# The complete guide to Wake

> Everything on one page: what Wake does, the first request with no key, opening a desk (by hand or by an agent), claiming the site, installing the tracker, what every screen shows, goals, Markdown for agents, the front door and the listings, the API, the MCP server, the CLI, destinations, alerts, the discovery files, pricing, privacy and troubleshooting. Each section links to the page that goes deeper.

## 1 · What Wake does

Wake is Agent Experience Optimization (AXO) for a website, run end to end. AI agents (ChatGPT, Claude, Perplexity, Cursor, Codex, scripted clients) already come to your site for the people behind them: to read the docs, compare pricing, sign up, download, take an API key or pay. A browser pixel never sees them, because they do not run JavaScript. Wake does four things, every week, on autopilot:

1. **Watch.** One file where the site is served reports every agent request: family, country, page, status, how it ended. Crawlers are counted apart and never sold as agents.
2. **Count the loss.** The visits that came to sign up, call the API or buy and did not finish, times what a customer is worth to you. The count is measured; the dollar figure is that count times your number, never a guess.
3. **Fix.** Where they stopped and the file-level change that lets them through, written for your coding agent, with the sessions as evidence.
4. **Check.** Next week's agents against this week's. What changed and what is next, in the Monday brief.

The first report is free. Watching and the loss count stay free for good. The changes, the problems, security and the weekly brief are $100 a month after a 7-day trial with no card ([Pricing](/wake/docs/pricing)).

## 2 · First request, no key, no account

The free report for any public site, as JSON:

```bash
curl "https://wakeagents.ai/api/wake/v1/public/readiness?host=example.com"
```

It returns scores out of 100 (access, information, measurement), the blockers, and publish-ready `llms.txt` and `robots.txt`. The same tool answers over MCP at `https://wakeagents.ai/api/wake/v1/public/mcp` (`wake_check_site`, `wake_about`, `wake_signup`); a GET on that URL returns the server card, a POST speaks JSON-RPC 2.0. The browser version is [/wake/start](/wake/start): a deep scan, a task list and `wake-playbook.md`.

## 3 · Open a desk

A desk is one website on one account. An account holds up to three sites, and teammates can be invited from Settings → Team.

- **By hand**: [/wake/signup](/wake/signup) with an email and a password, or with Google. Accepting the [Terms](/wake/docs/terms) and the [Privacy policy](/wake/docs/privacy) is part of the form.
- **By an agent**: the same account and desk, without a browser, with an API key in the answer:

```bash
curl -X POST https://wakeagents.ai/api/wake/v1/public/signup \
  -H "Content-Type: application/json" \
  -d '{"site":"https://your-site.example","email":"you@your-site.example","terms_accepted":true}'
```

The answer is `201` with the desk URL, `api_key` (shown once), the MCP URL and the next steps. The person later signs in with Google using that email, or sets a password at [/wake/forgot](/wake/forgot). The same action is the MCP tool `wake_signup`. Limits are the ones the form has: one desk per host, rate-limited, terms required. An email that already has an account gets `200` and no new desk.

## 4 · Claim the site

Ownership gates the tracker keys, the readiness report, the listing plan, the front door and the fixes. Open the desk → **Install → step 1** and add one of:

- `<meta name="wake-verify" content="…">` in the homepage `<head>` (preferred),
- `https://<host>/.well-known/wake-verify.txt` with the body shown,
- a DNS TXT record at `_wake-verify.<host>`.

Wake checks every 30 seconds while the page is open; **Check now** checks at once. The checker names itself `WakeVerify/0.1` and follows one same-site redirect. Over the API: `POST /api/wake/v1/verify` (MCP: `wake_verify`). Details and the per-method failure reasons: [Install](/wake/docs/install#1-·-ownership).

## 5 · Install the tracker

Press **Generate the file** on the desk (API: `POST /api/wake/v1/provision`, MCP: `wake_provision`, CLI: `wake install --kit --out ./wake-collector`). You get, once, an ingest key and deploy-ready files that already carry it:

| File | Where it runs |
|---|---|
| `cloudflare-worker.js` + `wrangler.toml` | A Cloudflare Worker route in front of your origin. Recommended in front of any stack, hosted builders included. Sees every status. |
| `express.js` | Express or Connect middleware on Node ≥ 18. Sees every status. Behind a proxy add `app.set("trust proxy", 1)` before it. |
| `nextjs-middleware.js` | Next.js `middleware.ts` (`proxy.ts` on Next.js 16). Middleware cannot see statuses, so wrap the route handlers agents call with the exported `withAxo()`; api, auth, account and checkout routes are not reported without it. |

What each agent request sends: timestamp, method, page class and page path, status, the user-agent (used to name the family, then discarded), a country code when the platform provides one, the network operator name, and an opaque per-agent hint computed with your secret. Secrets come from `AXO_SITE_SECRET` and `AXO_INGEST_KEY` in the environment first, then the literal in the file. **Rotate keys** mints new ones; the deployed file stops until redeployed and nicknames restart.

**First event.** Wake never sends test traffic. One request as an agent after the deploy produces it:

```bash
curl -s -o /dev/null -A "WakeFirstEvent/1.0" https://<host>/
```

**The human tell** (Express): `<script src="/__wake/i.js" defer></script>` in the layout. A page that reports a person is dropped on your server; a silent browser-looking page view goes out as a headless suspect.

**Which account the agent acted for**: in your auth code set `res.locals.axoAccount = user.id` (Express) or the response header `x-axo-account` (any stack). The collector hashes it with your secret and strips the header, so the desk can show which agents acted for which of your accounts without holding an id.

The whole install can be handed to a coding agent: Install → step 1 → **Hand it to your AI**, or the prompt at the end of [Install](/wake/docs/install#let-your-ai-do-the-whole-install).

## 6 · What the desk shows

| Screen | What it answers | Plan |
|---|---|---|
| **Overview** | The week in one look: agents, visits, the funnel, "Came to act, left without it" with the dollar figure at your number, the map of where agents come from. | Free |
| **Agents** | One row per agent (a daily nickname): family, country, network, how often it returns, stage reached, converted. | Free |
| **Pages** | What they read, page by page, hour by hour, and the common sequences. | Free |
| **Problems** | Where agents stop and what they got back: each drop-off with the visits behind it, by page class and status. | Plan |
| **Fixes** | The plan: every change in order, with evidence and a brief your coding tool applies; the before-and-after once a step is marked done. Also Goals, Worth, Markdown for agents. | Plan |
| **Security** | Agents that behaved like a threat, named by behaviour, never by address. | Plan |
| **Weekly brief** | The week as a written report, Monday by email when switched on. | Plan |
| **Reach** | Where the site is listed, the front door, arrivals per listing and one by one. | Free to watch |
| **Connect your AI** | API keys, the MCP snippets for Claude Code, Cursor, Codex and Claude Desktop, the PostHog destination. | Free |
| **Alerts** | Rules on a number or on a quiet tracker; email and signed webhooks. | Plan |
| **Settings** | Sites, team, billing, export, delete. | Free |

The funnel has five beats: discovered, read docs, authenticated, attempted an action, converted (a successful write on checkout). Friction kinds: `auth_wall`, `action_unauthorized`, `action_rejected`, `action_not_found`, `action_wrong_method`, `action_rate_limited`, `action_server_error`, `repeated_error`, `abandoned_on_error`, `docs_dead_end`. The page class is one of `home`, `docs`, `auth`, `pricing`, `checkout`, `account`, `search`, `api`, `discovery`, `other`. Full definitions: [What AXO measures](/wake/docs/axo).

## 7 · Goals: prove what an agent finished

The tracker sees requests; your code knows when the thing really happened. Name the goal at that line and it arrives as its own event, for the same agent, on the reserved page `/~goal/<name>`:

- Next.js: `await wakeGoal(request, "generation_started")` (exported by the tracker file), or the response header `x-wake-goal: generation_started` from a handler wrapped with `withAxo()`.
- Express: `res.locals.wakeGoal = "generation_started"`, or `wakeGoal(req, "generation_started")`.
- Cloudflare Worker in front of any origin: the response header `x-wake-goal: generation_started`.

Names are letters and underscores; the header is removed before the response leaves your server. A goal can also be a rule on a request the tracker already reports, such as `POST /oauth/token` answered 2xx. Fixes → Goals lists each goal with its visits by family and writes the prompt for your coding tool. API: `GET`/`POST /api/wake/v1/goals`; MCP: `wake_goals`.

## 8 · Markdown for agents

With **Serve Markdown to agents** on (Fixes), your tracker answers an agent that asks for Markdown (`Accept: text/markdown` ahead of `text/html`) with the page's own words and, at the end, the links to what can be done on your site. Browsers, requests with a cookie or an Authorization header, files, API routes, sign-in routes and machine paths are never touched. Off by default; if Wake is slow (2.5 seconds) the request goes on to your site unchanged. Check it:

```bash
curl -s -H "Accept: text/markdown" -A "WakeMarkdownCheck/1.0" https://your-site/
```

## 9 · The front door and the listings

Most sites answer `/llms.txt`, `/.well-known/mcp.json`, `/.well-known/agent-card.json` and `/mcp` with an HTML error page. Under **Reach**, one switch opens a front door for your site: Wake reads up to 60 of your public pages once (robots.txt respected) and serves them as an index, `llms.txt`, an agent card, an MCP server card and an MCP server with four read-only tools (`about`, `search`, `read_page`, `get_started`) at `https://wakeagents.ai/agents/<your-host>/…`. `get_started` hands out tracked links to the actions on your own site (install, sign up, pricing, docs), so Reach can show what an agent did after it arrived. Redirects for your own domain are listed on the screen.

A public listing is published in your name, so it starts with your click on Reach (official MCP registry, Glama, IndexNow for search assistants). Every listing hands out the same server under its own link, so arrivals credit the listing they came through. Agents, crawlers and our own test runs are counted apart. The door is off until you open it, needs a claimed site, and closes in one click. Files and rules: [Discovery files](/wake/docs/discovery).

## 10 · The API

Base URL `/api/wake/v1`. Machine description at [`/api/wake/v1/openapi.json`](/api/wake/v1/openapi.json). Auth: a key minted under **Connect your AI** (up to 10 active keys per desk, shown once, stored hashed), sent as `Authorization: Bearer wk_live_…` or `X-API-Key: wk_live_…`. One key reads one desk. 120 requests a minute per key. `window` is `24h`, `7d` (default) or `30d`.

| Method and path | Returns |
|---|---|
| `GET /` · `GET /openapi.json` | Index and OpenAPI, no auth. |
| `GET /me` | Host, verification, collector status, key label, MCP and docs URLs. |
| `GET /overview` · `/agents` · `/sessions` · `/sessions.csv` · `/funnel` · `/friction` · `/pages` · `/series` · `/alerts` | The desk's reads for a window. |
| `GET /fixes` · `GET /fix_plan` · `POST /fix/done` | Ranked fixes; the plan in order with briefs; mark a step deployed. |
| `GET /goals` · `POST /goals` | The goals and their visits; set the list. |
| `GET /insight?metric=&breakdown=&filters=&compare=` | A trend, broken down and filtered, with the previous window. |
| `GET /errors` · `GET /events` · `GET /security` · `GET /health` | Every 4xx and 5xx agents received; the newest requests; threat scoring; collector health. |
| `GET /readiness` · `GET /listing` · `POST /listing/plan` | The public site as an agent sees it; the listing plan (never publishes). |
| `POST /verify` · `POST /provision` · `GET /install?kit=1` | Ownership check; the tracker kit; collector status. |
| `GET /destinations` · `GET /alert_rules` · `GET /benchmarks` | PostHog destination; alert rules and deliveries; k-anonymous cohort medians. |
| `POST /mcp` | The MCP endpoint (section 11). |

Public, no key: `GET /public/readiness?host=`, `GET /public/about`, `POST /public/mcp`, `POST /public/signup`.

Errors are JSON `{ error, code, how_to_fix, docs }`: `401 unauthorized` (missing or revoked key, the body says how to get one), `403 unverified` (claim the site), `404 not_found` (unknown route; unknown public routes list the real ones), `429 rate_limited` (with `Retry-After`). Full reference and row shapes: [API](/wake/docs/api).

## 11 · The MCP server

`POST https://wakeagents.ai/api/wake/v1/mcp`, streamable HTTP, JSON answers, the same key as the API. One tool per question (`wake_overview`, `wake_agents`, `wake_sessions`, `wake_funnel`, `wake_friction`, `wake_fixes`, `wake_fix_plan`, `wake_goals`, `wake_pages`, `wake_alerts`, `wake_series`, `wake_errors`, `wake_events`, `wake_security`, `wake_health`, `wake_insight`, `wake_readiness`, `wake_listing`, `wake_benchmarks`, `wake_install`, `wake_destinations`, `wake_alert_rules`, `wake_me`) and four that write to your own desk only (`wake_verify`, `wake_provision`, `wake_fix_done`, `wake_listing_plan`). One prompt, `improve`: "improve this site for agents". A GET on the endpoint returns the server card; SSE-first clients get the 405 the transport asks for.

```bash
# Claude Code
claude mcp add --transport http wake https://wakeagents.ai/api/wake/v1/mcp --header "Authorization: Bearer <key>"
```

```json
// Cursor: .cursor/mcp.json
{ "mcpServers": { "wake": { "url": "https://wakeagents.ai/api/wake/v1/mcp", "headers": { "Authorization": "Bearer <key>" } } } }
```

```toml
# Codex: ~/.codex/config.toml, with WAKE_API_KEY exported in the shell
[mcp_servers.wake]
url = "https://wakeagents.ai/api/wake/v1/mcp"
bearer_token_env_var = "WAKE_API_KEY"
```

```json
// Claude Desktop and other stdio-only clients, through the CLI
{ "mcpServers": { "wake": { "command": "npx", "args": ["-y", "wake-agents", "mcp"], "env": { "WAKE_API_KEY": "<key>", "WAKE_API_URL": "https://wakeagents.ai" } } } }
```

Then ask in plain words: "What can I fix so more AI agents get through my site? Use Wake." The tool calls `wake_fix_plan`, makes the changes, deploys, and calls `wake_fix_done` for each step; the desk then compares the visits before and after. Protocol notes and every tool's parameters: [MCP](/wake/docs/mcp).

## 12 · The CLI

```bash
npm i -g wake-agents
wake login --key wk_live_… --url https://wakeagents.ai
wake status
wake fixes --window 7d
wake install --kit --out ./wake-collector
wake connect claude-code
wake mcp        # stdio bridge for Claude Desktop
```

Config in `~/.config/wake/config.json` (mode 0600); `WAKE_API_KEY` and `WAKE_API_URL` override it. Every read command takes `--window` and `--json`. [CLI](/wake/docs/cli).

## 13 · Destinations and alerts

- **PostHog**: connect your project under Connect your AI → Destinations. Every fifteen minutes the desk forwards each agent request as `agent_request` and each closed visit as `agent_session` (stage, task, friction, conversion, threat level) in PostHog's batch capture format, with `$geoip_disable` and no person profiles. Filter on `wake_site`.
- **Alerts**: rules on a number crossing a line or on a tracker gone quiet, checked every fifteen minutes; delivery by email and by signed webhook (headers `X-Wake-Event`, `X-Wake-Timestamp` and `X-Wake-Signature-V2`, an HMAC of the timestamp and the body with the secret shown once). The log of every delivery is on the Alerts screen and at `GET /alert_rules`.
- **Weekly brief**: Monday by email when switched on in Overview → Weekly brief; always readable on the desk and at `GET /api/v1/wake/brief` with a signed-in session.

## 14 · The discovery files on your own site

`llms.txt` (a Markdown index with one reason per link), `llms-full.txt` (the same with the page text inlined), `robots.txt` (a named bot does not inherit the `*` group; name the search bots you want to be cited by), `sitemap.xml` (canonical 200 URLs only, no hop redirects), `/.well-known/agent-card.json`, `/.well-known/mcp.json`. The scan at [/wake/start](/wake/start) checks them on your site and writes publish-ready copies; the front door (section 9) can answer them for you. Why each one matters: [Discovery files](/wake/docs/discovery); how a page gets quoted by an answer engine: [AEO and GEO](/wake/docs/aeo).

## 15 · Pricing

Watch is free for good: scan, Overview, Agents, Pages, the loss count, three sites, teammates, the tracker file. The Plan is $100 a month: Problems, Fixes, Security, the weekly brief, changes and alerts. Every account starts with 7 days of the whole desk and no card; when the trial ends, watching continues and nothing is deleted. Billing by card through Stripe, cancel any time from Settings. [Pricing](/wake/docs/pricing).

## 16 · Privacy and data

Kept per site: coarse events (timestamp, method, page class and page path, status, family, identity tier, country, network operator name, a daily HMAC nickname computed with your secret and folded with the UTC day), your email with the hostname, hashed keys, a sealed copy of the ingest key so the kit can be reopened, goals by name, the front-door ledger. Never kept: raw IP, user-agent strings, query strings, bodies, prompts, outputs, page content, cookies, referrers, tool arguments. Visits are kept 90 days. Export the desk as JSON and delete the account from Settings, both immediate. Sub-processors: Cloudflare, Railway, Stripe, Resend, and PostHog only if you connect it. [Privacy](/wake/docs/privacy) · [DPA](/wake/docs/dpa) · [Terms](/wake/docs/terms).

## 17 · Troubleshooting

- **401 from the ingest endpoint**: the ingest key was rotated; redeploy with the new file.
- **No events but agents visit**: the route must cover the paths agents hit (docs, API). On Next.js, api, auth, account and checkout need `withAxo()`.
- **Ownership check answers 403**: a WAF or bot rule blocks `WakeVerify/0.1`; allow it or use the DNS record.
- **Statuses missing in Problems**: the tracker cannot see them (Next.js middleware) or predates 19 Nov 2026; redeploy the current file from Install.
- **Readiness says agents cannot fetch the homepage**: the first HTTPS request returned a challenge or a non-200. Serve a plain 200 with the words in the HTML, and a `<main>` with one `<h1>`.
- **A 429 from the API**: wait the `Retry-After` seconds; 120 requests a minute per key.
- **A goal never shows**: the name must be letters and underscores, reported only after the thing succeeded, from a request the tracker reports (on Next.js, a handler wrapped with `withAxo()`).

Questions: [the short answers](/wake/docs/questions), or the address in the footer of [the site](/wake/).
