docs(site): rewrite Quick Start to drive against the daemon#625
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the documentation Quick Start to align with ADR-0022’s canonical “daemon-mediated signing” deployment shape, ensuring readers use the daemon path first and verify the resulting receipt chain via the CLI.
Changes:
- Reorients Quick Start to daemon-first flow for Python, TypeScript, and Go (Install → Start daemon → Emit → Verify).
- Adds explicit
agent-receipts verifysteps to confirm receipt persistence and chain/signature integrity. - Demotes in-process signing to a clearly-marked appendix with a “Not for production” warning.
7 tasks
ojongerius
added a commit
that referenced
this pull request
May 25, 2026
Introduces `docs/operations/current.md` as the curated active-subgraph view of in-flight, blocked, and next work. Reduces ~77 open issues to ~15 active nodes with editorial overlay (closures, blocked-on-Otto framing, conflicts). Adds an "Operational state" pointer to AGENTS.md so agents and humans open this file at session start. Initial content includes the post-ADR-0021/0022 merge state with a verification pass: #597 and #614 closed, ADR-0022 PR #619 recorded, and the four closure-1 implementation PRs (#621/#623/#624/#625) recorded as in-flight rather than farmable.
5 tasks
) Lead every SDK section (Python, TypeScript, Go) with the daemon-mediated signing path per ADR-0022 D1: the SDK emits tool-call events over a Unix socket and the agent-receipts-daemon holds the Ed25519 key. Each section follows Install -> Start the daemon -> Emit -> Verify and ends with `agent-receipts verify` so the reader confirms the receipt landed. In-process signing is demoted to a clearly-labeled tutorial/testing-only appendix carrying the ADR-0022 D2 "Not for production" note. Replaces the stale attest_protocol imports. The page's posture now matches the homepage and daemon-setup, closing SITE-P3. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp
Reorder the intro SDK list to Python/TypeScript/Go to match section order, check the TypeScript emit() return value, and drop the unused receipt_hash from the in-process appendix example. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp
Drop the @Alpha dist-tag from the TypeScript install (DaemonEmitter ships in stable 0.10.0; @Alpha resolves to an older prerelease that still exports the old Emitter name). Wrap the TypeScript example in an async main() with try/finally so it is copy/paste runnable and always closes the socket. Ignore the Go Close() error in the deferred call to stay errcheck-clean. Note AGENTRECEIPTS_CHAIN_ID alongside the DB and public-key overrides in every verify step. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp
ojongerius
force-pushed
the
claude/determined-ride-G8rr0
branch
from
e7388e5 to
c1a81cd
Compare
Adds .catch() with process.exitCode=1 to surface emit() errors deterministically across Node versions (Copilot review on #625).
This was referenced May 26, 2026
ojongerius
added a commit
that referenced
this pull request
May 26, 2026
* docs(site): rewrite Quick Start to drive against the daemon (closes #616) Lead every SDK section (Python, TypeScript, Go) with the daemon-mediated signing path per ADR-0022 D1: the SDK emits tool-call events over a Unix socket and the agent-receipts-daemon holds the Ed25519 key. Each section follows Install -> Start the daemon -> Emit -> Verify and ends with `agent-receipts verify` so the reader confirms the receipt landed. In-process signing is demoted to a clearly-labeled tutorial/testing-only appendix carrying the ADR-0022 D2 "Not for production" note. Replaces the stale attest_protocol imports. The page's posture now matches the homepage and daemon-setup, closing SITE-P3. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): address Quick Start review feedback Reorder the intro SDK list to Python/TypeScript/Go to match section order, check the TypeScript emit() return value, and drop the unused receipt_hash from the in-process appendix example. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): address second-round Quick Start review feedback Drop the @Alpha dist-tag from the TypeScript install (DaemonEmitter ships in stable 0.10.0; @Alpha resolves to an older prerelease that still exports the old Emitter name). Wrap the TypeScript example in an async main() with try/finally so it is copy/paste runnable and always closes the socket. Ignore the Go Close() error in the deferred call to stay errcheck-clean. Note AGENTRECEIPTS_CHAIN_ID alongside the DB and public-key overrides in every verify step. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): handle main() rejection in TS Quick Start snippet Adds .catch() with process.exitCode=1 to surface emit() errors deterministically across Node versions (Copilot review on #625).
ojongerius
added a commit
that referenced
this pull request
May 26, 2026
* docs(site): rewrite Quick Start to drive against the daemon (#625) * docs(site): rewrite Quick Start to drive against the daemon (closes #616) Lead every SDK section (Python, TypeScript, Go) with the daemon-mediated signing path per ADR-0022 D1: the SDK emits tool-call events over a Unix socket and the agent-receipts-daemon holds the Ed25519 key. Each section follows Install -> Start the daemon -> Emit -> Verify and ends with `agent-receipts verify` so the reader confirms the receipt landed. In-process signing is demoted to a clearly-labeled tutorial/testing-only appendix carrying the ADR-0022 D2 "Not for production" note. Replaces the stale attest_protocol imports. The page's posture now matches the homepage and daemon-setup, closing SITE-P3. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): address Quick Start review feedback Reorder the intro SDK list to Python/TypeScript/Go to match section order, check the TypeScript emit() return value, and drop the unused receipt_hash from the in-process appendix example. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): address second-round Quick Start review feedback Drop the @Alpha dist-tag from the TypeScript install (DaemonEmitter ships in stable 0.10.0; @Alpha resolves to an older prerelease that still exports the old Emitter name). Wrap the TypeScript example in an async main() with try/finally so it is copy/paste runnable and always closes the socket. Ignore the Go Close() error in the deferred call to stay errcheck-clean. Note AGENTRECEIPTS_CHAIN_ID alongside the DB and public-key overrides in every verify step. https://claude.ai/code/session_01FCwvdzkbcG574nCU4h8Zwp * docs(site): handle main() rejection in TS Quick Start snippet Adds .catch() with process.exitCode=1 to surface emit() errors deterministically across Node versions (Copilot review on #625). * docs(site): fix stale APIs and macOS socket path in Daemon Setup (#628) * docs(site): fix stale APIs and macOS socket path in Daemon Setup Brings `daemon-setup.mdx` into line with the shipped SDKs and `daemon/README.md`: - TypeScript snippets use `DaemonEmitter` (renamed from `Emitter` in @agnt-rcpt/sdk-ts 0.10.0). - TypeScript install drops `@alpha` — `DaemonEmitter` ships on the default tag; `@alpha` still resolves to the old `Emitter` name. - Go snippets use `emitter.NewDaemon` (current constructor; `emitter.New` no longer exists). - macOS default socket path moves from `$TMPDIR/agentreceipts/...` to `$XDG_DATA_HOME/agent-receipts/events.sock` (matches the daemon's actual resolver; `$TMPDIR` is not inherited by GUI-spawned processes, so the old path made the handshake fail silently on macOS — issue #545). Updates the troubleshooting `ls` example to the new macOS path and fixes one prose reference to `New()` → `NewDaemon()` in the same paragraph as the renamed snippets. Closes #627. * docs(site): address Copilot review on #628 - "Connect your emitters" paragraph: drop the incorrect claim that the Go SDK ignores `AGENTRECEIPTS_SOCKET` on non-macOS/Linux platforms. `emitter.DefaultSocketPath` consults the env var first on every host; `NewDaemon()` only errors when neither the env var nor an explicit socket-path option supplies a path. - Troubleshooting `ls`: switch the macOS example to `~/.local/share/agent-receipts/events.sock` (the absolute default fallback) instead of `${XDG_DATA_HOME:-...}`. The daemon and SDKs ignore a non-absolute `XDG_DATA_HOME` and fall back, so the previous shell expansion could point at the wrong path when the env var is set but invalid — same trap the verify section already avoids. * docs(site): clarify language scope + XDG_DATA_HOME caveat (Copilot round 2) - "Connect your emitters" paragraph: drop the Go-specific `NewDaemon()` reference, since the surrounding text applies to all SDKs. Use "the emitter constructor" and mention `WithSocketPath` only as a Go example so TS/Python readers aren't misdirected. - Troubleshooting: add a one-line caveat noting that the macOS `ls` example assumes the default fallback path; users with a custom `AGENTRECEIPTS_SOCKET` or absolute `XDG_DATA_HOME` should check their own path. Mirrors the caveat the verify section already carries. * ci: verify README code snippets against the SDK artifacts Adds a release-blocking gate that extracts the SDK quick-start snippets from the user-facing READMEs and compiles / type-checks each one — catching the recurring papercut (#593, #594) where a snippet calls a non-existent API, imports a wrong module path, or drifts behind a published rename. - scripts/readme_snippets/: a dependency-free Python harness. extract.py (pure, unit-tested) parses fenced blocks and assembles compilation units; check.py scaffolds a throwaway project and runs go build / tsc --noEmit / mypy against either the in-tree SDK (--source local) or the published artifact (--source published). - Default-in: every SDK-importing fenced block is checked, so a newly added snippet is covered without annotation. snippet-check directives (continues, skip) handle dependent and illustrative blocks. - readme-snippets.yml runs the in-tree check on every README-touching PR; the publish-* workflows run the published check at release time. Fixes drift the gate caught: - sdk/go/README.md used the stale module path github.com/agent-receipts/sdk-go instead of github.com/agent-receipts/ar/sdk/go (install + imports). - Root README Python quick-start passed action as a dict where CreateReceiptInput expects ActionInput; now uses ActionInput(...). Closes #595 https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu * ci: fail loudly on chained Go snippets instead of dropping them Self-review caught a silent gap: a `continues` directive before a Go block would render only the first block in the chain and silently drop the rest, leaving a snippet unchecked — the exact failure this gate exists to prevent. Go snippets are standalone, so raise a clear error instead. https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu * ci: address snippet-harness review feedback - TS check now reads typescript / @types/node from sdk/ts/package.json (the SDK builds on ~6.0.2 / ^25), so the gate matches the published .d.ts instead of an arbitrary pinned major. - Fail fast (exit 2) when a README path doesn't exist, instead of silently dropping it and reporting success — a path typo must not disable the gate. - Pin mypy (==2.1.0) so the gate is deterministic across runs. - Hoist Go imports verbatim so aliases (foo "pkg"), blank imports (_ "pkg"), and inline comments survive the package-shim rewrite. https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu * ci: address second-pass snippet-harness review feedback - Clear a pending snippet-check directive when an unrecognised one follows, so it can't leak onto the next fenced block. - Pin the temp TS project's typescript / @types/node to exact versions (strip the ^/~ range) so resolution is deterministic without a lockfile. - Use a conventional throwaway Go module path (example.com/readme-snippets). https://claude.ai/code/session_016jA1Qu4hJK8mnsjCMDFPFu
ojongerius
added a commit
that referenced
this pull request
May 26, 2026
ojongerius
added a commit
that referenced
this pull request
May 26, 2026
* chore: remove committed binary and expand .gitignore Removes the accidentally committed agent-receipts Mach-O binary and adds /agent-receipts, /bin/, and /daemon/bin/ to .gitignore so built binaries cannot be committed again. * docs(ops): update current.md for 2026-05-26 Mark closure-1 nodes shipped (#621/#623/#624/#625/#628), add daemon-setup-stale-api and py-readme-daemon-refresh nodes, record #632/#633/#634, note #592 trusted-publishing blocker, refresh Next farmable section.
11 tasks
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.
Summary
Rewrites
site/src/content/docs/getting-started/quick-start.mdxto lead with the daemon-mediated signing path for all three SDK sections, per ADR-0022. Closes the SITE-P3 finding, where the Quick Start still taught in-process signing as the recommended path — contradicting the homepage, which describes in-process as the insecure posture.agent-receipts verifyso the reader confirms the receipt landed, not just thatemitreturned (closes the confirmation-path gap, PY-P14 / GO-P10).:::dangeraside.attest_protocolimports — replaced withagent_receipts.The page's posture now matches the homepage and
daemon-setup.mdx.API-naming note
The TS/Go emit examples use the actual shipped SDK API —
DaemonEmitter(TS) andemitter.NewDaemon(Go) — so the code runs against current artifacts.daemon-setup.mdxcurrently teachesnew Emitter()(TS) andemitter.New()(Go), which are type-only/non-existent in the current SDKs. That discrepancy is left for a separate follow-up rather than fixed here (this PR touches onlyquick-start.mdx).Test plan
grep -ri "attest_protocol" quick-start.mdx→ zero matchesin-processmention is the appendix heading ("tutorial and testing only"), with the "Not for production" note immediately below:::directives balancedrehype-mermaidstep needs a Playwright browser, which the sandbox network policy blocks — MDX compiles past parsing; mermaid block is structurally unchanged from the prior page)References
docs/adr/0022-canonical-deployment-shape.mddocs/audit/2026-05-24-quickstart-and-site-synthesis.mdCloses #616