docs: full documentation implementation (structure + content)#1600
docs: full documentation implementation (structure + content)#1600baxen wants to merge 2 commits into
Conversation
Add the docs/ skeleton for the full docs implementation: getting-started, architecture, guides, reference, and vision sections, with a nav/TOC home page. Every page is a stub carrying its heading outline and pointers to the source material to be migrated in Phase 2 (content). docs/nips/, docs/spec/, and the loose design docs stay at their current paths (55 references from code, tests, and migrations outside docs/); reference/nips.md and reference/design-docs.md index them instead. Root GitHub-convention files are untouched. ARCHITECTURE/NOSTR/TESTING/ RELEASING/VISION* remain in place this phase and will become pointer files in Phase 2. Co-authored-by: npub19zza5yyr075j4vvlg2drsh2xe0xy3dqxhfchlgtw8vryglrry3gq8q7tzk <2885da10837fa92ab19f429a385d46cbcc48b406ba717fa16e3b06447c632450@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub19zza5yyr075j4vvlg2drsh2xe0xy3dqxhfchlgtw8vryglrry3gq8q7tzk <2885da10837fa92ab19f429a385d46cbcc48b406ba717fa16e3b06447c632450@sprout-oss.stage.blox.sqprod.co>
Fill all 31 stub pages scaffolded in Phase 1 with content migrated and verified from the root docs, crate READMEs, and source code: - getting-started/ (3): installation, quickstart, local relay (TESTING.md) - architecture/ (8): ARCHITECTURE.md §1–§8, one page per section - guides/ (9): development, testing, agents, workflows, self-hosting, nostr-clients (operational half of NOSTR.md), adding-event-kinds, adding-api-endpoints, releasing - reference/ (5): CLI reference verified against buzz --help and crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted), configuration, known-limitations (ARCHITECTURE §9 + conformance LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical), design-docs index - vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational banners and rewritten links Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get pointer notes marking docs/ as canonical; deletion is a follow-up. All relative links in the new tree verified to resolve. Known limitations are documented honestly, never papered over: rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README drift, one-line GOVERNANCE.md. Note: pre-commit sadscan findings reviewed as false positives (dev-default postgres URI and NIP-OA test vectors, both already on origin/main). Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 23f75dac90
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | `add_reaction` | React to the trigger message | ✅ | | ||
| | `call_webhook` | HTTP POST to an external URL — SSRF-protected, redirects disabled, 1 MiB response cap | ✅ | | ||
| | `request_approval` | Suspend and wait for approval (`from:`, `message:`, `timeout:` default 24h) | ⚠️ not wired end-to-end (WF-08) | | ||
| | `delay` | Pause execution (`duration:`, max 300 seconds) | ✅ | |
There was a problem hiding this comment.
For workflow definitions that set delay.duration between 271 and 300 seconds, this table says the step is valid, but execute_action in crates/buzz-workflow/src/executor.rs defines MAX_DELAY_SECS: u64 = 270 and returns InvalidDefinition for larger values. Users following the documented 300-second limit will get failing runs; document 270 seconds or change the executor.
Useful? React with 👍 / 👎.
| | `BUZZ_ACP_MCP_COMMAND` | no | empty | Optional MCP server binary provided to the agent subprocess | | ||
| | `BUZZ_ACP_IDLE_TIMEOUT` | no | `620` | Max seconds of agent silence before cancelling a turn | | ||
| | `BUZZ_ACP_MAX_TURN_DURATION` | no | `3600` | Absolute wall-clock cap per turn | | ||
| | `BUZZ_API_TOKEN` | no | — | Required if the relay enforces token auth | |
There was a problem hiding this comment.
For deployments where a reader expects token-based auth, this tells operators to set BUZZ_API_TOKEN, but buzz-acp has no CLI/config field that consumes it and the WebSocket auth handler is pure NIP-42/NIP-OA rather than bearer-token based. Setting this variable will not authenticate the harness, so agents will still be rejected unless their Nostr key is a relay member or carries a valid NIP-OA owner tag.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
(Pinky, agent, on behalf of Wes.) This one is incorrect — BUZZ_API_TOKEN is consumed on main:
crates/buzz-workflow/src/executor.rs:898—std::env::var("BUZZ_API_TOKEN")read directly.crates/buzz-acp/src/config.rs:667— legacyBUZZ_ACP_API_TOKENis propagated intoBUZZ_API_TOKEN(so buzz-acp deployments do interact with it).crates/buzz-cli/Cargo.toml:19— clap env auto-wiring for the CLI.
The configuration.md row is legitimate and should stay. The wording could arguably clarify which components consume it, but removing it would be a regression.
wesbillman
left a comment
wesbillman
left a comment
There was a problem hiding this comment.
Review on behalf of Wes (posted by Pinky, agent).
High-quality docs work — the structure, the honest known-limitations.md, the aspirational banners on vision docs, and the decision to leave docs/nips/ + docs/spec/ in place (55 in-tree references) are all right. I independently re-verified: 0 broken relative links across all 42 files in this PR (the broken links under docs/nips/ are pre-existing and untouched here), and the workflow-schema (diff_posted, interval:) and CLI exit-code claims check out against source.
Requesting changes for three small accuracy items — all quick:
-
Delay cap: 300s → 270s (
docs/guides/workflows.md, delay row).execute_actionincrates/buzz-workflow/src/executor.rssetsMAX_DELAY_SECS: u64 = 270and returnsInvalidDefinitionabove it. As written, a user following the doc hits a rejection. (Codex's inline comment on this is correct.) -
CLI reference is stale on arrival. The branch is ~48 commits behind; #1616 (community moderation Phase 1) added a
moderationcommand group after your branch point, so main now ships 19 groups, not the documented 18 — which also dates the accuracy note's "18 groups / 87 subcommands" claim. Please rebase and add themoderationsection (or at minimum note the gap). -
Push back on Codex's other P2 —
BUZZ_API_TOKENis NOT unused. It's consumed in three places on main:crates/buzz-workflow/src/executor.rs:898reads it,crates/buzz-acp/src/config.rs:667propagates legacyBUZZ_ACP_API_TOKENinto it, andbuzz-cliauto-wires it via clap's env support (crates/buzz-cli/Cargo.toml). Theconfiguration.mdrow is legitimate; please don't remove it. I've replied on that thread.
With those addressed this is an easy approve — happy to re-review immediately.
2 participants
Summary
Full docs implementation for Buzz: a new
docs/tree with a Diátaxis-style split (getting started → understand → do → look up), migrating and verifying ~5,400 lines of existing root-level documentation. Two commits:cfd16deb— structure (Phase 1): information architecture + 31 stub pages with per-page outlines and source pointers.23f75dac— content (Phase 2): all 31 pages written, verified against code where applicable.What is in the tree
getting-started/architecture/guides/reference/buzz --help+crates/buzz-cli/src(18 groups / 87 subcommands, exit codes 0-5), configuration, known-limitations, NIPs index (NIP-CW canonical), design-docs indexvision/Verification done
crates/buzz-workflow/src/schema.rs— corrected ARCHITECTURE.md drift (5 trigger types incl.diff_posted;schedulesupportsinterval:as well ascron:).reference/known-limitations.md(rate limiting unenforced, WF-07/WF-08 workflow stubs, CLI README drift, one-line GOVERNANCE.md), cross-linked from affected pages.main; noted as false positives in the commit message.Deliberate decisions
docs/nips/,docs/spec/, and loose design docs are NOT moved — 55 references from code, tests, migrations, and Helm templates point at those paths.reference/nips.mdandreference/design-docs.mdindex them in place. Path migration is a candidate follow-up with reference rewrites.docs/canonical. Deleting them is a follow-up decision.Follow-ups (not in this PR)
docs/is trusted.docs/nips/+docs/spec/paths (requires rewriting 55 external references).GOVERNANCE.md.Coordinated by fable00; structure by fable02; content by fable01. Requested by @baxen in Buzz demo-channel.