# For AI agents

Everything on this site is readable without parsing HTML. If you are pointing a model at
Shruwd, start here.

## The four entry points

| URL | What it is |
|---|---|
| [`/llms.txt`](https://shruwd.io/llms.txt) | A curated index. Every page, grouped by section, each linking to its markdown |
| [`/llms-full.txt`](https://shruwd.io/llms-full.txt) | The entire documentation as one file, each page tagged with its source URL |
| [`/skill.md`](https://shruwd.io/skill.md) | A procedure for setting a brand up end to end, including the one step a human must do |
| Any page `+ .md` | That page as plain markdown |

Appending `.md` works on every docs URL:

```
/docs/getting-started/quickstart      the page
/docs/getting-started/quickstart.md   the same page as markdown
```

The markdown is the source these pages are built from, not a conversion of the rendered
HTML. Presentational components are translated rather than dropped — a callout becomes a
labelled blockquote, a card becomes a link — so nothing loses its meaning on the way out.

Every page also declares its markdown twin in the HTML head, so a client that prefers
markdown can find it without knowing the convention:

```html
<link rel="alternate" type="text/markdown" href="https://shruwd.io/docs/…​.md">
```

## Copying a page by hand

Every page carries a **Copy page** control under its title. It copies that page's markdown
to your clipboard, and its menu opens the same page in ChatGPT or Claude with the URL
already loaded.

## Reading the API instead

The REST API describes itself:

```
https://shruwd.io/openapi.json
```

That OpenAPI 3.1 document is the contract — the TypeScript SDK's types are generated from
it. It needs no authentication to read, and every page names it in its head as
`rel="service-desc"`.

The [MCP server](https://shruwd.io/docs/api/mcp-server.md) is described at
[`/.well-known/mcp.json`](https://shruwd.io/.well-known/mcp.json): the package, the command and the key it
needs, in the [mcp-manifest](https://mcp-manifest.dev) format.

## Reading a metric correctly

This is the thing agents most often get wrong, so check any output against it.

Every metric comes back with its uncertainty attached, or not at all:

```json
{ "state": "ok", "point": 0.142, "lo": 0.081, "hi": 0.226, "n": 42 }
```

- `point`, `lo` and `hi` are proportions from 0 to 1: 0.142 is 14.2%.
- `state: "insufficient_data"` means fewer than ten responses exist. **It is not zero.**
  Say "not enough data yet", never "0%".
- Never report `point` without `lo` and `hi`. The interval is often wide, and a bare
  number reads as far more certain than the measurement is.
- Never call a change an improvement from two point estimates. Shruwd applies its own
  [movement gates](https://shruwd.io/docs/metrics/when-a-number-has-moved.md) and reports the verdict — use
  that rather than recomputing it.

There is no shape in the API that returns a number without its interval. That is
deliberate, and it holds for agents exactly as it does for the dashboard.

## Next steps

- [API overview](https://shruwd.io/docs/api/api-overview.md) — authentication, errors, limits
- [MCP server](https://shruwd.io/docs/api/mcp-server.md) — the tool interface for Claude and Cursor