chore(missing_docs): audit bookkeeping for the 2026-08-24 drift-watch run - #614

Summary

Bookkeeping companion to the missing_docs drift-watch run of 2026-08-24: surface-map entries for the two newly detected Factory REST routes, a refreshed surface snapshot, and two fixes to the staleness audit that were producing permanent false positives.

The run found no undocumented features, CLI commands, slash commands, or settings, and no map-hygiene, stale-doc-reference, unlisted-page, or changelog-verification findings. No feature doc PRs accompany this one. The only other output is #613, which syncs the OpenAPI spec.

Changes

references/feature_surface_map.md

Two new /factory routes appeared in warp-server since the last snapshot. Both are mapped internal, matching every other route in that namespace:

• POST /factory/automations/{id}/run — fires an automation's cron trigger immediately; marked x-internal: true in warp-server's canonical spec, so its own publish filter strips it.
• POST /factory/{uid}/runs — dispatches a run to a factory. This one is not marked x-internal upstream, so it needed a separate rationale: it stays out of the docs copy because the sync-openapi-spec policy excludes the entire /factory namespace (factory in EXCLUDED_TAGS plus the /factory path prefix) while the Factory REST API is unreleased. The map comment records that distinction and points at the exclusion to revisit when the API ships.

Neither is hand-documented: warp-server is private, and per the skill's "Public vs. private surfaces" guardrail an endpoint absent from the released spec is treated as not-yet-public.

references/surface_snapshot.json

Regenerated with --update-snapshot. Only those two routes changed.

scripts/audit_docs.py — staleness false positives

The staleness audit reported 29 findings, none of them actionable. Two causes were mechanical and are fixed here; the rest are triaged below.

Link and image destinations were matched as prose. strip_code_spans removed code spans so CLI examples wouldn't trip terminology rules, but left ](...) targets in place. Every single agent-mode hit was a URL slug or an asset filename — ](/knowledge-and-collaboration/warp-drive/agent-mode-context/), ](../../assets/terminal/agent-mode-suggestion-1.png). Neither is fixable wording: renaming a published page to chase a terminology change breaks inbound links, and image filenames are not reader-visible. The [...] label is left alone, since that half is prose. Removes 5 findings, two files entirely.

The generated telemetry table was matched as prose. All three privacy.mdx hits (warp ai, ai command, ambient agent) were inside the exhaustive telemetry table, which the release_updates skill's update_telemetry.py regenerates wholesale from the client's event definitions. Those strings are code-derived; editing them here is reverted on the next release, and the real fix is upstream in the event definition. The audit now stops at the ### Exhaustive telemetry table heading, mirroring the same constant that script uses. Removes 1 finding.

Net: 29 → 23 findings, with the remainder being genuine style-guide questions rather than audit noise.

Deferred findings

Nothing below was silently dropped — each was checked against source and left for the owning skill or a human decision.

Deferred to style_lint (23 low-severity terminology findings)

The missing_docs skill delegates pure wording to style_lint, and each of these is a wording judgement rather than a docs gap. Grouped by term:

• ai credits (10 files) — needs a style-guide decision first. AGENTS.md line 831 says "credits (lowercase, not 'AI credits')" and line 837 says to drop the "AI" prefix throughout, but line 833 uses "AI credits" itself when defining compute credits: "Used alongside AI credits and platform credits when describing credit types." The docs consistently follow the second reading, naming the inference bucket in the three-bucket model (AI / compute / platform). AGENTS.md contradicts itself here; resolving that is a style-guide change, not an audit fix, so the rule was left as written.
• warp terminal (7 files) — the rule already permits this "unless distinguishing," and every hit is the distinguishing case: client vs. backend in the enterprise architecture diagram, the local terminal vs. the cloud platform on the harness pages, and the product name in the enterprise product list. The one arguable hit is terminal/more-features/index.mdx ("Explore additional Warp terminal features").
• warp ai (3 files) — faqs.mdx is a deliberate historical reference ("What happened to the old Warp AI chat panel?"). The other two are the phrase "Warp AI credits," which folds into the ai credits decision above.
• ai command (1 file) — "AI Command Search" is a live feature name, still present in the client source (app/src/terminal/input.rs, app/src/settings/input.rs, app/src/tips/tip_view.rs).
• generate command (1 file) — a word-boundary artifact: the page says "generate command suggestions," a verb phrase, and Generate still ships (the page is already titled "Generate (Legacy)"). The rule was left intact rather than narrowed, since weakening it to kill one benign match risks missing a real one.

Deferred elsewhere

• warp-server ownership gap. scripts/suggest_reviewers.py resolved no owner for public_api/openapi.yaml, router/handlers/public_api/factories.go, or router/handlers/public_api/factory_automations.go — warp-server's .github/CODEOWNERS and .github/STAKEHOLDERS have no rule covering public_api/ or router/handlers/public_api/. Adding one there (a job for the sync-stakeholders skill) would let future spec syncs route themselves.

Validation

• test_audit_docs.py → 12 tests, OK (including the accounting-totality and snapshot-roundtrip checks)
• test_suggest_reviewers.py → 15 tests, OK
• Re-ran the full audit with --diff: exit 0, api_routes findings 0 (was 2), surface_changes 0 (was 2), unaccounted: none
• npm run build → exit 0

Reviewers

No reviewer assigned. The docs repo has no CODEOWNERS, and recent history on .agents/skills/missing_docs/ is almost entirely the account opening this PR, so there is no second owner to route to automatically.

Unverified claims

None — this PR adds no page content. Every claim about route visibility was checked against warp-server/public_api/openapi.yaml and public-openapi-filter.yaml, and every claim about a live feature name against the public warpdotdev/warp checkout.

Co-Authored-By: Oz oz-agent@warp.dev
Co-Authored-By: Warp agent@warp.dev