chore(missing_docs): repoint surface map at renamed /agents/ paths and refresh snapshot

[hongyi-chen]

What

Bookkeeping for a missing_docs drift-watch run. The headline change is repairing the surface map
after the IA rename.

Surface map

• Repointed 66 entries from src/content/docs/agent-platform/ to src/content/docs/agents/.
  The rename in feat(phase0): rename /agent-platform/ → /agents/ (IA restructure Phase 0) #420 moved the docs tree but left the map behind, which alone produced
  68 map-hygiene findings and 64 phantom "undocumented feature" findings — about two thirds of
  everything the audit reported.
• New GA mappings: ContextWindowUsageBreakdown (promoted dogfood → GA), GeminiEnterprise
  (promoted dogfood → GA; already covered by the BYOLLM Gemini Enterprise page), and OscHyperlinks
  (promoted preview → GA). Removed the stale OscHyperlinks ignore-list entry, which the map-hygiene
  integrity check correctly flagged as a mapped/ignored conflict.
• New internal entries for Warp Agent CLI-only surfaces (SettingSurfaces::TUI /
  SlashCommandSurfaces::TuiOnly), matching the existing precedent for that surface: /api-keys,
  /reset-statusline, /vim-mode, the five appearance.zero_state.show_* toggles, and
  agents.voice.voice_input_hold_key.
• Pruned /add-api-key and /clear-provider-api-key, which were removed from code and replaced
  by /api-keys.
• Marked the three new Factory scorer autofix-config routes internal, matching every other
  /factory route: Factory is not a released public product.

Snapshot

Regenerated with --update-snapshot so the next run diffs against this baseline.

Result

Standing findings went from 195 → 47. Completeness accounting now reports 0 findings for
feature flags, CLI commands, slash commands, settings, and map hygiene, with no unaccounted surfaces.
npm run build passes (355 pages).

Relationship to #446

#446 is an earlier bookkeeping PR from a previous run of this skill, still open. It predates the #420
rename, so it does not contain the agent-platform/ → agents/ path repair, and it also carries
an audit_docs.py OpenAPI path-parsing fix that this PR does not touch. The two overlap on
feature_surface_map.md and surface_snapshot.json, so they need sequencing: merge #446 first, then
rebase this one (the snapshot is a wholesale regen, so re-running --update-snapshot after the rebase
is the cleanest resolution).

Companion PRs from this run

• docs: document the context window usage breakdown #456 — context window usage breakdown
• docs: document selectable custom inference endpoint API formats #457 — custom inference endpoint API formats
• docs: add auto_approve_bypasses_command_denylist to the settings reference #458 — auto_approve_bypasses_command_denylist in the settings reference
• docs: document the /copy-debugging-id slash command #459 — /copy-debugging-id slash command
• docs/settings-warp-agent-menu-path — stale Settings menu paths

Closed as duplicates of existing open PRs: #455 (→ #451), #460 (→ #440 and #387), #461 (→ #439).

Deferred findings (full list)

15 warp-server public API routes missing from developers/agent-api-openapi.yaml. warp-server is
private, so per the skill's public/private guardrail these were not hand-written. All of them back
already-public surfaces, so they belong to the sync-openapi-spec skill as a separate change:

• GET /agent/artifacts/{uid}, GET /agent/artifacts/{uid}/download (back the public oz artifact commands)
• GET /agent/events, GET /agent/events/stream, POST /agent/events/{run_id}
• POST /agent/messages, GET /agent/messages/{run_id}, POST /agent/messages/{id}/read,
  POST /agent/messages/{id}/delivered (back the public oz run message commands)
• GET /agent/schedules/{id}, PUT /agent/schedules/{id}, DELETE /agent/schedules/{id},
  POST /agent/schedules/{id}/pause, POST /agent/schedules/{id}/resume (the collection endpoint is
  already in the spec)
• GET /agent/run-by-external-reference — genuinely ambiguous: it sits in agent_webhooks.go beside
  harness-support plumbing. Left unmapped rather than marked internal so it keeps resurfacing until
  someone with context classifies it.

32 terminology/staleness findings (ai credits → credits, warp terminal → Warp,
agent-mode → Agent Mode, one ambient agent → cloud agent). These are pure wording and are
owned by the style_lint skill, which has a --fix mode. Sweeping them here would have buried the
substantive changes in unrelated churn — and #452 is already an open attempt at exactly that sweep.

1 new server-side agent tool: report_external_reference. Reported by the snapshot diff. Its only
client surface is oz harness-support report-external-reference, a hidden command already mapped
internal, so there is no public surface to document yet.

Verified as already covered, no action needed: agent execution profiles in settings files
(execution_profiles is documented), computer-use overlay timing, MCP tool confirmation copy,
code-block file reference opening, logout signing out of Warp web, and the Oz icon replacement.
gcloud auto-sign-in during GCP provider setup is already handled by open PR #442.

---

Conversation: https://staging.warp.dev/conversation/c45bb2ea-d33b-4723-8249-478547f81a47
Run: https://oz.staging.warp.dev/runs/019fc891-7c04-779b-b006-328169d8a0d7

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 3, 2026 5:26pm

[hongyi-chen]

One dependency worth flagging: this PR maps OscHyperlinks to terminal/more-features/files-and-links.mdx and removes its stale ignore-list entry, but the OSC 8 content itself lands in #451 (I closed my duplicate #455 in its favor). The mapping is valid either way — map hygiene only requires the target page to exist on the base branch, and it does — but if #451 is abandoned rather than merged, that page will need the OSC 8 section written before the mapping fully reflects reality.

[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 refreshes the missing-docs surface map and snapshot after the /agent-platform/ to /agents/ documentation path rename, while classifying newly observed surfaces as documented, gated, or internal.

Concerns

No blocking concerns found. The changed doc targets in the annotated diff exist locally, the changes are reference-data-only, and spec_context.md reports that no approved or repository spec context was found for this PR.

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