mirror of
https://github.com/block/buzz.git
synced 2026-11-03 07:51:22 +00:00
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>
29 lines
2.5 KiB
Markdown
29 lines
2.5 KiB
Markdown
# 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`](../bridge-channel-window.md) | superseded by NIP | Engineering record of the `/query` channel-window extension. **[NIP-CW](../nips/NIP-CW.md) is the canonical spec** — read this only for implementation history. |
|
|
| [`MCP_DRIVEN_HOOKS.md`](../MCP_DRIVEN_HOOKS.md) | active | MCP-driven lifecycle hooks: MCP tools the agent calls at lifecycle points (see also the [agents guide](../guides/agents.md)). |
|
|
| [`multi-tenant-relay.md`](../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`](../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`](../../crates/buzz-conformance/LIMITS.md) and [known limitations](known-limitations.md). |
|
|
| [`git-on-object-storage.md`](../git-on-object-storage.md) | draft | Formal specification for serving git refs over object storage. |
|
|
| [`mesh-llm-local-build.md`](../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`](../spec/MultiTenantRelay.tla) / [`.cfg`](../spec/MultiTenantRelay.cfg) | TLA+ (TLC) | Multi-tenant relay ingest/read confinement — the spec the conformance gate checks traces against |
|
|
| [`MultiTenantAuth.spthy`](../spec/MultiTenantAuth.spthy) | Tamarin | Multi-tenant authentication protocol |
|
|
| [`GitOnObjectStore.tla`](../spec/GitOnObjectStore.tla) / [`.cfg`](../spec/GitOnObjectStore.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](known-limitations.md#conformance-gate).
|