docs-audit: surface map + snapshot bookkeeping (2026-08-05 drift-watch)

[hongyi-chen]

Summary

Bookkeeping for the 2026-08-05 missing_docs drift-watch run: surface-map decisions for everything triaged in this run, plus a refreshed surface snapshot so the next run diffs against today's baseline. Both audit modes exited 0 with no skipped audits and no unaccounted surface items.

Changes

.agents/skills/missing_docs/references/feature_surface_map.md

• GET /.well-known/oauth-authorization-server → internal

• GET /.well-known/oauth-protected-resource/api/v1/mcp/factory → internal

  RFC 8414 / RFC 9728 OAuth discovery documents that MCP clients fetch automatically before authenticating against the hosted Factory MCP endpoint (router/handlers/public_api/oauth2.go). They are registered only when the dogfood-only factory_mcp flag is on (factory_mcp: false in config/prod.yaml), are absent from warp-server's canonical public spec, and are machine-facing protocol metadata rather than a documentable API surface.

• GET /factory/{uid}/metrics → internal

  Added to the existing Factory block. Factory is not publicly released, and the operation carries x-internal: true in warp-server's canonical spec, so the publish filter strips it from the docs copy.

• appearance.zero_state.freeze_animation_when_unfocused → src/content/docs/cli/configuration.mdx

  Warp Agent CLI-only setting (SettingSurfaces::TUI), documented on the CLI configuration page rather than the all-settings reference, matching the other appearance.zero_state knobs.

.agents/skills/missing_docs/references/surface_snapshot.json

• Regenerated with --update-snapshot. New entries: the four API routes above plus POST /api/v1/agent/runs/{runId}/scores, the Oz web app route artifacts/:artifactUid, the server tool get_media_artifact_links, and the setting appearance.zero_state.freeze_animation_when_unfocused.

Companion feature PRs from this run

• docs: document the /copy-debugging-id slash command #459 — /copy-debugging-id slash command (extended with the CLI reference and feedback guide).
• docs: document the CLI start screen freeze-animation setting #479 — CLI start screen freeze_animation_when_unfocused setting.
• docs: document shareable media artifact links and artifact media pages #480 — Shareable media artifact links and artifact media pages.
• docs: use canonical agent terminology in software factory guides #481 — Agent terminology fixes in the software factory guides.

The surface-map entry for freeze_animation_when_unfocused points at a page that already exists on main, so this PR is independently mergeable in any order.

Deferred findings (nothing dropped)

OpenAPI spec drift — route through the sync-openapi-spec skill, not hand-written docs. Three released endpoints are in warp-server's canonical spec without x-internal but missing from developers/agent-api-openapi.yaml:

• GET /agent/artifacts/{artifactUid}/download
• GET /agent/run-by-external-reference
• POST /agent/runs/{runId}/scores

The sync script's --mode diff reports no unclassified (!) items, but a regenerated subset would also add research-preview Agent Memory schemas (AgentMemoryCreateConfig, AgentMemoryResponse, AgentMemoryUpdateConfig, AgentAutoMemoryCreateConfig, AgentAutoMemoryResponse, MemoryStoreAttachmentResponse), plus modifications to 18 existing schemas. Publishing memory configuration while AIMemories is still research preview would contradict the skill's public/private guardrail, so this run stopped short of applying the sync. Recommended follow-up: decide whether those schemas should be excluded by the sync policy or marked x-internal in warp-server, then run sync-openapi-spec as its own PR. POST /agent/runs/{runId}/scores is also worth a second look — it exists for judge runs reporting Factory scorer verdicts, so it may warrant x-internal upstream.

Terminology/staleness (30 remaining findings). Every match was inspected in context and confirmed correct as written: telemetry event tables in privacy.mdx, the current "AI Command Search" feature name, agent-mode URL slugs and image filenames, the "AI credits" bucket name, and deliberate "Warp terminal" vs. Oz distinctions. Two genuine violations were fixed in #481. Broader wording enforcement remains with the style_lint skill.

Weak coverage (81 findings, --weak-coverage). Spot-checked and confirmed to be keyword-heuristic noise: for example GroupedTabs → terminal/windows/tabs.mdx (four "tab group" mentions), CloudRunners → platform/runners.mdx (37 "runner" mentions), NamedAgents → platform/agents.mdx (covers cloud agents throughout). No action taken.

Clean categories. No findings for feature flags, CLI commands, map hygiene, stale doc references, unlisted sidebar pages, or changelog review.

Validation

• audit_docs.py (coverage and --diff) exit 0, audits_skipped empty, unaccounted empty.
• After the changes, the slash-command, setting, and three internal API findings no longer appear; remaining API findings are the three spec-sync items above.
• npm run build passes; check_links.py reports 0 broken links.

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

[vercel]

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

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

[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 bookkeeping by classifying newly triaged surfaces in feature_surface_map.md and refreshing surface_snapshot.json for the 2026-08-05 drift-watch baseline.

Concerns

• No blocking general, security, or spec-alignment concerns found in the attached diff.

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