mirror of
https://github.com/block/buzz.git
synced 2026-08-18 06:50:31 +02:00
npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl
23f75dac90
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>
2.5 KiB
2.5 KiB
Design Documents Index
Engineering design records and formal specifications living directly under docs/. Like the NIPs, they stay at their current paths (external references from code, tests, and Helm templates) — this page is the index.
These are design records, not user documentation: they capture the reasoning behind a feature at the time it was built. Where a NIP supersedes one, the NIP is normative.
Design records
| Document | Status | Summary |
|---|---|---|
bridge-channel-window.md |
superseded by NIP | Engineering record of the /query channel-window extension. NIP-CW is the canonical spec — read this only for implementation history. |
MCP_DRIVEN_HOOKS.md |
active | MCP-driven lifecycle hooks: MCP tools the agent calls at lifecycle points (see also the agents guide). |
multi-tenant-relay.md |
draft | Formal specification for a multi-tenant Buzz relay (first-class communities). Prose companion to the TLA+ model below. |
multi-tenant-conformance.md |
active | Source-vs-model checklist for adding communities without changing single-community behavior. Pairs with crates/buzz-conformance — see its honest LIMITS.md and known limitations. |
git-on-object-storage.md |
draft | Formal specification for serving git refs over object storage. |
mesh-llm-local-build.md |
active | Build prerequisites for the embedded mesh-llm native layer (linked into relay and desktop binaries). |
Formal specifications (docs/spec/)
Machine-checked models backing the multi-tenant and git-on-object-storage designs:
| File | Tool | Models |
|---|---|---|
MultiTenantRelay.tla / .cfg |
TLA+ (TLC) | Multi-tenant relay ingest/read confinement — the spec the conformance gate checks traces against |
MultiTenantAuth.spthy |
Tamarin | Multi-tenant authentication protocol |
GitOnObjectStore.tla / .cfg |
TLA+ (TLC) | Git refs over object storage |
The conformance harness validates executions against the TLA+ spec at runtime — it is not a proof. See known limitations.