Scenarios and usage guidelines

Three real, source-verified walkthroughs — pick the one that matches what you actually have available. Every command and output below was run against a live instance while writing this page (the hosted demo, or a freshly built self-host image); none of it is invented.

:::note What's shipped vs. what's described elsewhere All three scenarios below use existing data — the synthetic golden fixture, whether served by the hosted demo or seeded locally. They do not walk through registering your own evidence sources. Self-host operators can register local-path Git/docs/deployment/Jira sources or a live Jira project, then run collection or collection-and-reconciliation jobs. Live/network Git/docs/deployment sources are not implemented. See Evidence sources for the supported setup and limits. :::

Scenario A — Evaluate it in five minutes, zero install

Persona: a founder, pilot user, or evaluator who wants to see the concept before installing anything.

Preconditions: none — the hosted demo is public and read-only.

Starting point: https://horologium.horo.run/app/w/demo/products/acme-store

Steps:

1. Open the URL above. You land on Product map — every canonical entity (a capability, a change, a release, a deployment target) and relationship for a fictional company, acme/store.
2. Click the Refund window node (red — it has an open conflict). The Evidence drawer opens on the right.
3. Read the drawer top to bottom: Open findings lists documentation_conflict and released_not_live, both warn severity. Deployment reality shows beta: 2.0.0 and production: 1.8.0 — released, but not live everywhere. Claims shows three conflicting values for refund.window (14 days, 30 days, 30 days — two agree, one doesn't). Evidence lists the exact citations: a docs paragraph, a line range in refund_policy.py, and a Jira ticket description, each with its own observed timestamp.
4. Click Integrity in the top nav. You see the same two findings as a flat list, each still linking back to its subject.
5. Click Timeline in the top nav, then select Refund window from the dropdown. You see the ordered sequence of claim_opened / relationship_opened events that produced the state you just read — not a snapshot, the actual history.

Expected outcome: you can explain, with a citation for each part, why this one capability is simultaneously "documented as 14 days," "coded as 30 days," and "live on production at the older value" — three facts a single status field would have collapsed into one misleading "Done."

Verify success: you found the documentation_conflict finding and can name its two disagreeing evidence citations without asking anyone.

Gotchas: the data is entirely synthetic (acme/store is not a real company) — the data_class: "synthetic" field on GET /v1/workspace confirms this if you're scripting instead of clicking.

Cleanup: none — you didn't write anything; the hosted demo is read-only (HOROLOGIUM_READ_ONLY=true).

Deeper reference: Hosted demo walkthrough, Integrity states and the evidence model.

Scenario B — Self-host it and explore the same fixture locally

Persona: an engineer or approved design partner who wants to run the real artifact themselves, not just look at the hosted copy.

Preconditions: Docker with Compose v2; you have repository/artifact access (self-host is by invitation during this Alpha — see Public Alpha limitations if you don't have access yet).

Starting point: a clone of the private repository, or the artifact handed to you through your private channel.

Steps:

cd horologium
cp .env.example .env
# Edit .env: set POSTGRES_PASSWORD (hex, not base64 — see the file's own comment)
docker compose up -d

curl -s http://127.0.0.1:8080/healthz   # {"status":"ok"}
curl -s http://127.0.0.1:8080/readyz    # {"status":"ready","database":"reachable"}

Seed the same golden fixture the hosted demo runs (to register your own sources instead, see Evidence sources):

docker compose exec \
  -e HOROLOGIUM_DATABASE_URL="postgres://horologium:$(grep ^POSTGRES_PASSWORD .env | cut -d= -f2)@postgres:5432/horologium" \
  horologium-server /usr/local/bin/seed_golden_fixture

Open http://127.0.0.1:8080/app/ — the same dashboard as Scenario A, running on your own machine against your own Postgres.

Expected intermediate state: curl -s http://127.0.0.1:8080/v1/findings | jq '.items | length' returns 2.

Expected final outcome: a local Horologium instance with the identical documentation_conflict and released_not_live findings from Scenario A, reachable only from 127.0.0.1 (no auth exists yet in this Alpha — see Security, privacy and data boundaries before binding it anywhere else).

Verify success: curl -s http://127.0.0.1:8080/v1/deployment-targets | jq '.items | length' returns 2 (beta, production).

Failure/gotcha notes: a 0 from any of the counts above means the seed didn't run, or ran against the wrong database — see the self-host quickstart's troubleshooting section. Re-running the seeder against an already-seeded database mints duplicate rows — run it once per fresh volume.

Cleanup: docker compose down stops it; add docker volume rm horologium-selfhost_horologium-pgdata to also drop the seeded data.

Deeper reference: Self-host quickstart.

Scenario C — Ask a coding agent what's actually live, via MCP

Persona: a developer using Claude Code (or another MCP-capable client) who wants an agent to answer "is X live?" from Product Truth instead of guessing from a stale doc.

Preconditions: a running horologium-server (local from Scenario B, or the hosted demo — no credentials required either way).

Starting point: a terminal with claude on PATH.

claude mcp add horologium-demo \
  -e HOROLOGIUM_API_BASE_URL=https://horologium-demo-551243130607.us-central1.run.app \
  -- uv run --project python/horologium-mcp horologium-mcp
claude mcp list
# horologium-demo: ... - ✓ Connected

Inputs you supply: only HOROLOGIUM_API_BASE_URL — no token, no credential. The adapter is read-only and the demo has none of its own.

Steps — ask the agent: "Using the horologium-demo MCP server, is the refund-window capability live on production?"

Expected tool sequence (what the agent should do, and what you'll see if you watch its tool calls): list_entities with q="Refund" to resolve the capability, then get_entity for its claims, open findings, and per-target deployment reality in one response.

Expected final outcome: the agent reports the same two findings from Scenario A, each with a real citation — documentation_conflict (14 vs. 30 days) and released_not_live (on beta 2.0.0, production still 1.8.0) — not a hallucinated summary.

Verify success: ask the agent to call get_workspace first — it should report "data_class": "synthetic", confirming it knows this is demo data before quoting anything back to you.

Failure/gotcha notes: if tool calls return nothing useful, confirm HOROLOGIUM_API_BASE_URL actually points at a reachable, seeded server — curl its /healthz directly first.

Cleanup: claude mcp remove horologium-demo.

Deeper reference: MCP / coding-agent integration.

What do you give the other party? (summary)

Horologium isn't a handoff/exchange product, but every scenario above does involve pointing something at it. This is the complete list — nothing else is required, and nothing else should be asked for:

Scenario	What you supply	What you never need
A — hosted demo	Nothing (a public URL)	Any credential
B — self-host	POSTGRES_PASSWORD you generate yourself	An external API key
C — MCP	HOROLOGIUM_API_BASE_URL only	An API token, an auth header

Usage guidelines

Choosing a starting scenario. No install, no opinion yet → Scenario A. Evaluating self-host feasibility → Scenario B. Building an agent workflow → Scenario C (can run directly against the hosted demo, no self-host required first).

Minimal safe input. Never point HOROLOGIUM_DATABASE_URL or HOROLOGIUM_API_BASE_URL at anything containing real customer data during this Alpha — there is no authentication yet (see Security, privacy and data boundaries).

Production vs. demo behavior. The hosted demo is HOROLOGIUM_READ_ONLY=true — every write attempt (POST /v1/proposals) returns 403. A self-hosted instance defaults to read-write unless you set the same flag.

Limitations and sharp edges. These scenarios use fixture data and do not configure custom sources. See Evidence sources for which local and live providers can collect your own data, and the maturity table on What is Horologium?.

Troubleshooting. Start at the self-host quickstart's troubleshooting section for install-time issues, or Public Alpha limitations for everything else.

How a request reaches Product Truth

All three access paths in every scenario above read the exact same API — an agent through MCP sees precisely what the dashboard shows, because there is no second, MCP-specific interpretation (ADR-0009). The fixture line is an optional seed path; registered-source collection is supported for local Git/docs/deployment/Jira sources and live Jira. Live/network Git, docs, and deployment sources remain unsupported; see Evidence sources.