docs(skills): missing_docs audit bookkeeping (surface map + snapshot)

[hongyi-chen]

Bookkeeping for the missing_docs drift-watch audit: surface-map entries, the regenerated snapshot, and one fix to the audit script itself. No user-facing docs change here — those ship in the companion feature PRs.

Audit script fix

parse_public_api_routes only followed exported Register* call sites when walking warp-server's route registration graph. warp-server has since moved the MCP OAuth discovery routes into an unexported helper, registerMCPDiscoveryRoutes, so those routes silently dropped out of the audit's universe. That produced two misleading signals: a --diff "route removed" finding and two map-hygiene "dead entry" findings for routes that are very much alive.

The extractor now follows both spellings. Following the helper also surfaces the two path-suffixed RFC 8414 discovery variants that were never extracted before, which are mapped below.

This is the failure mode worth flagging: the audit reported removal for something that had only moved. Pruning those map entries, which is what the hygiene finding literally suggests, would have been wrong.

Surface map

• Slash commands - The Warp Agent CLI's TUI-only commands were mapped internal with a rationale that no longer holds ("not documented on the public slash-commands page"). They are documented, on the CLI reference page, so they now map there.
• AgentCliLaunchModal - Ignore-list entry. A one-time launch modal in the same class as OzLaunchModal and OrchestrationLaunchModal: it shows once, links to the CLI get-started page, and has no recurring surface.
• CLI-only settings - Statusline, theme, and start-screen settings remapped from internal to the CLI configuration page that documents them.
• New API routes, all internal - OAuth consent/grants/registration/revocation (browser and machine plumbing for third-party MCP clients, none in warp-server's canonical public spec), harness-support/commit-snapshot (x-internal: true in the canonical spec), the four new path-suffixed OAuth discovery documents, and the new Factory integration, scorer, and automation-subscription routes (Factory is not a released product; FactoryMcp is dogfood).

Verification

• test_audit_docs.py — 12/12 pass, including the snapshot round-trip and the completeness accounting check.
• test_suggest_reviewers.py — 15/15 pass.
• Full audit exits 0 with unaccounted: none.

Three undocumented_api_endpoints findings remain on this branch and are expected: GET /agent/artifacts/{uid}/download, GET /agent/run-by-external-reference, and POST /agent/runs/{runId}/scores are public in warp-server's canonical spec but stale in the docs copy. They are fixed by the companion OpenAPI sync PR, which owns developers/agent-api-openapi.yaml.

Deferred findings

Recorded here so nothing is dropped silently.

30 low-severity staleness findings — deferred to style_lint. Every one is a false positive or needs a product decision:

• agent-mode (5 files) — all hits are URL slugs (/terminal-and-agent-modes/, /agent-mode-context/) and image filenames, not prose. The staleness check strips code spans but not link targets.
• warp ai / ai command / ambient agent in privacy.mdx — verbatim telemetry event names and their descriptions. That table is generated from telemetry.json by the release_updates skill, so hand-edits would be overwritten. Fixing the wording means changing the event descriptions upstream.
• warp ai in agents/getting-started/faqs.mdx — the heading "What happened to the old Warp AI chat panel?" is deliberately historical.
• ai command in terminal/entry/index.mdx — "AI Command Search", an actual feature name.
• warp terminal (9 files) — "Warp Terminal" used where it is legitimately distinguished from the CLI or Oz.
• ai credits (10 files) — the real conflict. The style guide says use "credits" without the AI prefix, but the docs consistently name three buckets: AI credits, compute credits, and platform credits. Dropping the prefix from "alongside AI credits and compute credits" would make those sentences ambiguous. This needs a terminology decision on what the first bucket is called, not a mechanical rename.

81 --weak-coverage findings — no action. All are keyword-matching noise: the check looks for flag-name-derived phrases (e.g. "handoff local cloud" for HandoffLocalCloud) that never appear in prose. Every one maps to a real, verified page. The flag is off by default for this reason.

3 changelog items:

• SKILLS_DIRS env var in agent-driver mode — deferred. agent-driver does not exist in the public warpdotdev/warp checkout, so this is an internal harness surface, not a public one.
• Computer-use Linux background mouse fix — behavior fix, no doc change.
• Computer-use synthetic cursor in video recordings — rendering improvement to an already-documented feature.

factory-mcp bundled skill — deferred. The skill ships in the public client, but it drives the hosted Warp Factory product (the warp-factory MCP server, factory tasks, foreman) which has no public documentation and whose API is dogfood-gated. Documenting the skill would expose an unreleased product surface. Re-flag when Factory ships.

MultiLevelOrchestration flag — tracked only. Dogfood; the snapshot diff will re-flag it on promotion.

Reviewers

scripts/suggest_reviewers.py resolved @moirahuang and @warpdotdev/oss-maintainers from the warp .github/STAKEHOLDERS. The four warp-server handler paths behind the API entries (oauth2.go, factories.go, agent_artifacts.go, public_api/openapi.yaml) had no owner match and are left for manual assignment.

Conversation: https://staging.warp.dev/conversation/7e6d979d-88a2-46f0-90e1-6404a7edc72e
Run: https://oz.staging.warp.dev/runs/019fec9e-026d-7b44-bc62-8d6c8e2ccf6b

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 10, 2026 5:26pm