docs: migrate read CLI to obsigna and fix stale default chain id#823
Merged
Conversation
The daemon's default chain id changed from the literal "default" to the current UTC date (and now auto-advances daily) in #735, but the docs were never updated. Multiple pages claimed receipts land on a chain named `default`, and several example commands passed `--chain-id default` — a chain that no longer exists, so the commands would fail as written. Verified against source: - verify -chain-id default: time.Now().UTC().Format("2006-01-02") (verify.go:77) - daemon ChainID default: same (obsigna-daemon/main.go:196) - show/verify-event: auto-detect the sole chain when -chain-id is unset - doctor: auto-detect active chain, fall back to today's date Fixes: cli-commands (verify + doctor flag defaults), end-to-end walkthrough (drops the non-existent --chain-id default; relies on single-chain auto-detect), quick-start, daemon-setup config sample, the three mcp-proxy integration pages, and the sdk-{go,py,ts} api-reference disclosure snippets.
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the documentation to match the daemon/CLI behavior introduced in #735, where the default chain id is the current UTC date (and no longer the literal default). This prevents documented commands like --chain-id default from failing and clarifies when --chain-id is required vs auto-detected.
Changes:
- Replaces stale references to the
defaultchain with the UTC-date-based default in CLI reference and getting-started docs. - Updates walkthrough commands to rely on single-chain auto-detection instead of passing a non-existent
--chain-id default. - Aligns MCP proxy and SDK API reference snippets with the new chain-id behavior.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| site/src/content/docs/sdk-ts/api-reference.mdx | Removes --chain-id default from receipt export comment. |
| site/src/content/docs/sdk-py/api-reference.mdx | Removes --chain-id default from receipt export comment. |
| site/src/content/docs/sdk-go/api-reference.mdx | Removes --chain-id default from receipt export comment. |
| site/src/content/docs/reference/cli-commands.mdx | Updates verify/doctor -chain-id default descriptions to date/auto-detect behavior. |
| site/src/content/docs/mcp-proxy/codex.mdx | Updates default chain-id description for daemon-managed chains. |
| site/src/content/docs/mcp-proxy/claude-desktop.mdx | Updates default chain-id description for daemon-managed chains. |
| site/src/content/docs/mcp-proxy/claude-code.mdx | Updates default chain-id description for daemon-managed chains. |
| site/src/content/docs/getting-started/quick-start.mdx | Updates verify commentary/prose to reflect date-based default chain id. |
| site/src/content/docs/getting-started/end-to-end.mdx | Removes --chain-id default usage and updates walkthrough narrative/output to date-based chains. |
| site/src/content/docs/getting-started/daemon-setup.mdx | Updates daemon.toml sample chain_id away from default. |
…igna The read/verify CLI was renamed agent-receipts -> obsigna (ADR-0030); since #821/ #822 the daemon and hook binaries and SDK package names were updated, but the docs still taught the deprecated `agent-receipts` shim everywhere. agent-receipts now only ships as a thin deprecation shim that forwards to obsigna and prints a stderr notice (daemon/cmd/agent-receipts/main.go), and obsigna is the primary CLI binary (daemon/.goreleaser.yaml). - All ~100 command invocations -> grouped canonical form: `obsigna receipt list/show/verify/verify-event` and `obsigna doctor`. Grouped form is required for consistency: `list` has no flat alias (`obsigna list` errors); the closed flat-alias set is only {verify, show} per ADR-0030. - cli-commands.mdx: renamed the `## agent-receipts` section to `## obsigna`, added a deprecation-shim note, and repointed all `#agent-receipts` anchors. - Install docs: `go install .../cmd/agent-receipts@latest` -> `.../cmd/obsigna@latest`; prose now names the `obsigna` CLI (brew + from-source). - Example list output: CHAIN column and `Chain <id>: VALID` prose now show the per-day UTC chain id (matching each receipt's date) instead of the stale `default`. Left unchanged: brew tap org-name (agent-receipts/tap/obsigna), GitHub repo links, the agent-receipts-daemon/-hook deprecation references, DIDs, data paths, brand name.
ojongerius
changed the title
default chain id to the per-day UTC default…kthrough - daemon-setup.mdx: the sample daemon.toml set chain_id to a fixed date; copy-pasting it would pin one chain and disable the per-day auto-advance. Comment it out with a note to omit it and rely on the per-day UTC default. - end-to-end.mdx: reword the 'you should see chain X' line so it isn't tied to one specific date.
ojongerius
added a commit
that referenced
this pull request
Jun 13, 2026
…t a receipts.db (#824) Follow-ups from the doc-e2e persona fan-out against the post-#823 docs: - cli-commands.mdx: #823 renamed the section heading and all command examples to obsigna but left the page's intro bullet list and the --db/--public-key blockquote still calling the read CLI `agent-receipts` (the deprecation shim). Rename both to `obsigna`, keeping a one-line note that `agent-receipts` still works as a shim. - dashboard/installation.mdx: the dashboard visualises an existing receipts.db but never creates one, and the docs gave a no-SDK reviewer no way to obtain one. Add a short note pointing at the daemon + an SDK/MCP-proxy emit path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Two related documentation fixes, both surfaced by the doc-e2e persona harness from #708 (the Theo/Python runner executed the documented journey and flagged stale CLI/chain wording):
agent-receiptsshim toobsigna. The CLI was renamedagent-receipts→obsigna(ADR-0030). Since docs: align SDK package names and stale cmd paths with what ships #821/docs: rename agent-receipts-daemon → obsigna-daemon; fold brew installs into the umbrella formula #822 the daemon/hook binaries and SDK package names were updated, but the docs still taughtagent-receiptseverywhere.agent-receiptsnow only ships as a thin deprecation shim that forwards toobsignaand prints a stderr notice (daemon/cmd/agent-receipts/main.go);obsignais the primary CLI binary (daemon/.goreleaser.yaml).defaultchain id to the per-day UTC default. The daemon default chain id changed from the literal"default"to the current UTC date — and now auto-advances daily — in feat(daemon): auto-advance chain ID on terminal tail; date-based default #735, but the docs were never updated. Several pages claimed receipts land on a chain nameddefault, and example commands passed--chain-id default, a chain that no longer exists.CLI migration
All ~100 command invocations moved to the grouped canonical form:
agent-receipts listobsigna receipt listagent-receipts show <seq>obsigna receipt show <seq>agent-receipts verifyobsigna receipt verifyagent-receipts verify-eventobsigna receipt verify-eventagent-receipts doctorobsigna doctorGrouped form is required for consistency:
listhas no flat alias (obsigna listerrors); the closed flat-alias set is only{verify, show}per ADR-0030.reference/cli-commands.mdx: renamed the## agent-receiptssection to## obsigna, added a deprecation-shim note, repointed all#agent-receiptsanchors.go install …/cmd/agent-receipts@latest→…/cmd/obsigna@latest; prose now names theobsignaCLI (brew + from-source).Left unchanged (not the read CLI): brew tap org-name (
agent-receipts/tap/obsigna), GitHub repo links, theagent-receipts-daemon/-hookdeprecation references, DIDs (did:agent-receipts-daemon:local), data paths (~/.local/share/agent-receipts/), and the brand name "Agent Receipts".Chain-id correction — verified against source
verify -chain-idYYYY-MM-DDdaemon/internal/verifycli/verify.go:77ChainIDdaemon/cmd/obsigna-daemon/main.go:196receipt show/verify-eventdaemon/internal/showcli/show.go:63doctor -chain-iddaemon/internal/doctorcli/doctor.go:120,630Origin of the drift: #735 (
ChainID: "default"→time.Now().UTC().Format("2006-01-02")).cli-commands.mdx:verify+doctor-chain-iddefault descriptions.getting-started/end-to-end.mdx: walkthrough no longer runs the non-existent--chain-id default(relies on single-chain auto-detect); example outputs/prose show the date-based chain.quick-start.mdx,daemon-setup.mdxconfig sample, the mcp-proxy integration pages, and SDK api-reference snippets.obsigna receipt listoutput tables: theCHAINcolumn andChain <id>: VALIDprose now show the per-day UTC chain id (matching each receipt's date) instead of the staledefault.Out of scope
daemon-process-separation,openclaw-plugin-deep-dive) — dated point-in-time narratives, intentionally left.XDG_DATA_HOMEfindings — live in the separateagent-receipts/dashboardrepo.