<task-notification>
<task-id>abffd48b0b8324c0f</task-id>
<tool-use-id>toolu_01WGP9rpvKn6TEApKuLzQuZR</tool-use-id>
<output-file>C:\Users\decid\AppData\Local\Temp\claude\C--Users-decid-Documents-projects-spt-core\b494f5e6-5b4d-4145-aaaa-5585e1168377\tasks\abffd48b0b8324c0f.output</output-file>
<status>completed</status>
<summary>Agent "Research acclaimed docs techniques" completed</summary>
<result>I now have comprehensive, well-cited material across all five sections. Let me compile the final report.

---

# What Makes Developer Documentation Critically Acclaimed — Research Report for `spt-core`

A research synthesis grounded in cited developer sentiment, style guides, and the emerging practice of agent-consumable docs. Recommendations tailored to `spt-core`'s dual human + AI-agent audience appear in Section 5.

---

## 1. Exemplars — docs developers actually praise

| # | Project | Why devs love it (one line) | Source |
|---|---------|------------------------------|--------|
| 1 | **Stripe** | The gold-standard three-column layout (nav / explanation / live runnable code) that injects *your own* test API keys into samples; docs treated as a product, even baked into the engineering career ladder. | [apidog teardown](https://apidog.com/blog/stripe-docs/), [Moesif teardown](https://www.moesif.com/blog/best-practices/api-product-management/the-stripe-developer-experience-and-docs-teardown/) |
| 2 | **Twilio** | Task-oriented structure organized around real jobs ("Send a message", "Record a call") with runnable, multi-language examples — you build, not just read. | [Nordic APIs](https://nordicapis.com/5-examples-of-excellent-api-documentation/), [apidog](https://apidog.com/blog/twilios-api-the-other-gold-standard-and-why-its-stripes-true-equal/) |
| 3 | **The Rust Book** | The community reference standard for teaching a hard systems language gently; the de-facto "best technical docs" recommendation in r/rust and r/learnprogramming. | (community consensus, Rust Book = `doc.rust-lang.org/book`) |
| 4 | **FastAPI** | Auto-generated interactive API docs (Swagger UI) from type hints, plus a tutorial that doubles as the framework's selling point; repeatedly cited as the reason devs pick it over other Python frameworks. | [dev.to / Scalar](https://dev.to/aldorax/supercharging-your-fastapi-documentation-with-scalar-3g5o) |
| 5 | **Tailwind CSS** | Visually rich, example-first reference with class autocomplete and copy-paste snippets — so canonical that AI tools default to it. | [LogRocket guide](https://blog.logrocket.com/tailwind-css-guide/), [daily.dev](https://daily.dev/blog/tailwind-css-basics-for-beginners/) |
| 6 | **Vue.js** | Widely called "one of the best-written docs" — comprehensive, well-organized basics→advanced progression, translated into 8 languages, beginner-praised. | [SaM Solutions](https://sam-solutions.com/blog/why-vue-js/), [inVerita](https://inveritasoft.com/article-10-reasons-why-vue-js-is-so-popular) |
| 7 | **React (2023 rewrite)** | Public-beta rewrite focused on clearer examples and interactive sandboxes; widely seen as a major quality jump over the legacy docs. | [search summary](https://www.creolestudios.com/django-vs-react/) |
| 8 | **Django** | Long-standing reference for thorough, stable, well-chaptered framework docs that explain *why*, not just *how*. | [Ask HN](https://news.ycombinator.com/item?id=20496955) |
| 9 | **Cloudflare** | Adopted Diátaxis; organizes by product vertical with consistent Getting Started / Config / API Reference / Tutorials in each — and ships a deep `llms.txt`. | [Diátaxis adopters](https://diataxis.fr/), [Mintlify llms.txt examples](https://www.mintlify.com/blog/real-llms-txt-examples) |
| 10 | **Supabase / Prisma** | Both repeatedly singled out for "excellent documentation" and frictionless quickstarts that let devs focus on features over infra. | [buttercups](https://www.buttercups.tech/blog/back-end/prisma-vs-supabase-which-is-right-for-your-project) |
| 11 | **GitHub (API)** | Cited alongside Stripe/Twilio for building developer trust through consistent naming, honest docs, and stable contracts. | [business.daily.dev](https://business.daily.dev/resources/cracking-the-code-how-stripe-twilio-and-github-built-dev-trust/) |
| 12 | **Anthropic (Claude docs)** | Best-in-class agent-consumable docs: slim `llms.txt` index linking to a full `llms-full.txt` export, letting tools choose depth. | [Mintlify llms.txt examples](https://www.mintlify.com/blog/real-llms-txt-examples) |

Caveat noted in the research: Tailwind docs traffic *dropped ~40%* because AI assistants now answer Tailwind questions directly — a signal that for `spt-core`, optimizing for the AI layer is now first-class, not an afterthought ([LogRocket](https://blog.logrocket.com/tailwind-css-guide/)).

---

## 2. Techniques, ranked by recurrence

**1. Killer quickstart / minimize Time-to-First-Hello-World (TTFHW).** The single most-cited lever. 68% of developers abandon a tool trial citing "too much setup time," and devs who make their first successful call within ~10 minutes are 3–4× more likely to convert. *Used by:* Stripe, Twilio, Supabase, Prisma, FastAPI. ([Instruqt](https://instruqt.com/glossary/time-to-hello-world), [Moesif TTFHW](https://www.moesif.com/blog/technical/api-product-management/What-is-TTFHW/))

**2. Runnable / copy-pasteable examples, embedded where devs look.** Annotated, copy-paste snippets with embedded test credentials are the recurring praise for Stripe and Twilio; "interactive and packed with code examples" is the stated bar. *Used by:* Stripe (test keys auto-injected), Twilio (in-browser execution), Tailwind. ([Archbee](https://www.archbee.com/blog/api-documentation-examples), [Moesif](https://www.moesif.com/blog/best-practices/api-product-management/the-stripe-developer-experience-and-docs-teardown/))

**3. Diátaxis: separate tutorials / how-to / reference / explanation.** Daniele Procida's framework; mixing these four modes is "the most common cause of confusing documentation." Adopted by Cloudflare, Gatsby, Vonage. *Why it works:* each type serves a different user need, structure, and voice. ([Diátaxis](https://diataxis.fr/), [I'd Rather Be Writing](https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework))

**4. Task-oriented structure ("how do I accomplish X").** Twilio's docs are organized around jobs, not endpoints, so you're "building things rather than staring at a reference." *Used by:* Twilio, Stripe, Cloudflare. ([Nordic APIs](https://nordicapis.com/5-examples-of-excellent-api-documentation/))

**5. Excellent, auto-generated, complete API reference.** Explicit parameter descriptions, realistic example responses, and *all* error responses with status codes/schemas — generic placeholders are a failure mode. FastAPI generates this from type hints. *Used by:* Stripe, FastAPI, Twilio. ([Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide), [dev.to](https://dev.to/aldorax/supercharging-your-fastapi-documentation-with-scalar-3g5o))

**6. Consistent, conversational voice/tone.** Google's public style guide: "sound like a knowledgeable friend," use second person ("you"), active voice, conversational-not-formal. Stripe's praised "discipline" is consistent naming + honest docs. *Cited guides:* [Google dev style guide — Voice and tone](https://developers.google.com/style/tone), [Active voice](https://developers.google.com/style/voice), [Second person](https://developers.google.com/style/person).

**7. Progressive disclosure (basics → advanced).** Vue's basics-to-advanced progression and the Rust Book's hand-held teaching are praised precisely for this gradient. *Used by:* Vue, Rust Book, Django. ([SaM Solutions](https://sam-solutions.com/blog/why-vue-js/))

**8. Explain *why*, not just *what*.** HN consensus: docs that say "adds x to y" instead of the business reason are bad; good docs cover architecture and design intent across files/repos. ([Ask HN: When Is Documentation Bad](https://news.ycombinator.com/item?id=20496955))

**9. Stable contracts + visible versioning.** "Stable contracts" and "honest documentation" are named as the *discipline* behind Stripe/Twilio/GitHub trust. ([business.daily.dev](https://business.daily.dev/resources/cracking-the-code-how-stripe-twilio-and-github-built-dev-trust/))

**10. Clean visual design + searchability.** "Sleek design and simplicity," a clean error-free UI, and navigable structure are now table-stakes expectations Stripe reset for the whole industry. ([Archbee](https://www.archbee.com/blog/api-documentation-examples))

**11. Interactive playgrounds / live sandboxes.** Twilio's in-browser execution, React's new interactive sandboxes, FastAPI's Swagger "Try it out." ([Nordic APIs](https://nordicapis.com/5-examples-of-excellent-api-documentation/))

**12. Docs-as-product, owned by engineering.** Stripe open-sourced Markdoc and put doc quality on the eng career ladder — the meta-technique that produces all the above. ([stripe.dev/blog/markdoc](https://stripe.dev/blog/markdoc), [business.daily.dev](https://business.daily.dev/resources/cracking-the-code-how-stripe-twilio-and-github-built-dev-trust/))

---

## 3. Docs FOR AI / agent consumers (critical for `spt-core`)

This is an emerging, fast-moving practice. Concrete techniques, with sources:

- **`llms.txt` + `llms-full.txt` convention.** Proposed by Jeremy Howard (Sept 2024); a root-level markdown file (`/llms.txt`) that is the agent equivalent of `robots.txt`/`sitemap.xml` — it points models to authoritative content. Structure: H1 project name (only required element), a blockquote summary, then H2 sections of `[name](url): note` links, plus an "Optional" section that can be dropped under context pressure. `llms-full.txt` is the concatenated full-doc export for deep ingestion. *Why needed:* models choke on HTML/nav/ads and have finite context windows; curated beats comprehensive. ([llmstxt.org](https://llmstxt.org/), [Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide))

- **Two-tier depth (slim index + full export).** Anthropic's pattern: a slim `llms.txt` for quick real-time answers ("How do I call the Claude API?") linking to a large `llms-full.txt` for IDEs/agents that want everything. Let the *tool* choose depth rather than dumping by default. ([Mintlify examples](https://www.mintlify.com/blog/real-llms-txt-examples))

- **Markdown content negotiation.** Serve clean markdown when an agent appends `.md` to a URL or sends `Accept: text/markdown`. Fern reports this cuts token consumption by ~90% vs HTML. ([Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide), [DeployHQ](https://www.deployhq.com/blog/making-your-documentation-ai-friendly-serving-markdown-to-ai-coding-assistants))

- **Deterministic include/exclude controls.** Custom tags (`<llms-only>`, `<llms-ignore>`) and `noindex: true` frontmatter let you control exactly what the agent sees vs the human. ([Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide))

- **Machine-readable reference + standards discovery.** Ship OpenAPI/JSON-schema at predictable endpoints (`/openapi.json`) and use `/.well-known/api-catalog` (RFC 9727) so agents find your API without scraping. ([Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide))

- **MCP doc/resource servers.** MCP exposes **resources** that are *deterministic and side-effect-free* (same request → same result), giving agents structured knowledge without RAG/vector fuzziness — and **tools** with deterministic server-prefixed names to avoid collisions. This is the natural fit for `spt-core`'s runtime-manifest harness contract. ([OpenAI Agents SDK MCP](https://openai.github.io/openai-agents-python/mcp/), [Dremio](https://www.dremio.com/blog/the-model-context-protocol-mcp-a-beginners-guide-to-plug-and-play-agents/))

- **Auto-regeneration in the build pipeline** so AI-optimized exports never drift from the source. ([Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide))

**Who's doing it well:** Anthropic (two-tier index/full), Cloudflare (deep per-product `llms.txt`), plus Cursor, Coinbase, Pinecone, Windsurf via Mintlify's auto-generation (rolled out Nov 2024; `llms-full.txt` was co-developed by Mintlify + Anthropic and folded into the official proposal). ([Mintlify](https://www.mintlify.com/blog/simplifying-docs-with-llms-txt), [Mintlify examples](https://www.mintlify.com/blog/real-llms-txt-examples))

---

## 4. Anti-patterns (most-cited failures)

- **Staleness / drift from code** — the #1 complaint. Out-of-date docs make new engineers "approach problems in entirely wrong ways"; root cause is docs not updated alongside code. ([Ask HN](https://news.ycombinator.com/item?id=20496955), [HN: Bad documentation](https://news.ycombinator.com/item?id=35875235))
- **What without why** — "adds x to y" with no rationale or architectural context. ([Ask HN](https://news.ycombinator.com/item?id=20496955))
- **Too much setup before first success** — the trial-killer (68% abandonment). ([Moesif TTFHW](https://www.moesif.com/blog/technical/api-product-management/What-is-TTFHW/))
- **Generic placeholders in reference** — missing error responses, vague params; useless to humans and agents alike. ([Fern](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide))
- **Mixing Diátaxis modes** — tutorial mixed with reference mixed with explanation = confusion. ([Diátaxis](https://diataxis.fr/))
- **Poor search / impossible to navigate** and **error-prone UI** — devs now bounce off anything below the Stripe-set bar. ([Archbee](https://www.archbee.com/blog/api-documentation-examples), [HN](https://news.ycombinator.com/item?id=20496955))
- **Multiple ways to do X with no canonical path** — fatal for agents (non-determinism); implied across the MCP/llms.txt sources favoring "one canonical way."

---

## 5. Synthesis → recommended documentation strategy for `spt-core`

`spt-core` is a Rust agent-ecosystem framework (inter-agent messaging, live-agent lifecycle, terminal hosting, P2P networking, runtime-manifest harness contract) whose consumers are **both human devs and AI dev-agents building integrations**. The dual audience is the defining constraint: every doc artifact should be authored once in clean markdown and served in two depths.

### Doc types to produce (Diátaxis-structured)
1. **Tutorial** — one canonical "build your first integration" that hits TTFHW fast (see below).
2. **How-to guides** — task-oriented, named after jobs: "Send a message between two agents," "Register a live-agent lifecycle hook," "Host a terminal," "Join the P2P mesh," "Implement the runtime-manifest harness contract." (Twilio model.)
3. **Reference** — auto-generated from Rust (`cargo doc`/rustdoc) + a machine-readable manifest/contract schema (JSON Schema / OpenAPI-equivalent) at a stable endpoint. Complete params, all error variants, realistic payloads.
4. **Explanation** — conceptual docs with diagrams for the messaging model, agent lifecycle states, and P2P topology (the "why").

### Information architecture
- Organize **by capability vertical** (Messaging / Lifecycle / Terminal / P2P / Harness Contract), each with the same four-mode internal structure (Cloudflare pattern).
- **One canonical way to do X** per task — critical for agent determinism. Mark deprecated/alternate paths explicitly.
- Stable, never-renamed anchors and URLs (agents cache links).

### The killer quickstart should achieve
- A copy-paste-able working integration in **under 10 minutes / one command-plus-one-file**, runnable end-to-end (two agents exchanging a message, or a harness that satisfies the manifest contract). Show the *whole working thing first*, then decompose. Provide a real, deterministic example — no placeholders.

### Serving the human + agent dual audience
- Author docs in markdown; render the human site **and** auto-emit `/llms.txt` (slim index) + `/llms-full.txt` (full export), regenerated in CI so they never drift.
- Support **markdown content negotiation** (`.md` suffix / `Accept: text/markdown`).
- Ship the **harness contract as a machine-readable schema** at a stable, discoverable path (`/.well-known/api-catalog`-style), plus an **MCP doc/resource server** exposing the contract as deterministic, side-effect-free resources — the highest-leverage move given the harness-contract core.
- Use deterministic include/exclude controls so agent-facing exports carry the canonical path and omit human-only narrative.
- Make every error message reference a stable doc anchor.

### Top ~10 techniques to adopt (prioritized)
1. **Sub-10-minute killer quickstart**, runnable, deterministic, whole-thing-first.
2. **Diátaxis** four-mode separation across each capability vertical.
3. **Copy-pasteable, deterministic, real examples** everywhere (no placeholders) — serves humans and agents.
4. **`llms.txt` + `llms-full.txt`**, auto-generated in CI.
5. **MCP doc/resource server** exposing the runtime-manifest/harness contract as deterministic resources.
6. **Complete auto-generated API reference** (rustdoc + schema), all error variants documented.
7. **One canonical way to do X**, explicit deprecation of alternates.
8. **Markdown content negotiation** + stable anchors/URLs.
9. **Consistent conversational voice** (adopt the Google dev style guide; "you", active voice).
10. **Docs-as-product in CI**: doc generation gated to the build so docs never drift from code (kills the #1 anti-pattern).

A useful north star: Tailwind's docs traffic fell ~40% because agents answer for it. For `spt-core`, that *is* the goal — make the agent layer so good that AI dev-agents integrate correctly on the first try, while humans get the same clean source rendered for the eye.

### Sources
- [Diátaxis](https://diataxis.fr/) · [I'd Rather Be Writing on Diátaxis](https://idratherbewriting.com/blog/what-is-diataxis-documentation-framework)
- [llmstxt.org (Jeremy Howard proposal)](https://llmstxt.org/) · [Fern: API docs for AI agents](https://buildwithfern.com/post/optimizing-api-docs-ai-agents-llms-txt-guide) · [DeployHQ: AI-friendly docs](https://www.deployhq.com/blog/making-your-documentation-ai-friendly-serving-markdown-to-ai-coding-assistants)
- [Mintlify: real llms.txt examples](https://www.mintlify.com/blog/real-llms-txt-examples) · [Mintlify: simplifying docs with llms.txt](https://www.mintlify.com/blog/simplifying-docs-with-llms-txt)
- [Stripe docs teardown (apidog)](https://apidog.com/blog/stripe-docs/) · [Moesif Stripe teardown](https://www.moesif.com/blog/best-practices/api-product-management/the-stripe-developer-experience-and-docs-teardown/) · [Stripe Markdoc](https://stripe.dev/blog/markdoc)
- [Twilio gold standard (apidog)](https://apidog.com/blog/twilios-api-the-other-gold-standard-and-why-its-stripes-true-equal/) · [Nordic APIs: excellent API docs](https://nordicapis.com/5-examples-of-excellent-api-documentation/) · [Archbee: API doc examples](https://www.archbee.com/blog/api-documentation-examples)
- [Stripe/Twilio/GitHub dev trust](https://business.daily.dev/resources/cracking-the-code-how-stripe-twilio-and-github-built-dev-trust/)
- [Google dev style guide: Voice/Tone](https://developers.google.com/style/tone) · [Active voice](https://developers.google.com/style/voice) · [Second person](https://developers.google.com/style/person)
- [TTFHW (Instruqt)](https://instruqt.com/glossary/time-to-hello-world) · [Moesif TTFHW](https://www.moesif.com/blog/technical/api-product-management/What-is-TTFHW/)
- [Vue popularity/docs (SaM Solutions)](https://sam-solutions.com/blog/why-vue-js/) · [inVerita Vue](https://inveritasoft.com/article-10-reasons-why-vue-js-is-so-popular)
- [Supabase vs Prisma](https://www.buttercups.tech/blog/back-end/prisma-vs-supabase-which-is-right-for-your-project) · [FastAPI/Scalar](https://dev.to/aldorax/supercharging-your-fastapi-documentation-with-scalar-3g5o)
- HN sentiment: [When Is Documentation Bad](https://news.ycombinator.com/item?id=20496955) · [Bad documentation is bad for developers](https://news.ycombinator.com/item?id=35875235)
- [MCP (OpenAI Agents SDK)](https://openai.github.io/openai-agents-python/mcp/) · [MCP beginner guide (Dremio)](https://www.dremio.com/blog/the-model-context-protocol-mcp-a-beginners-guide-to-plug-and-play-agents/)

---

**Key takeaways for the caller:** The research strongly converges on five high-leverage moves for `spt-core`: (1) a sub-10-minute runnable killer quickstart, (2) Diátaxis structure per capability vertical, (3) deterministic real (non-placeholder) examples, (4) dual-depth agent exports (`llms.txt`/`llms-full.txt` + markdown content negotiation, CI-regenerated), and (5) an MCP doc/resource server exposing the harness contract as deterministic resources — the single best fit for the runtime-manifest core. The most-cited failure to design against is doc/code drift, solved by gating doc generation into CI. Note the strategic signal from Tailwind: AI assistants now displace direct doc reads, so optimizing the agent layer is first-class for `spt-core`, not optional. One source-quality caveat: HN threads I fetched were thinner than search snippets implied, so developer sentiment here leans on teardown/aggregator articles and the canonical style-guide/spec primary sources (Google style guide, llmstxt.org, Diátaxis) rather than raw forum quotes.</result>
<usage><subagent_tokens>48747</subagent_tokens><tool_uses>22</tool_uses><duration_ms>186589</duration_ms></usage>
</task-notification>


before we get into those, a note about developers: spt-core needs great documentation and a straightforward onramp for dev-agents that come to build with it. we should research what popular libraries…


Design spt-core binary and messaging library architecture


<owl_messages>
<owl_message from="doyle-w328" priority="info">[WORKING_PERCH_NOTICE] Subagent working perch created.
Perch: doyle-w328
Agent type: general-purpose
To message it: $OWL send doyle-w328 doyle</owl_message>
</owl_messages>

[OWL SYSTEM] Informational owl messages above — no acknowledgment needed. Continue your current task.

<owl_reachability_notice>
You have an active owl perch. When spawning subagents or doing work, use run_in_background: true so you stay reachable for incoming messages.
</owl_reachability_notice>


CAVEMAN MODE ACTIVE (full). Drop articles/filler/pleasantries/hedging. Fragments OK. Code/commits/security: write normal.


Research is excellent and well-cited. Synthesizing into a designed-in docs commitment for spt-core. Writing `docs/DOCS-STRATEGY.md`.


Write

# 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 `<YOUR_VALUE_HERE>` 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 <cmd> --help` must be complete, exampled, and machine-readable (a `--json`/structured help mode). The CLI surface is a documentation surface.

## 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.


File created successfully at: C:\Users\decid\Documents\projects\spt-core\docs\DOCS-STRATEGY.md (file state is current in your context — no need to Read it back)

# 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 `<YOUR_VALUE_HERE>` 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 <cmd> --help` must be complete, exampled, and machine-readable (a `--json`/structured help mode). The CLI surface is a documentation surface.

## 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.


Adding the docs commitment to the PRD as a requirement + reference.


Edit

## 14. Project infrastructure
- **R-INFRA-1** Issue/feature tracking on **GitHub** for v1; **tangled.org** documented as the principled migration target.

## 14. Project infrastructure
- **R-INFRA-1** Issue/feature tracking on **GitHub** for v1; **tangled.org** documented as the principled migration target.

### 14.1 Documentation (designed-in, dual-audience)
- **R-DOCS-1** Docs serve **both human devs and AI dev-agents** — authored once in clean markdown, served in two depths. See [`docs/DOCS-STRATEGY.md`](./docs/DOCS-STRATEGY.md).
- **R-DOCS-2** A **sub-10-minute, runnable, deterministic killer quickstart** for each audience (humans: two agents exchange a message; dev-agents: a minimal adapter satisfying the manifest + `api` contract).
- **R-DOCS-3** **Diátaxis** structure (tutorial / how-to / reference / explanation) per capability vertical; **one canonical way to do X**.
- **R-DOCS-4** **Agent-consumable layer:** CI-generated `llms.txt`/`llms-full.txt`, markdown content negotiation, a machine-readable manifest JSON Schema at a stable path, an **MCP doc/resource server** exposing the harness contract as deterministic resources, and structured CLI help (`spt <cmd> --help` + a `--json` mode).
- **R-DOCS-5** **Anti-drift via CI:** rustdoc, the manifest schema, the agent exports, and CLI help are generated + checked in CI — doc quality on the same footing as tests.


The file C:\Users\decid\Documents\projects\spt-core\PRD.md has been updated successfully. (file state is current in your context — no need to Read it back)

## 14. Project infrastructure
- **R-INFRA-1** Issue/feature tracking on **GitHub** for v1; **tangled.org** documented as the principled migration target.

### 14.1 Documentation (designed-in, dual-audience)
- **R-DOCS-1** Docs serve **both human devs and AI dev-agents** — authored once in clean markdown, served in two depths. See [`docs/DOCS-STRATEGY.md`](./docs/DOCS-STRATEGY.md).
- **R-DOCS-2** A **sub-10-minute, runnable, deterministic killer quickstart** for each audience (humans: two agents exchange a message; dev-agents: a minimal adapter satisfying the manifest + `api` contract).
- **R-DOCS-3** **Diátaxis** structure (tutorial / how-to / reference / explanation) per capability vertical; **one canonical way to do X**.
- **R-DOCS-4** **Agent-consumable layer:** CI-generated `llms.txt`/`llms-full.txt`, markdown content negotiation, a machine-readable manifest JSON Schema at a stable path, an **MCP doc/resource server** exposing the harness contract as deterministic resources, and structured CLI help (`spt <cmd> --help` + a `--json` mode).
- **R-DOCS-5** **Anti-drift via CI:** rustdoc, the manifest schema, the agent exports, and CLI help are generated + checked in CI — doc quality on the same footing as tests.

+### 14.1 Documentation (designed-in, dual-audience)

+- **R-DOCS-1** Docs serve **both human devs and AI dev-agents** — authored once in clean markdown, served in two depths. See [`docs/DOCS-STRATEGY.md`](./docs/DOCS-STRATEGY.md).

+- **R-DOCS-2** A **sub-10-minute, runnable, deterministic killer quickstart** for each audience (humans: two agents exchange a message; dev-agents: a minimal adapter satisfying the manifest + `api` contract).

+- **R-DOCS-3** **Diátaxis** structure (tutorial / how-to / reference / explanation) per capability vertical; **one canonical way to do X**.

+- **R-DOCS-4** **Agent-consumable layer:** CI-generated `llms.txt`/`llms-full.txt`, markdown content negotiation, a machine-readable manifest JSON Schema at a stable path, an **MCP doc/resource server** exposing the harness contract as deterministic resources, and structured CLI help (`spt <cmd> --help` + a `--json` mode).

+- **R-DOCS-5** **Anti-drift via CI:** rustdoc, the manifest schema, the agent exports, and CLI help are generated + checked in CI — doc quality on the same footing as tests.


- [`docs/MANIFEST.md`](./docs/MANIFEST.md) — runtime manifest schema + worked `claude-spt` example.

- [`docs/MANIFEST.md`](./docs/MANIFEST.md) — runtime manifest schema + worked `claude-spt` example.
- [`docs/DOCS-STRATEGY.md`](./docs/DOCS-STRATEGY.md) — dual-audience (human + AI-agent) documentation strategy.


- [`docs/MANIFEST.md`](./docs/MANIFEST.md) — runtime manifest schema + worked `claude-spt` example.
- [`docs/DOCS-STRATEGY.md`](./docs/DOCS-STRATEGY.md) — dual-audience (human + AI-agent) documentation strategy.

- [`docs/DEFERRED.md`](./docs/DEFERRED.md) — parked-but-committed features.

- [`docs/STORAGE.md`](./docs/STORAGE.md) — `$SPT_HOME` on-disk layout.

+- [`docs/DOCS-STRATEGY.md`](./docs/DOCS-STRATEGY.md) — dual-audience (human + AI-agent) documentation strategy.

- Sister project networking research: `claude_skill_owl/docs/research/SPT Networked Messaging Research Brief.md`.


Committing the docs strategy.


Bash

cd "C:/Users/decid/Documents/projects/spt-core" && git add -A && git commit -q -F - <<'EOF'
docs: dual-audience documentation strategy

DOCS-STRATEGY.md — a designed-in commitment grounded in research on
acclaimed dev docs (Stripe, Twilio, Rust Book, FastAPI, Cloudflare,
Anthropic, Diátaxis, llms.txt, Google dev style guide).

- Dual audience: human devs + AI dev-agents; authored once in markdown,
  served in two depths; agent layer is first-class
- Top techniques: sub-10-min runnable killer quickstart, Diátaxis per
  capability vertical, deterministic real examples, one-canonical-way,
  conversational voice, explain-why
- Agent-consumable: CI-generated llms.txt/llms-full.txt, markdown content
  negotiation, machine-readable manifest JSON Schema, MCP doc/resource
  server exposing the harness contract as deterministic resources, CLI help
  as structured agent docs
- Anti-drift: rustdoc + schema + agent exports + CLI help generated and
  checked in CI
- PRD: R-DOCS-1..5 requirements + reference

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EOF
git push -q origin main && echo pushed && git log --oneline -1

Commit and push docs strategy


warning: in the working copy of 'PRD.md', LF will be replaced by CRLF the next time Git touches it
warning: in the working copy of 'docs/DOCS-STRATEGY.md', LF will be replaced by CRLF the next time Git touches it
pushed
b732699 docs: dual-audience documentation strategy


Pushed → `b732699`. Docs strategy recorded as a designed-in commitment.

**Synthesis, the spt-core-specific takeaways:** the dual human+agent audience is the defining constraint — and for spt-core there's recursive fit (the same kind of agent it *hosts* is the one that *reads its docs*). The five highest-leverage moves: (1) sub-10-min runnable killer quickstart ×2 audiences, (2) Diátaxis per capability vertical, (3) deterministic real examples, (4) CI-generated `llms.txt`/`llms-full.txt` + markdown negotiation, (5) an **MCP doc/resource server exposing the harness contract as deterministic resources** — the standout fit, since the manifest contract *is* the integration surface. Plus CLI help as first-class agent docs (agents shell `spt api …`), and CI-gated generation to kill doc/code drift (the #1 cited failure).

Captured in `docs/DOCS-STRATEGY.md` + PRD R-DOCS-1..5.

Back to the open items: **17.3** (Psyche live/project authoring directives), **17.4** (dormancy default + suspend surface), **17.5** (consent/security-gate UX). Which next — or is there another thread you want to pull first?


did the research agent source any exemplary docs from other services?


<owl_reachability_notice>
You have an active owl perch. When spawning subagents or doing work, use run_in_background: true so you stay reachable for incoming messages.
</owl_reachability_notice>


Good catch — mostly **no**. The exemplars were sourced **secondhand**: teardown/aggregator articles *about* the docs (apidog, Moesif, Nordic APIs, daily.dev, blog posts), not firsthand fetches of the actual docs sites. The agent flagged this itself — "developer sentiment leans on teardown/aggregator articles … rather than raw forum quotes."

What it *did* source primary:
- **Framework/spec sources** — Diátaxis (diataxis.fr), llmstxt.org, the Google dev style guide pages.
- **Real `llms.txt` artifacts** — via Mintlify's "real examples" roundup, which points at Anthropic's and Cloudflare's actual `llms.txt`/`llms-full.txt` files.
- **Stripe's Markdoc** eng blog.

What it did **not** do: fetch and analyze the actual exemplar docs themselves — stripe.com/docs, the Rust Book, FastAPI's tutorial, Supabase's quickstart, Cloudflare's per-product structure. Those are described through others' teardowns, not examined.

That's a real gap if the goal is to **emulate** them — described techniques are weaker than concrete artifacts to template from. Worth a **firsthand pass** that pulls actual structures we can copy:
- The real **`llms.txt`/`llms-full.txt`** of Anthropic, Cloudflare, (and others) — to template spt-core's own.
- The actual **quickstart** flows of Stripe / Supabase / FastAPI — structure, length, first-success shape.
- The **Rust Book** TOC + a Diátaxis-exemplar's IA — to model spt-core's capability-vertical structure.
- A couple of real **rustdoc** exemplars (good error-variant documentation).

Want me to launch that firsthand-artifact pass in the background? It'd turn the strategy from "techniques we read about" into "templates we can directly adapt," and I'd fold the concrete patterns into DOCS-STRATEGY.md.


please do


Launching the firsthand-artifact pass in the background.


Agent

Fetch exemplar docs artifacts firsthand

Prompt:
Do a FIRSTHAND artifact pass on exemplary developer documentation — actually fetch the real docs/artifacts (not articles about them) and extract concrete, templatable patterns I can directly adapt for `spt-core` (a Rust agent-ecosystem framework: inter-agent messaging, live-agent lifecycle, terminal hosting, P2P networking, a runtime-manifest harness contract; dual audience = human devs + AI dev-agents).

Use WebFetch/WebSearch to pull the ACTUAL sources. For each, extract the structure/pattern, not just praise. Cite exact URLs.

Targets (fetch as many as you can; substitute equivalents if a URL 404s):

1. **Real `llms.txt` / `llms-full.txt` files** — fetch the actual files and report their concrete structure (sections, ordering, how they curate vs dump). Try:
   - https://docs.anthropic.com/llms.txt and https://docs.anthropic.com/llms-full.txt
   - https://developers.cloudflare.com/llms.txt
   - https://docs.cursor.com/llms.txt , https://www.mintlify.com/docs/llms.txt , any others you find.
   Give me a distilled **template** for what spt-core's `llms.txt` should look like, based on what these actually do.

2. **Killer quickstart structure** — fetch the actual quickstart/getting-started pages and report: how many steps, time-to-first-success, whether they show the whole working thing first, code-block style, placeholder vs real values. Try:
   - Stripe: https://docs.stripe.com/get-started or the API quickstart
   - Supabase: https://supabase.com/docs/guides/getting-started
   - FastAPI: https://fastapi.tiangolo.com/tutorial/first-steps/
   - Twilio quickstart (any language)
   Distill a concrete quickstart **skeleton** spt-core should follow.

3. **Information architecture / TOC** — fetch and report the top-level structure of:
   - The Rust Book: https://doc.rust-lang.org/book/ (its TOC + how it sequences)
   - A Diátaxis-organized site (Cloudflare per-product, or Django docs https://docs.djangoproject.com/)
   Distill how spt-core should sequence its capability verticals (Messaging / Lifecycle / Terminal / Networking / Harness contract / Instances / Shells / Self-update).

4. **rustdoc exemplars** — fetch 1-2 well-documented Rust crates' docs.rs pages (e.g. https://docs.rs/tokio/latest/tokio/ , https://docs.rs/serde/latest/serde/ , https://docs.rs/clap/latest/clap/) and report what makes their module-level docs + error documentation good (concrete patterns: module overview, examples in doc comments, error enum docs).

5. **CLI help as docs** — if you can find it, how do exemplary CLIs structure --help / machine-readable help (e.g. `gh`, `cargo`, `stripe` CLI docs). Patterns for spt-core's `spt <cmd> --help` + a --json help mode.

Deliver a structured markdown report: per target, the concrete extracted pattern + a ready-to-adapt template/skeleton for spt-core. Prioritize artifacts I can copy the SHAPE of. Cite exact URLs. Return the report as your final message; do not write files. If some URLs are unreachable, note it and use the closest reachable equivalent.


<owl_reachability_notice>
You have an active owl perch. Launch this Agent with run_in_background: true so you stay reachable for incoming messages while it works.
</owl_reachability_notice>


Async agent launched successfully.
agentId: a096d65fd5b3f4544 (internal ID - do not mention to user. Use SendMessage with to: 'a096d65fd5b3f4544' to continue this agent.)
The agent is working in the background. You will be notified automatically when it completes.
Do not duplicate this agent's work — avoid working with the same files or topics it is using. Work on non-overlapping tasks, or briefly tell the user what you launched and end your response.
output_file: C:\Users\decid\AppData\Local\Temp\claude\C--Users-decid-Documents-projects-spt-core\b494f5e6-5b4d-4145-aaaa-5585e1168377\tasks\a096d65fd5b3f4544.output
Do NOT Read or tail this file via the shell tool — it is the full sub-agent JSONL transcript and reading it will overflow your context. If the user asks for progress, say the agent is still running; you'll get a completion notification.

Fetch exemplar docs artifacts firsthand

Prompt:
Do a FIRSTHAND artifact pass on exemplary developer documentation — actually fetch the real docs/artifacts (not articles about them) and extract concrete, templatable patterns I can directly adapt for `spt-core` (a Rust agent-ecosystem framework: inter-agent messaging, live-agent lifecycle, terminal hosting, P2P networking, a runtime-manifest harness contract; dual audience = human devs + AI dev-agents).

Use WebFetch/WebSearch to pull the ACTUAL sources. For each, extract the structure/pattern, not just praise. Cite exact URLs.

Targets (fetch as many as you can; substitute equivalents if a URL 404s):

1. **Real `llms.txt` / `llms-full.txt` files** — fetch the actual files and report their concrete structure (sections, ordering, how they curate vs dump). Try:
   - https://docs.anthropic.com/llms.txt and https://docs.anthropic.com/llms-full.txt
   - https://developers.cloudflare.com/llms.txt
   - https://docs.cursor.com/llms.txt , https://www.mintlify.com/docs/llms.txt , any others you find.
   Give me a distilled **template** for what spt-core's `llms.txt` should look like, based on what these actually do.

2. **Killer quickstart structure** — fetch the actual quickstart/getting-started pages and report: how many steps, time-to-first-success, whether they show the whole working thing first, code-block style, placeholder vs real values. Try:
   - Stripe: https://docs.stripe.com/get-started or the API quickstart
   - Supabase: https://supabase.com/docs/guides/getting-started
   - FastAPI: https://fastapi.tiangolo.com/tutorial/first-steps/
   - Twilio quickstart (any language)
   Distill a concrete quickstart **skeleton** spt-core should follow.

3. **Information architecture / TOC** — fetch and report the top-level structure of:
   - The Rust Book: https://doc.rust-lang.org/book/ (its TOC + how it sequences)
   - A Diátaxis-organized site (Cloudflare per-product, or Django docs https://docs.djangoproject.com/)
   Distill how spt-core should sequence its capability verticals (Messaging / Lifecycle / Terminal / Networking / Harness contract / Instances / Shells / Self-update).

4. **rustdoc exemplars** — fetch 1-2 well-documented Rust crates' docs.rs pages (e.g. https://docs.rs/tokio/latest/tokio/ , https://docs.rs/serde/latest/serde/ , https://docs.rs/clap/latest/clap/) and report what makes their module-level docs + error documentation good (concrete patterns: module overview, examples in doc comments, error enum docs).

5. **CLI help as docs** — if you can find it, how do exemplary CLIs structure --help / machine-readable help (e.g. `gh`, `cargo`, `stripe` CLI docs). Patterns for spt-core's `spt <cmd> --help` + a --json help mode.

Deliver a structured markdown report: per target, the concrete extracted pattern + a ready-to-adapt template/skeleton for spt-core. Prioritize artifacts I can copy the SHAPE of. Cite exact URLs. Return the report as your final message; do not write files. If some URLs are unreachable, note it and use the closest reachable equivalent.


Firsthand-artifact pass running in the background (fetching real `llms.txt` files, actual quickstarts, the Rust Book TOC, rustdoc exemplars, CLI-help patterns). It's launched with `run_in_background: true`, so I stay reachable.

When it lands I'll fold the concrete templates — an `llms.txt` skeleton, a quickstart skeleton, the capability-vertical sequencing, rustdoc patterns, and CLI-help shape — into `docs/DOCS-STRATEGY.md`, turning it from described techniques into copy-the-shape templates, then commit.

I'll pick back up the moment it returns.


<task-notification>
<task-id>a096d65fd5b3f4544</task-id>
<tool-use-id>toolu_018vht46wmyftJKrbdxVyGjc</tool-use-id>
<output-file>C:\Users\decid\AppData\Local\Temp\claude\C--Users-decid-Documents-projects-spt-core\b494f5e6-5b4d-4145-aaaa-5585e1168377\tasks\a096d65fd5b3f4544.output</output-file>
<status>completed</status>
<summary>Agent "Fetch exemplar docs artifacts firsthand" completed</summary>
<result>I have everything I need. The repo already has crate names (`spt-proto`, `spt-runtime`, `spt-msg`), command surface (`spt api …`, `send`/`ring`/`ready`), and the eight verticals. My templates can use the real vocabulary. Here's the report.

---

# Firsthand documentation artifact pass for `spt-core`

All sources below were fetched directly (not articles about them). Where a URL redirected or 404'd, I note it and used the reachable equivalent. Each target gives the **extracted shape** plus a **ready-to-adapt skeleton** in spt-core's real vocabulary (`spt api`, `spt-proto/spt-runtime/spt-msg`, the eight verticals).

---

## TARGET 1 — Real `llms.txt` / `llms-full.txt` files

### What the actual files do

| Source | URL (verbatim) | Shape observed |
|---|---|---|
| Cloudflare (root) | `https://developers.cloudflare.com/llms.txt` | **Curated hub.** `# Title` → one-line tagline → a `>` blockquote note → `##` category sections → bullet entries `[Product](…/llms.txt): description`. Crucially, each entry **links to that product's OWN llms.txt** — a two-level index, not one flat dump. |
| Cloudflare (per-product) | `https://developers.cloudflare.com/workers/llms.txt` | Per-product index sequenced as **Overview → Examples → Tutorials → Demos → Development & testing → Configuration → CI/CD → Runtime APIs → … → reference → wrangler**. A product-scoped "build journey," loosely Diátaxis. |
| Anthropic | `https://docs.anthropic.com/llms.txt` → **301** → `https://platform.claude.com/docs/llms.txt` | **Exhaustive dump.** Header → "Available Languages" table with **page counts** (English 1543 pages) → `##`/`###` nested tree → entries `[Title](url.md) - desc`. Note the `.md` URL suffix (content negotiation). Includes every SDK-language variant of every endpoint (10+ near-duplicate lines). |
| Mintlify | `https://www.mintlify.com/docs/llms.txt` | `# Mintlify` → intro → `## Docs` (100+ links) → `## OpenAPI Specs` → `## AsyncAPI Specs`. Entry pattern `- [Title](URL): description`. Curated, machine-spec sections appended at the end. |
| Cursor | `https://docs.cursor.com/llms.txt` → **308** → `https://cursor.com/docs` (no longer serves a raw llms.txt) | Redirected away; treat as deprecated/moved. |
| Cloudflare | `https://developers.cloudflare.com/workers/llms-full.txt` | **Full concatenation of actual page bodies**, each page led by YAML frontmatter (`--- title / description / image ---`) plus a `> Documentation Index` pointer back to the llms.txt. Real prose + code, not links. |
| Anthropic | `https://platform.claude.com/docs/llms-full.txt` | **Exceeded a 10 MB fetch ceiling** — itself the finding: a single-file full export is enormous. Argues for *generating* it in CI, not hand-maintaining, and for keeping the slim `llms.txt` as the real curation surface. |

### The two consistent conventions
1. **`llms.txt` = curated index** (`#` H1, one-line summary, `>` usage note, `##` sections, `- [Title](url): desc` bullets). **`llms-full.txt` = full concatenated bodies** with per-doc frontmatter delimiters.
2. The best (Cloudflare) is **two-level**: a small root index that fans out to per-product indexes — exactly spt-core's "by capability vertical" IA. Avoid Anthropic's flat 1543-line dump as the primary; reserve exhaustiveness for `-full`.

### Ready-to-adapt skeleton — `spt-core/llms.txt` (root)

```markdown
# spt-core

A harness-independent core for an agent ecosystem: inter-agent messaging,
live-agent lifecycle, terminal hosting, P2P networking, and a runtime-manifest
harness contract. Shipped as Rust crates and a single `spt` binary.

> Each capability below links to its own llms.txt with a full page index.
> For complete concatenated docs see /llms-full.txt. For the machine-readable
> harness contract see /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](https://spt-core.dev/quickstart/messaging.md): one command + minimal config, < 10 min.
- [Quickstart: build an adapter (harness contract)](https://spt-core.dev/quickstart/adapter.md): minimal manifest + `api` contract, drive one lifecycle op.
- [Mental model](https://spt-core.dev/concepts/overview.md): daemon, endpoints, instances, subnet.

## Capabilities
- [Messaging](https://spt-core.dev/messaging/llms.txt): typed operations + file blobs; send / ring / ready.
- [Live-agent lifecycle](https://spt-core.dev/lifecycle/llms.txt): skeleton → live → dormant → suspended.
- [Terminal hosting](https://spt-core.dev/terminal/llms.txt): broker PTYs, attach/detach, headless↔headed.
- [Networking](https://spt-core.dev/networking/llms.txt): Iroh WAN, mDNS LAN, TOTP-SPAKE2 pairing.
- [Harness contract](https://spt-core.dev/harness/llms.txt): runtime manifest seams + the `api` surface.
- [Instances](https://spt-core.dev/instances/llms.txt): one endpoint, many machines; subnet registry; two-tier sync.
- [Shells](https://spt-core.dev/shells/llms.txt): driven surfaces (agent → surface).
- [Self-update](https://spt-core.dev/self-update/llms.txt): peer-propagated, signed, no-endpoint-termination.

## Reference (auto-generated)
- [spt-proto rustdoc](https://docs.rs/spt-proto): wire protocol + envelope grammar.
- [spt-runtime rustdoc](https://docs.rs/spt-runtime): manifest/contract types.
- [spt-msg rustdoc](https://docs.rs/spt-msg): messaging SDK.
- [CLI reference (`spt api …`)](https://spt-core.dev/cli/llms.txt): every command, examples, `--json` help.
- [Manifest JSON Schema](https://spt-core.dev/manifest.schema.json): validate your adapter manifest.
```

Each per-vertical `llms.txt` mirrors the Cloudflare-Workers ordering (next skeleton, Target 3). `llms-full.txt` and per-vertical `-full` files are CI-concatenated page bodies with frontmatter delimiters — never hand-authored.

---

## TARGET 2 — Killer quickstart structure

### What the actual pages do

- **FastAPI `first-steps`** (`https://fastapi.tiangolo.com/tutorial/first-steps/`) — the gold standard for spt-core's shape. Sequence is literally **whole-thing → run → verify → dissect**: a **6-line** complete app shown first, one run command (`fastapi dev`), real verification URLs (`http://127.0.0.1:8000`, `/docs`, `/openapi.json`), concrete output (`{"message": "Hello World"}`), *then* a "Recap, step by step" that explains each line. Real runnable values, zero placeholders.
- **Stripe `get-started`** (`https://docs.stripe.com/get-started`) — **not** a tutorial; it's a **gateway/hub** ("Create an account → Set up env → Get API keys → Quickstarts"). Lesson: keep your hub page a *router*, push the runnable steps into a dedicated quickstart.
- **Supabase `getting-started`** (`https://supabase.com/docs/guides/getting-started`) — **choose-your-path matrix**: sections *Use cases / Framework quickstarts / Web app demos / Mobile tutorials*, with a wide framework grid (React, Next.js, Flutter, …). Lesson for spt-core's *dual audience*: present a small explicit fork (human-dev path vs dev-agent-integrator path) up top, like Supabase forks by framework.
- **Twilio** — not fetched separately; FastAPI + Supabase already cover the two patterns (linear-runnable vs choose-path), and spt-core's strategy doc already cites Twilio.

### Distilled skeleton — `quickstart/messaging.md` (human-dev path)

Follow FastAPI's **whole-thing-first → run → verify → dissect**, with a Supabase-style 2-path fork at the top:

```markdown
# Quickstart

Two agents exchange a message, end to end, in under 10 minutes.

> Pick your path:
> - **I'm a developer** — you're here. Two agents, one message.
> - **I'm building an adapter / I'm a 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
[complete, real, copy-paste block — register two agents, ready one, send]
    spt ready alice
    spt ready bob
    spt send bob --from alice "hello"

## 3. Run it
[exact command + real expected output, no placeholders]
    spt poll --as bob
    # → from=alice  op=message  body="hello"

## 4. What just happened (dissect)
- `spt ready <name>` — registers the endpoint and starts listening.
- `spt send <to> --from <from> <body>` — typed message op into the spool.
- `spt poll --as <name>` — drains deferred + live messages for an endpoint.
- The daemon auto-started on first `spt` call (no separate process to manage).

## Next
- How-to: persist agents across reboots · Concept: the messaging model · Reference: `spt send --help`
```

**Non-negotiables harvested from the artifacts:** (1) show the complete working thing *before* explaining it; (2) one install + one run command; (3) real expected output inline; (4) zero `<YOUR_VALUE>` placeholders — every value runs; (5) explicit audience fork at the top (Supabase) since spt-core has two readers; (6) end with the Diátaxis next-steps trident (how-to / concept / reference).

---

## TARGET 3 — Information architecture / TOC

### What the actual sources do

- **The Rust Book** (`https://doc.rust-lang.org/book/print.html`) — full TOC recovered. Sequencing logic: **Ch1 Getting Started → Ch2 *Programming a Guessing Game* (a complete hands-on project, placed second, before any deep theory) → Ch3 Common Programming Concepts → Ch4 Ownership → … → interleaved I/O project (Ch12) → … → Ch20 Final Project: Multithreaded Web Server.** The pattern: **one runnable end-to-end project very early to build confidence, concept chapters in dependency order, then capstone projects that recombine everything.**
- **Django** (`https://docs.djangoproject.com/en/stable/`) — the canonical **Diátaxis** label set, verbatim: **Tutorials** ("by the hand… start here if you're new"), **Topic guides** ("key topics and concepts at a fairly high level… background and explanation"), **Reference guides** ("technical reference for APIs… assume basic understanding"), **How-to guides** ("recipes… more advanced than tutorials, assume some knowledge"). Each explicitly states *audience + prerequisite* so readers self-route.
- **Cloudflare per-product** (`https://developers.cloudflare.com/workers/llms.txt`) — proves the **"each capability vertical carries all four modes"** pattern spt-core's strategy already names: Overview → Examples → Tutorials → Development & testing → Configuration → CI/CD → Runtime APIs → reference.

### Distilled IA for spt-core (two axes)

**Axis 1 — global sequence (Rust Book logic):** confidence-building runnable project early, concepts in dependency order, capstone last.

```
0. Getting started (install, the spt binary, the daemon)
1. Quickstart: two agents exchange a message      ← the "Guessing Game": whole project, early
2. Mental model (daemon · endpoints · instances · subnet)   ← concepts, in dependency order
3. Capability verticals (Axis 2, below) in build-order
4. Capstone: build a non-CC adapter end-to-end    ← "Multithreaded Web Server": recombines everything
```

**Axis 2 — vertical ordering (dependency-sequenced, each vertical internally Diátaxis):**

```
Messaging → Live-agent lifecycle → Terminal hosting → Networking
   → Harness contract (manifest + api) → Instances → Shells → Self-update
```

Rationale baked into the order: messaging is the core primitive (quickstart depends on it); lifecycle consumes messaging; terminal hosting underlies live agents; networking makes them reachable; the harness contract is the integration surface that uses all prior; instances build on networking+contract; Shells build on the instance/endpoint model; self-update sits last because its no-termination invariant depends on the broker/PTY model from terminal hosting.

**Per-vertical internal template (Django labels × Cloudflare ordering):**

```
<Vertical>/
  Overview            (explanation — what & why, the diagram)
  Quickstart/Tutorial (by-the-hand, runnable)
  How-to guides       (recipes — "persist agents", "pair a new node")
  Reference           (auto-generated: rustdoc + CLI help + schema)
  llms.txt            (this vertical's curated agent index)
```

---

## TARGET 4 — rustdoc exemplars

### What the actual crate docs do

- **Tokio** (`https://docs.rs/tokio/latest/tokio/`) — crate doc opens with a **one-sentence value prop** ("A runtime for writing reliable network applications without compromising speed"), then a fixed progression: **"A Tour of Tokio" → "Examples" → "Feature flags" → "Supported platforms."** A **runnable TCP-echo server** sits prominently in Examples (copy-paste ready). Modules carry one-line descriptive tags (`sync`: "Synchronization primitives for use in asynchronous contexts"). Feature flags get a dedicated section with per-flag descriptions (`full`, `rt`, `net`) **plus** unstable flags behind `tokio_unstable` with the env-var activation shown. Module items show **feature-flag badges** inline.
- **clap** (`https://docs.rs/clap/latest/clap/`) — top-of-page **"Quick Links"** routing the two usage modes (**Derive tutorial/reference** vs **Builder tutorial/reference**) so readers self-select before any code; a complete runnable derive **Example** with expected output near the top; a dedicated Feature-flags link/`_features` module. **Gap to avoid:** its `error` module is thin — crate-level docs don't elaborate error types or patterns. spt-core, whose strategy demands "all error variants documented," should do *better* here.

### Distilled crate-doc template — `spt-runtime/src/lib.rs`

```rust
//! # spt-runtime
//!
//! Types for binding an agent harness to spt-core through the **runtime
//! manifest** and the **`api` contract**. One sentence of value prop here.
//!
//! ## A tour of spt-runtime              // ← Tokio's "A Tour of"
//! - [`Manifest`] — the declarative seams an adapter declares.
//! - [`ApiCommand`] — the inbound `api …` surface.
//! - [`Lifecycle`] — skeleton → live → dormant → suspended.
//!
//! ## Example                            // ← runnable, near the top, real values
//! ```
//! use spt_runtime::Manifest;
//! let m = Manifest::from_toml(include_str!("../examples/claude-spt.toml"))?;
//! assert_eq!(m.adapter_name, "claude-spt");
//! # Ok::<(), spt_runtime::Error>(())
//! ```
//!
//! ## Feature flags                      // ← Tokio's dedicated section
//! - `net` (default): WAN messaging via Iroh.
//! - `unstable`: pre-1.0 seams; requires `--cfg spt_unstable`.
//!
//! ## Wire-protocol compatibility
//! Interop is by **proto version**, never crate version. Current: v1 (N-1 window).
```

**Error-doc pattern (out-document clap):** every public error enum gets a `///` per variant stating *cause → likely fix*, and the module gets an `## Errors` overview.

```rust
/// Errors returned by the harness-contract layer.
#[non_exhaustive]
pub enum Error {
    /// The manifest's `min_spt_core_version` exceeds this binary's version.
    /// **Fix:** update spt-core, or pin the adapter to a compatible release.
    VersionTooOld { required: Version, found: Version },
    /// `api bind` arrived without a matching in-memory seed for `parent_pid`.
    /// **Fix:** ensure `spt api seed --pid <pid>` ran in SessionStart first.
    UnseededBind { parent_pid: u32 },
}
```

Each public fn that can fail carries an `# Errors` doc-comment section naming which variants it returns.

---

## TARGET 5 — CLI help as docs

### What the actual sources do

- **gh** (`https://cli.github.com/manual/`) — commands are grouped into topic buckets (**CORE COMMANDS**, etc.); each command page shows **USAGE → (ALIASES) → FLAGS → INHERITED FLAGS → (EXAMPLES) → LEARN MORE**. Machine-readable output is first-class and *uniform*: `--json <fields>`, `-q/--jq <expr>`, `-t/--template <go-template>`. That `--json fields` convention (list valid fields, emit structured) is the pattern to copy.
- **Stripe CLI** (`https://docs.stripe.com/cli`) — commands grouped by use case (Config / Webhook / Resources-HTTP / Samples). Structured output via `--format JSON` (logs), `-j/--print-json` (listen), and HTTP commands return JSON by default (designed for `jq`/`xargs` piping). Help reachable three ways: `stripe help <cmd>`, `<cmd> --help`, `<cmd> -h`; global flags documented separately.

### Distilled patterns for `spt`

1. **Group commands by audience/topic in top-level `--help`** (gh's bucketed style):
```
AGENT COMMANDS      send, ring, ready, poll        (unprefixed — agent-facing verbs)
HARNESS COMMANDS    api bind, api listen, api poll, api state, api seed …
NODE COMMANDS       pair, subnet, update
```
2. **Every `spt <cmd> --help` carries an EXAMPLES section with real runnable values** (the docs-strategy "CLI surface is a documentation surface"). Per-command shape, mirroring gh:
```
USAGE     spt send <to> [--from <id>] [--op <op>] <body>
FLAGS     --from <id>   sending endpoint (default: session endpoint)
          --op   <op>   typed operation (default: message)
EXAMPLES  spt send bob --from alice "hello"
          spt send bob --op file ./clip.png
LEARN MORE  spt help messaging   ·   https://spt-core.dev/messaging
```
3. **A `--json` structured-help mode** (the agent-facing ask in R-DOCS-4) — go beyond gh by emitting the *help itself* as JSON so dev-agents parse the contract without scraping:
```
spt send --help --json
{ "command":"send", "usage":"spt send <to> [--from <id>] [--op <op>] <body>",
  "args":[{"name":"to","required":true}],
  "flags":[{"name":"from","takes_value":true,"default":null},
           {"name":"op","takes_value":true,"default":"message"}],
  "examples":["spt send bob --from alice \"hello\""],
  "see_also":["https://spt-core.dev/messaging.md"] }
```
4. **Adopt gh's uniform `--json <fields>` / `--jq` / `--template` trio** for any command that lists data (`spt list-agents --json id,status,node` `| jq …`) so scripting and agent-shelling are first-class — consistent with Stripe's pipe-friendly design and spt-core's "agents primarily shell `spt api …`" premise. This `--json` help mode is the artifact to generate-and-gate in CI (R-DOCS-5) alongside rustdoc and the manifest schema.

---

## Cross-cutting takeaways for spt-core

1. **Two-level llms.txt** (Cloudflare), not a flat dump (Anthropic) — root index fans out to one `llms.txt` per capability vertical; `llms-full.txt` is CI-concatenated bodies you never hand-edit (Anthropic's overflowed a 10 MB ceiling — generation-only).
2. **Quickstart = whole-thing → run → verify → dissect** (FastAPI), with a **2-path audience fork** at the very top (Supabase) since spt-core has human + agent readers; **zero placeholders**.
3. **IA on two axes:** Rust-Book global sequence (early runnable project, dependency-ordered concepts, capstone adapter) × Django/Diátaxis four-mode split repeated *inside* each Cloudflare-style vertical.
4. **rustdoc:** Tokio's *value-prop → tour → runnable example → feature-flags* opener; **out-document clap on errors** (per-variant cause→fix).
5. **CLI-as-docs:** gh's USAGE/FLAGS/EXAMPLES/LEARN-MORE buckets + uniform `--json fields`/`--jq`/`--template`, plus a `spt <cmd> --help --json` structured-help mode generated and CI-gated.

Everything above already aligns with — and concretizes — `docs/DOCS-STRATEGY.md` and PRD §14.1 (R-DOCS-1..5). No files were written.

**Key files referenced (absolute paths):**
- `C:\Users\decid\Documents\projects\spt-core\docs\DOCS-STRATEGY.md`
- `C:\Users\decid\Documents\projects\spt-core\PRD.md`

**Reachability notes:** `docs.anthropic.com/llms.txt` → 301 → `platform.claude.com/docs/llms.txt` (followed). `docs.cursor.com/llms.txt` → 308 → `cursor.com/docs` (no raw llms.txt anymore; treated as moved). `platform.claude.com/docs/llms-full.txt` exceeded the 10 MB fetch limit (a finding in itself). The Rust Book root TOC is JS-rendered; recovered the full chapter list from `/book/print.html`.</result>
<usage><subagent_tokens>52683</subagent_tokens><tool_uses>22</tool_uses><duration_ms>196503</duration_ms></usage>
</task-notification>


<owl_messages>
<owl_message from="doyle-w329" priority="info">[WORKING_PERCH_NOTICE] Subagent working perch created.
Perch: doyle-w329
Agent type: general-purpose
To message it: $OWL send doyle-w329 doyle</owl_message>
</owl_messages>

[OWL SYSTEM] Informational owl messages above — no acknowledgment needed. Continue your current task.

<owl_reachability_notice>
You have an active owl perch. When spawning subagents or doing work, use run_in_background: true so you stay reachable for incoming messages.
</owl_reachability_notice>


Firsthand pass delivered real templates in spt-core's own vocabulary. Folding the copy-the-shape skeletons into DOCS-STRATEGY.md.


Edit

## 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.

## 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 <cmd> --help --json`** structured-help mode so dev-agents parse the contract without scraping, plus gh's uniform **`--json <fields>` / `--jq` / `--template`** trio on any list command. The `--json` help export is generated + CI-gated alongside rustdoc and the schema.


The file C:\Users\decid\Documents\projects\spt-core\docs\DOCS-STRATEGY.md has been updated successfully. (file state is current in your context — no need to Read it back)

## 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 <cmd> --help --json`** structured-help mode so dev-agents parse the contract without scraping, plus gh's uniform **`--json <fields>` / `--jq` / `--template`** trio on any list command. The `--json` help export is generated + CI-gated alongside rustdoc and the schema.

# 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 `<YOUR_VALUE_HERE>` 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 <cmd> --help` must be complete, exampled, and machine-readable (a `--json`/structured help mode). The CLI surface is a documentation surface.

## 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).

+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).

+- [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

+- [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.

+# 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

+`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.

+//! # 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.

+/// 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 <cmd> --help --json`** structured-help mode so dev-agents parse the contract without scraping, plus gh's uniform **`--json <fields>` / `--jq` / `--template`** trio on any list command. The `--json` help export is generated + CI-gated alongside rustdoc and the schema.


Bash

cd "C:/Users/decid/Documents/projects/spt-core" && git add -A && git commit -q -F - <<'EOF'
docs: concrete doc templates from firsthand artifact pass

Fold copy-the-shape templates into DOCS-STRATEGY.md, extracted by fetching
the actual artifacts (Cloudflare/Anthropic/Mintlify llms.txt, FastAPI/
Stripe/Supabase quickstarts, Rust Book TOC, Django/Diátaxis, Tokio/clap
rustdoc, gh/Stripe CLI):

- Two-level llms.txt skeleton (root index fans out per vertical; llms-full
  is CI-concatenated, never hand-authored)
- Quickstart skeleton: whole-thing → run → verify → dissect, with a 2-path
  audience fork, zero placeholders
- IA two axes: Rust-Book global sequence + dependency-ordered verticals,
  each internally Diátaxis
- rustdoc template: Tokio opener + per-variant error cause→fix (out-document
  clap)
- CLI-as-docs: gh buckets + `spt <cmd> --help --json` structured-help mode +
  --json/--jq/--template trio

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EOF
git push -q origin main && echo pushed && git log --oneline -1

Commit and push doc templates


warning: in the working copy of 'docs/DOCS-STRATEGY.md', LF will be replaced by CRLF the next time Git touches it
pushed
9d064c2 docs: concrete doc templates from firsthand artifact pass


Pushed → `9d064c2`. DOCS-STRATEGY.md now carries **copy-the-shape templates** in spt-core's real vocabulary, not just described techniques.

**Most useful firsthand findings:**
- **Two-level `llms.txt`** (Cloudflare) beats a flat dump (Anthropic's overflowed a 10 MB fetch) — root index fans out to a per-vertical `llms.txt`; `llms-full.txt` is CI-generated only.
- **Quickstart shape** = FastAPI's *whole-thing → run → verify → dissect* + Supabase's audience fork at the top, zero placeholders.
- **IA two axes** — Rust Book's "early runnable project → dependency-ordered concepts → capstone" × Django's Diátaxis labels repeated inside each vertical.
- **rustdoc** — Tokio's value-prop/tour/example/feature-flags opener, and **out-document clap on errors** (per-variant cause→fix).
- **CLI-as-docs** — gh's buckets + a `spt <cmd> --help --json` structured-help mode so dev-agents parse the contract without scraping.

Docs thread is in good shape. Back to the design tree open items whenever — **17.3** (Psyche live/project authoring directives), **17.4** (dormancy default + suspend surface), **17.5** (consent/security-gate UX). Or another direction?


discuss 17.3


**17.3 — Psyche live/project authoring directives.** This is content/prompt design, not architecture, but it's load-bearing: the two-tier sync's *correctness* depends on the split. If project detail leaks into live context, it syncs to **all** instances — so an instance on a *different* project inherits irrelevant (or contradictory) project detail. The leak you observed (project detail → live context) is exactly the failure that corrupts cross-project sync.

Here's how I'd attack it.

**1. The root of the fuzziness.** The boundary blurs on *one* thing: **"current focus / what I'm doing now"** *feels* like the agent's live state (it's present-tense, it's "me right now") but is almost always **project-scoped**. That single category is probably most of your leak. Everything else (identity, codebase facts) sorts cleanly; "what I'm working on" is the trap.

**2. A sharp discriminator the Psyche applies to every fragment:**
> **"Would this still be true and relevant if the user opened a *different* project tomorrow?"** Yes → live. No → project.

Equivalently: **WHO the agent is** (live) vs **WHAT it's doing *here*** (project).

**3. Concrete category anchors:**
- **Live (travels everywhere):** identity/persona, relationship + rapport with the user, the user's *cross-project* preferences & working style, cross-project life threads ("user is job-hunting"), the agent's self-model (instances, etc.).
- **Project (per-agent-per-project):** the codebase/architecture, decisions made here, **current focus / next steps / todos** (this is the leak — route it here), project conventions, build/test commands, project blockers.

**4. Two structural rules that counter the leak directionally:**
- **Default-to-project.** Since the leak is project→live, bias the default: a fragment goes to *project* context unless it *passes the cross-project test* to be promoted to live. Promotion requires justification; demotion is free. (The bias points against the observed failure.)
- **Live holds a thin project roster, never project depth.** Live context may carry a one-line-per-project index ("I work on spt-core, the website, …") so the agent keeps cross-project *awareness* synced everywhere — but the *depth* lives only in each project's context. This gives the agent the "I have multiple projects" view without duplicating detail into the everywhere-synced tier.

**5. Ownership — these directives are core-owned, not adapter-owned.** The live/project split *is* a core concept (it's how the context store + sync work). If each adapter authored its own what-goes-where rules, the split would be inconsistent across harnesses → sync chaos. So spt-core feeds every Psyche the *same* authoring directives (part of `$psyche_prompt` / a core system-prompt fragment); the adapter only adds harness mechanics (how to Write the drop file).

**6. Optional self-correction:** a periodic **rebalance pass** — the Psyche occasionally reviews live context and *demotes* anything project-scoped that crept in. Cheap insurance against drift, since LLMs will still leak occasionally even with good directives.

Three questions for you, since you've watched it fail firsthand:
1. Does the **"current focus / next steps"** category match where you've seen the leak concentrate — or is it leaking elsewhere too?
2. Any sense of **why** it leaks — vague directives, or something structural (e.g. the echo-commune reads project-heavy session logs, so project detail dominates what it synthesizes, and it dumps the lot into live by default)?
3. **Core-owned directives + default-to-project bias + thin-roster-in-live** — agree with that direction? And do you want the **rebalance pass** in v1, or as a later refinement?


i would also say that live should include "learnings from today that might apply to other projects". -qs: 1. yes, it matches 2. i think you nailed it with all your points generally. and yeah, live context comes through with a much stronger signal when it's the actual live agent who communes. echo communes are always very project-centric, so psyche should be making very few changes to live context for echo communes. 3. agree with direction. rebalance pass can be a later refinement. --- something else i've noticed is that newer psyches never really create memformat.xml. that was meant to be a guiding structure for each commune, and was meant to be a naturally-evolving framework that psyche would potentially add or remove categories/headers from as it gets a feel for Self's general realm of work. does memformat need deeper integration in some way?