[auto-wood]

What

Two deliverables: an agent-oriented docs layer with corrected facts, and a human-oriented README, plus six protocol diagrams used by both.

Docs (agent-facing)

• New docs/agents.md and docs/zh/agents.md: fact hierarchy (schemas/ > .mstar/specs/ > reference > how-to), reading order, task routing, capability table, common traps.
• docs/public/llms.txt index and a generated llms-full.txt bundle (tooling/docs/build-llms.mjs), wired into docs:build / docs:dev. The bundle is gitignored.
• VitePress nav/sidebar gain a "For agents" entry.

Fact fixes (EN + ZH)

• ToolDescriptor now has a field table in the data model; the extensions contract names the record objects that carry the bag.
• Connect required lists match the committed schema, which encodes the protocol_version 2 wire shape.
• Rust examples use SpokeResult::Ok/Reject, .await on connect_remote_adapter, and pass the Arc to register_peer.
• Demo manifest excerpts match the code (ke-extraction, ke-ownership, input-source, viewpoint).
• MemoryPortService is attributed to the Rust crate; C# and Go FFI symbol names match the generated bindings.
• Corrected profile count, hello version wording, Scope fields, initial_sequence, CONTRIBUTING rust-toolchain guidance, and the workspace-private package list.

README (human-facing)

Rewritten around positioning, one diagram, install, a first promote, package and capability tables, and a docs routing table. Negation and delivery archaeology removed; details link to the site.

Diagrams

tooling/diagrams/specs/ holds six Archify specifications (architecture, sequence, lifecycle, dataflow). Each passed validate --quality showcase with 0 errors and 0 warnings. tooling/diagrams/export-svg.mjs exports light/dark static SVGs into docs/public/diagrams/. The interactive HTML is not committed.

Verification

• node tooling/docs/twin-parity.mjs — 26 EN ↔ 26 CN, 0 heading mismatches.
• pnpm docs:build — complete.
• node tooling/docs/deadlink-check.mjs — 3231 links, 106 fragments, 0 broken.
• Browser check at 1440px: light/dark diagram swap follows the VitePress color mode; no horizontal overflow.

[greptile-apps]

Confidence Score: 4/5

[Low impact] The PR changes how readers find and understand SPOKE documentation, not protocol behavior.

Correct the advertised Connect version before merging; the shipped library rejects the newly documented value.

Findings

1.  Documented version cannot connect ▶
2.  Diagram adds a handshake step ▶
3.  Capability errors differ by operation ▶
4.  Bundle links lose their page ▶

Fix with agent prompt

### Issue 1
docs/explanation/connect.md:32
The new instruction to advertise `protocol_version: 2` makes custom clients incompatible with the shipped library. `PROTOCOL_VERSION` is still `1`, and `verify_hello_ed25519` rejects other values before checking the signature. Keep the advertised value at `1` and distinguish it from the newer signature requirements. Correct the Chinese page too.

### Issue 2
tooling/diagrams/specs/connect-session.sequence.json:79-85
The diagram shows the initiator sending a `ConnectSession` before the responder sends another one. The actual handshake sends only one snapshot, from the responder immediately after its hello. Readers following the diagram may send an unexpected frame or wait for an extra reply. Remove the initiator-to-responder snapshot and regenerate both SVGs.

### Issue 3
docs/agents.md:71
Not every missing capability returns `capability_missing`. The responder returns `op_unsupported` for unnegotiated tools and optional port families, and for a missing `ke-ownership` requirement. Agents following this rule can generate error branches that miss those responses. Limit the claim to the families that use `capability_missing`, or name both errors. Correct the Chinese page too.

### Issue 4
tooling/docs/build-llms.mjs:49-52
`absolutize` leaves page-local links such as `#cognition-selection-spoke-cognition` unchanged. Once the pages are combined into `llms-full.txt`, those links lose their original page address, so agents cannot resolve them back to the intended site sections. Pass the source page into `absolutize` and turn fragment-only links into full site URLs before combining the pages.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR adds agent-facing documentation, a generated English bundle, rewritten READMEs, and six protocol diagrams.

• Code assistants get a guide to SPOKE’s sources and documentation.
• The README guides new readers from SPOKE’s purpose to a first promote.
• Six protocol diagrams show how SPOKE’s parts and workflows fit together.
• Reference pages and examples now match SPOKE’s schemas and generated APIs.

Diagram

sequenceDiagram
    participant I as Initiator
    participant R as Responder
    I->>R: Signed ConnectHello
    R->>I: Signed ConnectHello with peer_nonce
    R->>I: Signed ConnectSession
    I->>R: ConnectInvokeRequest, sequence 0
    R->>I: ConnectInvokeResponse

Loading

_{Reviews (1) · Last reviewed commit: "docs: restructure for agent consumption ..." · Reviewed by Greptile}

[wood-s-inspector]

✅ Verdict: ship it · Score 100% (mergeable)

Findings	Count
🔴 must-fix	0
🟠 should-fix	0
🟡 may-fix	0
🔵 nit	0

📋 Review

Findings

none

Revalidated findings

Reassessed 0/13 prior finding(s) this round · 13 invalid-output · 0 omitted · 0 over cap · 13 recheckable · context coverage: truncated

finding	disposition	evidence	thread
Diagram gate's "accessible title" assertion passes on nested node titles, so it cannot catch the regression this PR fixes	unverifiable (invalid-output)	-	-
export-svg.mjs usage header hardcodes a macOS Playwright Chrome path and a docs/public input	unverifiable (invalid-output)	-	-
Diagram gate reports every read failure as "missing", discarding the real cause	unverifiable (invalid-output)	-	-
Contradictory diagram HTML delivery paths: specs and exporter target docs/public, README says /tmp and "not committed"	unverifiable (invalid-output)	-	-
Committed diagram SVGs have no regeneration/verification gate and their generator is an unpinned external skill	unverifiable (invalid-output)	-	-
Agents page states the dispatch deny codes backwards for every non-memory family	unverifiable (invalid-output)	-	-
<title> requirement dropped and aria-labelledby mandated without updating the documented gate contract	unverifiable (invalid-output)	-	-
Rewritten deny-code trap drops the spoke-cognition capability_missing case (EN+ZH readers now misclassify it as op_unsupported)	unverifiable (invalid-output)	-	-
aria-labelledby idrefs are checked by raw substring match, so a non-id attribute satisfies the new accessible-name gate	unverifiable (invalid-output)	-	-
Agent reading contract omits TimelineEvent.computable_logs from the l2-computable row	unverifiable (invalid-output)	-	-
Connect explanation says the hello advertises protocol_version 2, contradicting the reference page, the spec and the shipped constant	unverifiable (invalid-output)	-	-
Idref string is interpolated unescaped into a RegExp: wildcard false matches and an uncaught SyntaxError crash	unverifiable (invalid-output)	-	-
Exported SVGs strip lang and aria-labelledby but keep the <title>, losing the accessible name	unverifiable (invalid-output)	-	-

Linked-issue AC

none

✅ Verified

none

🗑️ Considered & rejected

none

🛠️ Plan to fix

none

Review 4 · commit 06a6173 · since 3c9d79c

[wood-s-inspector]

mstar-inspector line comments · round 1 · f06e397

[wood-s-inspector]

mstar-inspector line comments · round 2 · d8c160a

[wood-s-inspector]

mstar-inspector line comments · round 3 · 3c9d79c