Skip to content

docs: comprehensive README accuracy pass — verified against every line of code#233

Open
tlongwell-block wants to merge 1 commit intomainfrom
tyler/improve-readme
Open

docs: comprehensive README accuracy pass — verified against every line of code#233
tlongwell-block wants to merge 1 commit intomainfrom
tyler/improve-readme

Conversation

@tlongwell-block
Copy link
Copy Markdown
Collaborator

Why

The README had accumulated inaccuracies as the codebase grew. Features were claimed that aren't implemented, crates existed that weren't documented, env vars were missing from the config table, and descriptions had drifted from reality.

How this was verified

13 AI delegates each read every single line of their assigned crate(s) (~72,000 lines total across all 17 crates) and compared against the README. Findings were synthesized, applied, then crossfire-reviewed through 4 rounds of adversarial review (codex CLI + opus subagents) until both approved at 9–10/10.

What changed

+59 / −29 lines — README.md only, no code changes.

Critical fixes

  • "Approval gates" removed as shipped featureRequestApproval always fails at runtime with "not yet implemented — see WF-08". Now marked (approval gates: planned).
  • NIP-29 status corrected — kinds 9021 (join request) and 9022 (leave request) are fully implemented; only 9009 remains deferred. Previously said "9009, 9021 deferred".
  • Architecture diagram updated — added S3/MinIO as fourth backend dependency; fixed relay label from "admin API" (doesn't exist) to "channel/DM/media/workflow REST"; expanded Postgres/Redis labels.

Supported NIPs table

Added 6 implemented NIPs that were missing from the table:

  • NIP-05 (identity verification — /.well-known/nostr.json)
  • NIP-09 (event deletion — kind:5 handling)
  • NIP-10 (thread conventions — e/p tag resolution)
  • NIP-17 (private DMs — gift-wrap kind:1059)
  • NIP-50 (search capability — Typesense-backed)
  • NIP-98 (HTTP Auth — partial, POST /api/tokens bootstrap only)

Crate Map

  • Added 3 undocumented crates: sprout-sdk, sprout-media, sprout-cli with new "Shared libraries" section
  • Fixed all 12 existing crate descriptions against actual code:
    • sprout-relay: "admin routes" → "channel/DM/media/workflow REST, Blossom media upload"
    • sprout-core: added zero-I/O constraint, Schnorr verification, channel/presence types
    • sprout-db: "events, channels, API tokens" → lists all 9 data domains
    • sprout-auth: added NIP-98, rate limiting
    • sprout-pubsub: added presence tracking, typing indicators, rate limiting
    • sprout-workflow: lists all 5 trigger types, removes false "approval gates" claim
    • sprout-mcp: dropped hard tool count (code has 43/44 discrepancy), lists actual tool categories
    • sprout-huddle: added webhook verification, in-memory session tracking
    • sprout-audit: "hash chain" → "SHA-256 hash chain"
    • sprout-test-client: lists 8 E2E suite names

Configuration table

  • Added 17 missing env vars with defaults verified against config.rs: CORS, health port, metrics, connection limits, media/S3, pubkey allowlist, send buffer, UDS, JWKS URI
  • Added SPROUT_TOOLSETS — critical for MCP operators (controls which of the 7 toolsets are active)
  • Added SPROUT_RELAY_PUBKEY — required by sprout-proxy, also used as fallback auth by sprout-workflow
  • Fixed SPROUT_PUBKEY_ALLOWLIST description — narrowed to NIP-42 pubkey-only scope (API token and Okta JWT bypass)

MCP Tools section

  • Documented the toolset system: default (25 tools active out of the box), channel_admin, dms, canvas, workflow_admin, identity, forums
  • Added SPROUT_TOOLSETS=all guidance

Development section

  • Added sprout-cli to "Running a specific crate" examples

What's NOT in this PR

  • No code changes — README only
  • Detailed workflow YAML examples (belongs in WORKFLOWS.md)
  • Rate limiting tier details (operational, belongs in SECURITY.md)
  • Template variable syntax (belongs in AGENTS.md)

Verified every claim against source code via 13 parallel code-reading
delegates (one per crate, ~72k lines total) + 4 rounds of crossfire
review (codex CLI + opus subagents).

Supported NIPs table:
- Add NIP-05, NIP-09, NIP-10, NIP-17, NIP-50, NIP-98 (all implemented)
- Fix NIP-29 status: 9021-9022 are implemented, only 9009 deferred

Why Sprout table:
- Fix 'approval gates' claim: not implemented (WF-08), marked planned

Architecture diagram:
- Add S3/MinIO as fourth backend dependency
- Fix relay label: channel/DM/media/workflow REST (not 'admin API')
- Expand Postgres/Redis labels to reflect actual data

Crate Map:
- Add sprout-sdk, sprout-media, sprout-cli (existed but undocumented)
- Fix all 12 crate descriptions against actual code
- sprout-workflow: list all 5 trigger types, remove 'approval gates'
- sprout-relay: add Blossom media upload
- sprout-pubsub: add presence, typing, rate limiting
- sprout-core: add zero-I/O, Schnorr verification, channel types
- sprout-auth: add NIP-98, rate limiting
- sprout-db: list actual data domains (not just 3 of 13)
- sprout-mcp: drop hard tool count (code has 43/44 discrepancy)
- sprout-test-client: list 8 E2E suite names

Configuration table:
- Add 17 missing env vars with verified defaults from config.rs
- Add SPROUT_TOOLSETS (critical for MCP operators)
- Add SPROUT_RELAY_PUBKEY (required by proxy + workflow fallback)
- Fix SPROUT_PUBKEY_ALLOWLIST description (NIP-42 pubkey-only scope)

MCP Tools section:
- Document toolset system (default/channel_admin/dms/canvas/etc.)
- Note 25 tools active by default, SPROUT_TOOLSETS=all for full suite

Development section:
- Add sprout-cli to 'Running a specific crate' examples
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant