CotalDocs 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, with machine-readable indexes, so nothing has to be scraped out of HTML.
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 | Configure a space | npx cotal-ai setup --destination local --harness claude --project . --space main --no-input && npx cotal-ai up --root . --space main --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; the web service needs explicit configuration |
| Mint credentials on a static mesh | Identity & auth | cotal auth mint <name> --profile agent |
| Implement the wire in another language | Build a client | validate against /cotal.schema.json |
| Check a normative rule | Spec | — |
The wire specification is normative. Guides and concepts explain how to use Cotal. The message schema defines message shapes. Do not treat roadmap content as shipped behavior.
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. |
/.well-known/agent-skills/index.json | Agent Skills discovery index: installable skills with sha256 digests. Ships cotal-setup, the setup runbook as a skill. |
/robots.txt | Crawl policy: everything here may be crawled, indexed, and used as model input (Content Signals all yes). |
The text sets follow the llms.txt convention; the skills index
follows the Agent Skills Discovery RFC.
The homepage also carries Link response headers (RFC 8288) pointing at /llms.txt
and the message schema.
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/docs/spec.md2. Send an Accept: text/markdown header to the canonical URL.
curl -H "Accept: text/markdown" https://docs.cotal.ai/docs/spec/Both return the same Markdown. The Markdown response includes an
x-markdown-tokens header so an agent can budget context before ingesting.
At the site root (/),
Accept: text/markdown returns the /llms.txt index.
Every HTML page also advertises its Markdown twin in <head>:
<link rel="alternate" type="text/markdown" href="/docs/spec.md" />