docs: missing_docs audit bookkeeping (surface map + snapshot)

[hongyi-chen]

What

Companion audit-bookkeeping PR for this missing_docs drift-watch run. Updates the skill's reference files only — no user-facing docs pages change here.

Surface map (feature_surface_map.md):

• /theme slash command → internal — Warp Agent CLI (TUI)-only (SlashCommandSurfaces::TuiOnly, Availability::ALWAYS), like /voice and /version. Not present in the GUI, so not on the public slash-commands page.
• appearance.theme setting → internal — Warp Agent CLI (TUI) color theme (SettingSurfaces::TUI in tui_theme.rs), like general.autoupdate_enabled and appearance.zero_state.*. The GUI theme setting is the separate appearance.themes.theme, which is already documented.

Snapshot (surface_snapshot.json):

• Regenerated so the next drift-watch run diffs against the current baseline. This records the surfaces that were triaged and deferred (below), plus the oz agent --remove-prompt flag documented in the companion CLI PR (docs: document named-agent base prompt flag in CLI reference #387).

Why

Per the missing_docs skill's PR strategy, all feature_surface_map.md and surface_snapshot.json edits from a run are collected into a single companion bookkeeping PR (these are shared files; splitting them across feature PRs causes merge conflicts). The mappings above stop /theme and appearance.theme from being re-flagged as gaps every run.

Validation

• Re-ran the audit after these changes: undocumented_slash_commands, undocumented_settings, and all 9 surface_changes are resolved; map_hygiene is 0; completeness accounting reports no unaccounted items; no audits skipped (exit 0).

Deferred findings (summarized so nothing is silently dropped)

The remaining 76 audit gaps are intentionally deferred:

• 44 undocumented API endpoints (/agent/* messaging/events/schedules/artifacts, /factory/*) — warp-server is private and these are not in the released OpenAPI spec. Released endpoints should go through the sync-openapi-spec skill; the rest are internal/unreleased. Not hand-documented per the public/private guardrail.
• evaluations / evaluations/:evaluationId Oz web app routes + factory/scorers API routes — Factory/Evaluations preview surface, not publicly documented yet. Recorded in the snapshot; will re-flag on GA.
• WellKnownMcpIds feature flag (dogfood) — snapshot-tracked only; no docs until promotion.
• 32 potentially_stale_docs (LOW terminology) — owned by the style_lint skill. Many are legitimate usages ("Warp Terminal" distinguishing from Oz on harness/enterprise pages, "AI credits" on billing pages).

The one actionable public/GA gap this run (named-agent base prompt CLI flag) is documented in #387.

Conversation: https://staging.warp.dev/conversation/5113be3f-fb48-437d-9e4e-59fd0269e2ee
Run: https://oz.staging.warp.dev/runs/019fa484-f76e-7a51-a25b-58112517462a

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 27, 2026 5:13pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR updates missing-docs audit bookkeeping only: it maps the Warp Agent CLI-only /theme slash command and appearance.theme setting as internal exceptions, and refreshes the surface snapshot for newly observed feature flags, CLI flags, API routes, slash commands, settings, and Oz web routes.

Concerns

• No blocking concerns found. The changed files are reference data only, the added surface-map entries match the audit parser's expected key -> target format, and the security pass found no security-relevant changes.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz