docs: Agent runs guide and platform tokens (DO NOT MERGE until Phase 2)

[sre-helmcode]

Merged early at the owner's request (2026-10-10) so the docs can be reviewed live; the feature itself stays canary-only until Phase 2 ships.. The feature is built and verified in production but not open to the community yet; these docs ship with the opening.

What

Member-facing docs for Agent runs (give Pi or Hermes a task inside a workspace) and the new platform tokens (nan_pat_...).

• New page runs.mdx in src/content/docs ("Agent runs") and src/content/docs-es ("Runs de agentes"), group Guides, order: 19, right after Workspaces. Sections: before you start, portal (Runs tab, New run form, live page, cancel), where the agent works (worktree rules), states, concurrency and queue, inference and secrets, CLI (nan run, nan runs, flags, Ctrl-C, exit codes), API (API keys vs Tokens, create / follow with curl -N / cancel / list, SSE frames, errors), FAQ.
• workspaces.mdx (both): new short section "Run agents on tasks" / "Pon a tus agentes a trabajar en tareas", before Backups, linking to the guide.
• nan-cli.mdx (both): new "Runs" section before Updating.
• intro.md (both): link in "Where to go next".
• examples.md / apps.md: order 19/20 -> 20/21 (orders must stay gapless).
• There is no separate account / API key doc page, so the Tokens explanation lives in runs.mdx ("API keys and tokens").
• src/lib/mdxToText.ts: the /api/docs text extractor threw on every MDX expression, so a {/* ... */} placeholder would have broken /api/docs/runs.md. Comment-only expressions are now dropped; any other expression is still refused. Tests in src/tests/lib/mdxToTextComments.test.ts. (The page no longer has placeholders, but the fix stays: it is harmless and keeps future placeholders safe.)
• New src/tests/layouts/runsDocs.test.ts (51 tests, including the screenshots: referenced in order, files exist, WebP size matches, alt/caption present and translated, no ids or infra words, folder holds only published files, UI labels and the CLI/API mapping): placement, every fact below, valid JSON in the create example, in-page anchors resolve, docs links exist, no internal infra words, no em-dashes, no real-looking secrets, extractor serves the page, EN/ES same structure, inbound links from Workspaces / CLI / intro.

Screenshots

The owner's three captures are in public/docs/runs/ as WebP (metadata stripped; the sidebar cropped off the Runs tab capture and the empty bottom off the run page), embedded with <Screenshot> in both locales:

1. runs-01-tab.webp (1400x760): Runs tab, Agent runs card, history and New run.
2. runs-02-new-run.webp (1046x1500): the New run form.
3. runs-03-run-page.webp (1400x710): a running run with Cancel run and the live Output.

They show only the owner's workspace "test", run tasks and token counts. The portal copy uses the real UI labels (Task, Folder, Separate branch Auto/On/Off, Time limit, Start run, Cancel, Cancel run); the CLI and API sections keep the technical names and add a one-line mapping (Folder = --cwd / cwd, Separate branch = --worktree / git_isolation, Time limit = --timeout / timeout_seconds, Task = prompt).

Verified facts (prod E2E 2026-10-10), for reviewers

Note: this list uses the technical names (prompt, working directory, worktree, timeout). The portal shows them as Task, Folder, Separate branch and Time limit (see the screenshots); the docs use the UI labels in the portal sections and the technical names in the CLI/API sections.

• A run gives an agent (Pi or Hermes, whichever is installed in the workspace) a task inside one of your workspaces; it keeps running if you close the page/terminal; you get live logs, the result and, for git repos, a branch.

• Portal workspace page tabs: Overview, Runs, Console, SSH keys, Events, Backups. Runs tab has the history and a "New run" button (fields: agent, prompt up to 32 KiB, working directory default /home/nan, worktree auto/on/off, timeout 15/30/60/120 min; confirmed in cloud-ui src/lib/runs.ts: default 30 min, options 15 min / 30 min / 1 hour / 2 hours). Clicking a run opens its live log page; Cancel asks for confirmation.

• Folder behavior: working directory inside a git repo and worktree auto (default) or on: isolated git worktree on branch nan-run/<first 8 chars of run id>, commits its changes there, never pushes, checkout untouched; no changes: branch deleted. Not a repo with auto: works directly in the folder (no branch). worktree=on on a non-repo folder fails with a config error. Folder must be under /home/nan.

• Concurrency per workspace: Free/Micro 1, Nano 2, Basic 3, Medium 5, Large 8. Plus per-member total across workspaces of 5 (8 with Premium), shared with inference concurrency. Extra runs queue FIFO; up to 20 queued per workspace, 50 per member, 60 new runs per hour.

• Each run is its own resource-limited process in the workspace; a runaway run is stopped alone; SSH sessions and always-on agents keep working.

• States: queued, starting, running, succeeded, failed, cancelled, timed_out. Cancel stops within seconds. Timeout 60 s to 2 h via API/CLI (UI 15 min / 30 min / 1 hour / 2 hours, default 30 min).

• Inference: runs use the workspace's own inference key and count against plan usage. Creating runs requires a plan with inference (else 403 tier_restricted, portal shows upgrade dialog). Secrets in the workspace env file are masked as *** in run logs.

• CLI (nan v0.1.24+): curl -fsSL https://nan.builders/install | bash, nan auth login; nan run [--ws NAME] [--agent pi|hermes] [--model M] [--cwd PATH] [--worktree|--no-worktree] [--timeout 30m] [--detach] [--json] ("prompt" | -f prompt.md | -); nan runs ls|show|logs [-f]|cancel. One workspace: --ws optional, otherwise lists them and exits 64. Exit codes: 0 succeeded, 1 failed, 2 timed_out, 3 cancelled, 4 config/agent/key problem, 64 usage, 65 auth, 69 API unavailable, 75 --detach accepted. Ctrl-C once detaches, twice within 2 s cancels. nan runs logs <id> --json prints one JSON event per line.

• API (base https://api.nan.builders): POST /v1/runs {workspace (name or id), agent, prompt, cwd, git_isolation (null|true|false), timeout_seconds, model} with optional Idempotency-Key; GET /v1/runs?workspace=&state=&limit=&cursor=; GET /v1/runs/{id}; GET /v1/runs/{id}/events (SSE with Accept: text/event-stream; frames id: + event: run_event|state|end, heartbeat comment every 15 s, resume with Last-Event-ID; JSON pages otherwise with ?after=); POST /v1/runs/{id}/cancel. Errors use the OpenAI envelope {"error":{"message","type","param","code"}}.

• Credentials: Settings -> API Keys = inference AND platform API, only for plans with inference. Settings -> Tokens = nan_pat_... platform tokens: platform API only (runs, list workspaces), never inference; shown once; up to 10 active; expiry 30/90/365 days or never; revocable; any member with an active subscription can create them. Workspace keys cannot manage runs (403), so an agent cannot launch runs by itself.

• CLI v0.1.25 (helmcode/nan-cli litellm-test usage-hook ConfigMap is at 98.1% of the annotation cap and will break the next hook edit #42) authentication for runs, first found wins: NAN_TOKEN env var (nan_pat_ token or sk- key; never written to disk) > --token-file PATH (first line; refused on unix if readable/writable by others: chmod 600) > token saved with nan auth login --api-token (stdin only, hidden on a terminal, verified with GET /v1/runs?limit=1, saved 0600 in a separate field so the Setup tab never copies a platform token into tool configs) > session from nan auth login > saved sk- API key. Platform tokens only work for runs: nan me, nan metrics usage and the dashboard need a session. nan --version prints nan <version>. GitHub Actions example copied from the nan-cli README on origin/main.

Other sources: devops AGENT-AUTOMATIONS-PHASE1.md on origin/main (§2.1.3 API and error codes, §2.1.4 admission, §2.2.6 worktree, §2.4 CLI) and the nan-cli README on origin/main (Agent runs section; Ctrl-C detach also exits 75; runs commands use the nan auth login session or the Setup API key).

Test evidence

• npx vitest run: 73 files, 1599 tests passed (ran 3 times; once api/docs.test.ts > returns 200 with a valid manifest payload hit the 5 s timeout under full-suite load, passes alone and on the next two full runs; it parses every docs page, so it is load-sensitive).
• npm run build: complete.
• Dev server: /docs/runs, /es/docs/runs render; in-page anchors (including accented Spanish ids like #dónde-trabaja-el-agente) resolve; /api/docs/runs.md serves the page and manifest.json lists runs.

No VERSION file in this repo, nothing to bump.

🤖 Generated with Claude Code

[sre-helmcode]

Blocking reviews (Opus, foreground) at head 68fb272:

• QA: APPROVED (round 1 at 8a49240 approved with nits; nits applied).
• UX: APPROVED (round 1 at 8a49240 had 1 blocker: tokens described as not worth stealing, although they can start runs that spend the plan; fixed in both locales).

Open non-blocking nits: pin the 30-minute stream cap and the cross-page anchors (#connect / #conectarte) in tests; mention the upgrade dialog in the no-inference FAQ; ES exit-code row 2 wording.

Still DO NOT MERGE until Agent Automations opens (end of Phase 2).

[sre-helmcode]

Screenshots + UI labels round. Blocking reviews (Opus, foreground) at head 6001595: QA APPROVED, UX APPROVED. (At d7c7a04 both flagged the mapping sentence splitting the API field table; fixed and pinned by a contiguity test.) Still DO NOT MERGE until Agent Automations opens (end of Phase 2).

[sre-helmcode]

Portal Time limit default (30 min, options 15 min / 30 min / 1 hour / 2 hours, per cloud-ui src/lib/runs.ts) documented and pinned. QA (Opus, foreground) APPROVED at head b85d89e. Still DO NOT MERGE until Agent Automations opens (end of Phase 2).

[sre-helmcode]

CLI v0.1.25 authentication (NAN_TOKEN > --token-file > nan auth login --api-token > session > saved API key), CI/GitHub Actions example, --token-file flag, nan runs logs --json event types, min version 0.1.25. QA (Opus, foreground) APPROVED at 37f6f88 and, after a one-sentence nit fix, APPROVED at head baa3df4. Still DO NOT MERGE until Agent Automations opens (end of Phase 2).