Add CORAL.md deep dive + link CoralOS docs across code and READMEs

- CORAL.md: source→agents→example walkthrough of the CoralOS integration —
  the MCP client, agent orchestration, the capabilities only Coral provides
  (§5, tied to the docs), an end-to-end round, a "how to expand it" section,
  and a §10 index of the official docs.
- Link the official CoralOS docs inline at each referenced point in code:
  coral/mcp.ts (@see per primitive), coral/server.ts, market/protocol.ts,
  round.ts + marketplace/start.ts (create-session), bridge/server.ts (puppet +
  extended state), coral.toml, docker-compose.yml, and the agent manifests.
- Add matching doc links to the Coral-facing READMEs (buyer/seller/broker,
  marketplace, agent-economy, txodds/coral) and the root README.

URLs verified against https://docs.coralos.ai/llms.txt.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: trilltino

CORAL.md

@@ -170,7 +170,8 @@ one per concern:
   the **devnet guard** that throws on a mainnet RPC unless `ALLOW_MAINNET=1`, so it applies everywhere
   value moves.
 - **`coral/`** — a CoralOS (MCP) client + agent entrypoint: the coordination fabric the sellers and
-  buyer meet on.
+  buyer meet on. Deep dive, source → example: **[CORAL.md](CORAL.md)**; official docs:
+  [docs.coralos.ai](https://docs.coralos.ai/welcome).
 - **`market/`** — the WANT/BID/AWARD wire format: the negotiation protocol, pure and testable.
 
 ### The escrow contract — the settlement spine

README.md

@@ -12,6 +12,11 @@ buyer ──"request <service>"──▶ broker
 Two on-chain settlements per request; the broker keeps the spread. This is "money flowing through a
 graph of agents" — the agent-economy headline.
 
+> **CoralOS docs:** the broker opens **one Coral thread per seller** and correlates each reply per-thread
+> — [Threads](https://docs.coralos.ai/concepts/threads) +
+> [Coordination](https://docs.coralos.ai/concepts/coordination). How it's wired in the kit:
+> [/CORAL.md](../../CORAL.md).
+
 ## How it works
 
 - Reuses the kit's pieces: `payment.ts` (seller-side — charges the buyer, dynamic price) and

coral-agents/broker/README.md

@@ -11,6 +11,11 @@ WANT -> BID* -> AWARD
   -> ARBITER_RELEASED
 ```
 
+> **CoralOS docs:** these messages ride Coral threads with `@mentions`
+> ([Threads](https://docs.coralos.ai/concepts/threads)); the buyer blocks on bids and waits for sellers
+> to come online via [Coordination](https://docs.coralos.ai/concepts/coordination), all inside a
+> [Session](https://docs.coralos.ai/concepts/sessions). End-to-end wiring: [/CORAL.md](../../CORAL.md).
+
 `SETTLEMENT_MODE=direct` keeps the legacy base escrow path available, but the TxODDS CoralOS round uses
 `SETTLEMENT_MODE=arbiter` so the buyer cannot unilaterally claw back after delivery.
 

coral-agents/buyer-agent/README.md

@@ -1,3 +1,7 @@
+# Agent manifest — coral-server reads this to discover, launch, and configure the agent.
+# Docs: https://docs.coralos.ai/reference/agent · [options] table
+# https://docs.coralos.ai/reference/agent/tables/options · docker runtime
+# https://docs.coralos.ai/reference/agent/tables/runtimes/docker · whole-kit walkthrough /CORAL.md
 edition = 4
 
 [agent]

coral-agents/buyer-agent/coral-agent.toml

@@ -13,6 +13,12 @@ WANT service=txline arg="edge <fixtureId>"
   -> DELIVERED {teams, odds, analysis}
 ```
 
+> **CoralOS docs:** the loop is `wait_for_mention → reply` on a shared thread
+> ([Threads](https://docs.coralos.ai/concepts/threads),
+> [Coordination](https://docs.coralos.ai/concepts/coordination)); coral-server launches this agent into a
+> [Session](https://docs.coralos.ai/concepts/sessions) from its
+> [manifest](https://docs.coralos.ai/reference/agent). Kit walkthrough: [/CORAL.md](../../CORAL.md).
+
 The seller only delivers after `isFunded` confirms the escrow names its payout wallet and holds at
 least the quoted price. In arbiter mode it checks the escrow buyer as the vault PDA from `DEPOSITED`,
 not the human buyer wallet.

coral-agents/seller-agent/README.md

@@ -1,3 +1,7 @@
+# Agent manifest — coral-server reads this to discover, launch, and configure the agent.
+# Docs: https://docs.coralos.ai/reference/agent · [options] table
+# https://docs.coralos.ai/reference/agent/tables/options · docker runtime
+# https://docs.coralos.ai/reference/agent/tables/runtimes/docker · whole-kit walkthrough /CORAL.md
 edition = 4
 
 [agent]

coral-agents/seller-agent/coral-agent.toml

@@ -11,6 +11,9 @@
 services:
 
   # ── CoralOS — MCP bus that launches the agents per session ──────────────────
+  # Docs: running coral-server https://docs.coralos.ai/reference/server/docker · it spawns agent
+  # containers via the mounted docker.sock (Docker-in-Docker):
+  # https://docs.coralos.ai/guides/production/docker-in-docker · whole-kit walkthrough /CORAL.md
   coral:
     # Pinned by digest for reproducibility (what `:latest` resolved to on 2026-06-27). Bump:
     #   docker pull ghcr.io/coral-protocol/coral-server:latest

docker-compose.yml

@@ -8,6 +8,12 @@ Every payment is a real on-chain **devnet** transaction. CoralOS (coral-server)
 fabric — a pure MCP message bus. Payments are settled agent-side in SOL, so coral-server runs
 **stock and wallet-free** (no patched image, no keypair in the server).
 
+> **CoralOS docs:** agents run in a [Session](https://docs.coralos.ai/concepts/sessions) over
+> [Threads](https://docs.coralos.ai/concepts/threads); the human "checkout" door injects messages via the
+> [Puppet API](https://docs.coralos.ai/api-reference/puppet/send-message) and reads replies from
+> [session state](https://docs.coralos.ai/api-reference/local/get-extended-session-state). How it's all
+> wired in the kit: [/CORAL.md](../../CORAL.md).
+
 ```
                       ┌──────────────────────────┐
                       │   coral-server :5555      │  stock, wallet-free MCP bus

examples/agent-economy/README.md

@@ -106,7 +106,11 @@ function ensureSession(): Promise<string> {
   return session
 }
 
-/** Inject a message into a thread as user-proxy. */
+/**
+ * Inject a message into a thread AS the user-proxy agent — the human-in-the-loop puppet API.
+ * @see https://docs.coralos.ai/api-reference/puppet/send-message — send as an agent
+ * @see https://docs.coralos.ai/guides/integrating-with-your-app — driving Coral from your app
+ */
 async function inject(sid: string, threadId: string, content: string) {
   const res = await fetch(`${BASE}/api/v1/puppet/${NS}/${sid}/user-proxy/thread/message`, {
     method: 'POST', headers: AUTH,
@@ -135,6 +139,7 @@ function collectMessages(node: unknown, out: Msg[] = []): Msg[] {
 /**
  * Poll the extended session state until a message in `threadId` contains `marker`; return its text.
  * The puppet API is send-only (no read), so replies are read from the session state instead.
+ * @see https://docs.coralos.ai/api-reference/local/get-extended-session-state — the transcript endpoint
  */
 async function pollThread(sid: string, threadId: string, marker: string, timeoutMs = 35000): Promise<string> {
   const deadline = Date.now() + timeoutMs
@@ -167,6 +172,7 @@ app.post('/order', async (req, res) => {
     const query = prompt ? `${service} ${prompt}` : service
     const sid = await ensureSession()
 
+    // Open a thread AS the user-proxy. @see https://docs.coralos.ai/api-reference/puppet/create-thread
     const tres = await fetch(`${BASE}/api/v1/puppet/${NS}/${sid}/user-proxy/thread`, {
       method: 'POST', headers: AUTH,
       body: JSON.stringify({ threadName: `order-${Date.now()}`, participantNames: ['seller-agent'] }),