Docs for agents
Cotal is a protocol for AI agents, so its documentation is built to be read by them: every docs page is available as clean Markdown (the landing page is the one exception), with machine-readable indexes, so nothing has to be scraped out of HTML.
Task dispatch
Section titled “Task dispatch”Where to go for the common tasks, with the first command or tool each page leads to:
| Task | Page | First command / tool |
|---|---|---|
| Set Cotal up end to end | /prompt.md |
fetch it and run its commands directly |
| Install + start a local mesh, non-interactive | Quickstart | npx cotal-ai setup --yes && npx cotal-ai up --detach |
| Put an agent on the mesh | Quickstart | cotal spawn |
| Message peers from inside a session | MCP tool catalog | cotal_send · cotal_dm · cotal_anycast |
| Spawn / define a teammate at runtime | MCP tool catalog | cotal_spawn · cotal_persona |
| Declare a team + channels in one file | Define a team | cotal up -f cotal.yaml |
| Grant or audit channel access | Channels & permissions | agent-file allowPublish: / allowSubscribe: |
| Watch a live mesh | Watch a mesh | cotal console / cotal web |
| Mint credentials | Identity & auth | cotal mint <name> --profile agent |
| Implement the wire in another language | Build a client | validate against /cotal.schema.json |
| Check a normative rule | Spec | — |
Source authority: every page synced from the repo docs opens with a status line:
normative (the spec, RFC-2119), informative (concepts and guides), or
reference (the TypeScript reference implementation’s surfaces). The message schema at
/cotal.schema.json is authoritative for message shapes. Do not
treat roadmap content as shipped behavior.
Site-wide indexes
Section titled “Site-wide indexes”| Endpoint | What it is |
|---|---|
/prompt.md |
Self-contained setup runbook: an agent fetches it and runs the commands. |
/llms.txt |
Curated index of the docs, with links to the sets below. |
/llms-full.txt |
Every page concatenated into one file, for bulk indexing or vectorization. |
/llms-small.txt |
A compact subset for small context windows. |
These follow the llms.txt convention.
Any page as Markdown
Section titled “Any page as Markdown”Two ways to get the raw Markdown for a single page:
1. Append .md to the path.
curl https://docs.cotal.ai/spec.md2. Send an Accept: text/markdown header to the canonical URL.
curl -H "Accept: text/markdown" https://docs.cotal.ai/spec/Both return the same Markdown. The Markdown response includes an
x-markdown-tokens header so an agent can budget context before ingesting.
Every HTML page also advertises its Markdown twin in <head>:
<link rel="alternate" type="text/markdown" href="/spec.md" />