docs: audit bookkeeping (2026-07-10 drift-watch)

[hongyi-chen]

Audit bookkeeping for the missing_docs drift-watch run on 2026-07-10. Collects the surface-map and snapshot updates that accompany the sibling feature PRs, and records every deferred finding so nothing is silently dropped.

What changed

• feature_surface_map.md: allowlisted the 404 page in the Unlisted docs pages section (Astro's built-in 404 page, intentionally not in the sidebar).
• surface_snapshot.json: regenerated with --update-snapshot to re-baseline change detection (captures the new agent CLI flags, the agents.usage_display_mode setting, the NldPromptHistoryMatch dogfood flag, and the POST /api/v1/factory/avatar route).

Companion feature PRs

• oz agent run-cloud harness flags (reference/cli/index.mdx) — docs: document oz agent run-cloud harness flags #322
• agents.usage_display_mode setting (terminal/settings/all-settings.mdx) — docs: document agents.usage_display_mode setting #323

Deferred findings (not addressed in this run)

API endpoints — 19 (route via sync-openapi-spec, not hand-documented)

warp-server is a private repo, and these endpoints are not in the released OpenAPI spec (developers/agent-api-openapi.yaml), so per the skill's public/private guardrail they are NOT hand-documented. Confirm release status and route released ones through the sync-openapi-spec skill, or map internal:

• GET /agent/artifacts/{uid}
• GET /agent/events, GET /agent/events/stream, POST /agent/events/{run_id}
• POST /agent/messages, POST /agent/messages/{id}/delivered, POST /agent/messages/{id}/read, GET /agent/messages/{run_id}
• GET /agent/schedules/{id}, PUT /agent/schedules/{id}, DELETE /agent/schedules/{id}, POST /agent/schedules/{id}/pause, POST /agent/schedules/{id}/resume
• GET /factory, POST /factory, POST /factory/avatar, GET /factory/{uid}, PATCH /factory/{uid}, DELETE /factory/{uid}

Terminology / staleness — 32 (owned by the style_lint skill)

32 potentially_stale_docs findings (e.g. "warp ai", "ai credits", "agent-mode", "warp terminal", "oz agent") are pure wording issues. Per the skill, terminology/style enforcement is owned by style_lint, not missing_docs. Deferred to a style_lint sweep.

No docs needed

• NldPromptHistoryMatch feature flag (dogfood) — tracked by the snapshot only; re-flags on promotion to GA.
• Changelog "verify" items (2026.07.09): cross-window tab dragging is already documented in terminal/windows/tabs.mdx; markdown editor syntax highlighting, "Copy file path" right-click, scrollable custom-inference model lists, and the heap-profile command palette action are minor polish with no dedicated doc surface.

Validation

• Coverage re-run: undocumented_settings, unlisted_pages, surface_changes, and changelog_review all → 0. Remaining findings are the deferred API (19) and staleness (32) items above.
• npm run build succeeded (346 pages).

Conversation: https://staging.warp.dev/conversation/693d79a7-7cf9-4a67-b070-2aeb15986da6
Run: https://oz.staging.warp.dev/runs/019f4cf8-d573-7793-af78-d05ffd29cfd5

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, Comment	Jul 10, 2026 5:12pm