# Documentation strategy > Draft (2026-05-31). A **designed-in commitment**, not an afterthought — grounded in research on critically-acclaimed developer docs (Stripe, Twilio, the Rust Book, FastAPI, Cloudflare, Anthropic, Diátaxis, `llms.txt`, Google dev style guide). Governs the **shipped product docs** (authored as code lands); the planning docs (CONTEXT/PRD/ADRs/design docs) are internal and separate. ## The defining constraint: a dual audience spt-core's docs serve **two readers at once** — human developers *and* the **AI dev-agents that build integrations with it**. This is unusual and it is the design constraint: every artifact is authored **once in clean markdown** and served in **two depths** (human-rendered + agent-export). The agent layer is **first-class, not optional** — the strategic signal (Tailwind's docs traffic fell ~40% because assistants answer for it) is, for spt-core, *the goal*: make the agent layer so good that dev-agents integrate correctly on the first try. There is recursive fit here — the same kind of agent that spt-core *hosts* is the one that *reads its docs*. ## Principles (top techniques, prioritized for spt-core) 1. **Sub-10-minute killer quickstart** — runnable, deterministic, whole-working-thing-first, no placeholders. TTFHW ("time to first hello world") is the single most-cited conversion lever (~68% abandon trials over setup time). 2. **Diátaxis four-mode separation** — tutorial / how-to / reference / explanation, never mixed (mixing is the most-cited cause of confusing docs). 3. **Deterministic, real, copy-pasteable examples everywhere** — no `` placeholders; real values that run. Serves humans *and* agents. 4. **Dual-depth agent exports** — `llms.txt` (slim curated index) + `llms-full.txt` (full concatenated export), auto-generated in CI, plus markdown content negotiation (`.md` suffix / `Accept: text/markdown`) which cuts agent token use ~90% vs HTML. 5. **One canonical way to do X** — explicitly mark deprecated/alternate paths. Non-determinism is fatal for agents. 6. **Complete reference, auto-generated, all error variants** — rustdoc for the public SDK crates (`spt-proto`, `spt-runtime`, `spt-msg`) + a machine-readable manifest/contract schema. Generic placeholders in reference are a failure mode. 7. **Consistent conversational voice** — adopt the Google developer style guide: second person ("you"), active voice, knowledgeable-friend tone. 8. **Explain *why*, not just *what*** — conceptual docs + diagrams for the messaging model, the agent lifecycle states, instances/dormancy, and P2P topology. 9. **Stable, never-renamed anchors/URLs** — agents cache links. 10. **Docs-as-product, gated in CI** — generation (rustdoc, `llms.txt`, schema, CLI help) is part of the build so docs can never drift from code. Drift is the #1 most-cited docs failure; this kills it structurally. ## Information architecture — by capability vertical Organize by capability, each vertical carrying the same four Diátaxis modes internally (the Cloudflare pattern): **Messaging · Live-agent lifecycle · Terminal hosting · Networking (P2P + pairing) · Harness contract (manifest + `api`) · Instances · Shells · Self-update.** ## Killer quickstart targets (two, one per audience) - **Human dev:** two agents exchange a message end-to-end in **one command + minimal config**, < 10 min — the core primitive, whole-thing-first, then decomposed. - **Dev-agent integrator:** a minimal **adapter** that satisfies the manifest + `api` contract and drives one lifecycle operation — the "build a harness for spt-core" hello-world. ## Agent-consumable docs (spt-core specifics) - **`llms.txt` / `llms-full.txt`** — auto-emitted in CI; the slim index lets a tool answer quick questions, the full export feeds deep ingestion. - **Markdown content negotiation** + deterministic include/exclude tags so agent exports carry the canonical path and drop human-only narrative. - **Machine-readable manifest/contract schema** (JSON Schema) at a stable, discoverable path — agents validate their adapter manifests against it; the schema *is* documentation. - **MCP doc/resource server** — the standout fit, given the harness contract is the core integration surface. Expose the contract + reference as **deterministic, side-effect-free MCP resources** (same request → same result), giving integrating agents structured knowledge without RAG fuzziness. Highest-leverage agent-docs move for spt-core. - **CLI help as first-class agent docs** — agents primarily shell `spt api …`, so `spt --help` must be complete, exampled, and machine-readable (a `--json`/structured help mode). The CLI surface is a documentation surface. ## v0.1 deployment scope (grilled 2026-06-05) Deployed to GitHub Pages on `spt-releases` (ADR-0014; truth + CI generation stay in the source repo). **Tier 1 (ships with v0.1):** mental model/overview · human quickstart (install → two agents message) · adapter quickstart (via `mock-adapter`) · **harness contract vertical complete** (public manifest reference + full `spt api` reference + install-on-demand bootstrap pattern) · shell adapter getting-started (`spt-shell-notify` as the live example) · CLI reference generated from clap, CI-gated · **manifest JSON Schema (new code: schemars on the manifest types)** · root `llms.txt` + `llms-full.txt` CI-generated · rustdoc → Pages (no docs.rs — SDK crates are first-party-only while source is private). **Site generator: mdBook + custom theme CSS** (Rust-toolchain-coherent — one `cargo install mdbook` on the existing runners; the Rust Book IA this strategy copies *is* mdBook). Styling north star: **Astro Starlight** — copy its look/feel in the theme CSS, not its toolchain. Raw `.md` published alongside rendered pages (`/x.html` ↔ `/x.md`) for the agent-export convention; `llms.txt` / `llms-full.txt` / `manifest.schema.json` as static assets at site root. **Tier 2 (deferred, tracked):** remaining verticals' tutorials/how-tos (overview + reference stubs only in v0.1) · MCP doc server · `--help --json` mode (low marginal value over the generated CLI reference) · capstone tutorial · per-vertical `llms.txt` fan-out (root links pages directly until then). ## Anti-patterns to design against (most-cited failures) Doc/code drift (#1 — solved by CI gating); *what* without *why*; too much setup before first success; generic placeholders in reference; mixed Diátaxis modes; poor search/navigation; multiple non-canonical ways to do X (fatal for agents). ## CI commitments rustdoc, the manifest JSON Schema, `llms.txt`/`llms-full.txt`, and CLI help exports are **generated and checked in CI** — a doc-drift gate. Doc quality lives on the same footing as tests. --- ## Concrete templates (from firsthand artifacts) Extracted by fetching the *actual* artifacts (Cloudflare/Anthropic/Mintlify `llms.txt`, FastAPI/Stripe/Supabase quickstarts, the Rust Book TOC, Django/Diátaxis, Tokio/clap rustdoc, gh/Stripe CLI). Copy the *shape*. ### `llms.txt` — two-level (Cloudflare pattern, not Anthropic's flat dump) Root `llms.txt` is a **curated index that fans out to a per-vertical `llms.txt`**; `llms-full.txt` is CI-concatenated page bodies (Anthropic's overflowed a 10 MB fetch — generation-only, never hand-authored). ```markdown # spt-core A harness-independent core for an agent ecosystem: messaging, live-agent lifecycle, terminal hosting, P2P networking, a runtime-manifest harness contract. > Each capability links to its own llms.txt. Full concatenated docs: /llms-full.txt. > Machine-readable contract: /manifest.schema.json. Append `.md` to any doc URL > for raw markdown (~90% fewer tokens than HTML). ## Start here - [Quickstart: two agents exchange a message](…/quickstart/messaging.md): one command, <10 min. - [Quickstart: build an adapter](…/quickstart/adapter.md): minimal manifest + `api` contract. - [Mental model](…/concepts/overview.md): daemon, endpoints, instances, subnet. ## Capabilities (one bullet per vertical, each → its own llms.txt) - [Messaging](…/messaging/llms.txt): typed ops + file blobs; send / ring / ready. - [Live-agent lifecycle](…/lifecycle/llms.txt): skeleton → live → dormant → suspended. - … Terminal · Networking · Harness contract · Instances · Shells · Self-update ## Reference (auto-generated) - [spt-proto](https://docs.rs/spt-proto) · [spt-runtime](https://docs.rs/spt-runtime) · [spt-msg](https://docs.rs/spt-msg) - [CLI reference](…/cli/llms.txt) · [Manifest JSON Schema](…/manifest.schema.json) ``` ### Quickstart — whole-thing → run → verify → dissect (FastAPI), with a 2-path fork (Supabase) Zero placeholders; every value runs; complete working thing shown *before* explanation; audience fork at the top (spt-core has two readers); end with the Diátaxis trident. ```markdown # Quickstart — two agents exchange a message, end to end, <10 min. > Pick your path: **developer** (here) · **building an adapter / dev-agent** → /quickstart/adapter.md ## 1. Install (one line) curl -fsSL https://spt-core.dev/install.sh | sh Verify: spt --version # spt 0.1.0 (proto v1) ## 2. The whole working thing spt ready alice spt ready bob spt send bob --from alice "hello" ## 3. Run it spt poll --as bob # → from=alice op=message body="hello" ## 4. What just happened (dissect each line; note the daemon auto-started) ## Next how-to · concept · reference (Diátaxis trident) ``` ### Information architecture — two axes **Global sequence (Rust Book logic):** early runnable project, dependency-ordered concepts, capstone last. ``` 0 Getting started → 1 Quickstart (the early runnable project) → 2 Mental model → 3 Capability verticals (build-order) → 4 Capstone: build a non-CC adapter end-to-end ``` **Vertical ordering (dependency-sequenced):** `Messaging → Lifecycle → Terminal → Networking → Harness contract → Instances → Shells → Self-update` (messaging is the primitive the quickstart needs; self-update last because its no-termination invariant depends on the terminal/broker model.) **Per-vertical internal template (Django labels × Cloudflare ordering):** `Overview (why+diagram) · Quickstart/Tutorial · How-to guides · Reference (rustdoc+CLI+schema) · llms.txt` ### rustdoc — Tokio opener + out-document clap on errors Crate doc: **value-prop → "A tour of" → runnable example near top → feature flags → proto-compat note.** Every public error enum documents **per-variant cause → fix**; every fallible fn gets an `# Errors` section. ```rust //! # spt-runtime — one-sentence value prop. //! ## A tour of spt-runtime - [`Manifest`] · [`ApiCommand`] · [`Lifecycle`] //! ## Example (runnable, real values, near the top) //! ## Feature flags `net` (default) · `unstable` //! ## Wire-protocol compatibility interop by proto version, never crate version. ``` ```rust /// The manifest's `min_spt_core_version` exceeds this binary. /// **Fix:** update spt-core, or pin the adapter to a compatible release. VersionTooOld { required: Version, found: Version }, ``` ### CLI-as-docs — gh buckets + `--json` help mode Top-level `--help` groups by audience (`AGENT COMMANDS` send/ring/ready/poll · `HARNESS COMMANDS` api … · `NODE COMMANDS` pair/subnet/update). Per-command: **USAGE · FLAGS · EXAMPLES (real values) · LEARN MORE**. Beyond gh: a **`spt --help --json`** structured-help mode so dev-agents parse the contract without scraping, plus gh's uniform **`--json ` / `--jq` / `--template`** trio on any list command. The `--json` help export is generated + CI-gated alongside rustdoc and the schema.