docs-audit: surface map + snapshot bookkeeping (drift-watch) - #418
Conversation
Resolve missing_docs drift-watch findings that need only surface-map bookkeeping (no new public doc pages were warranted this run): - Slash commands /add-api-key, /clear, /clear-provider-api-key, /statusline, /status: all SlashCommandSurfaces::TuiOnly (Warp Agent CLI, not in the GUI) -> mapped internal, consistent with the other TUI-only commands. Pruned the removed /version entry. - Setting agents.statusline: SettingSurfaces::TUI (Warp Agent CLI only) -> mapped internal, like general.autoupdate_enabled / appearance.theme. - FileBackedExecutionProfiles (dogfood -> ga): internal persistence backend for execution profiles with no distinct user-facing surface (profiles are documented via agent-profiles-permissions) -> ignore list. - Computer-use map paths: AgentModeComputerUse / BackgroundComputerUse / VideoRecording pointed at a flat computer-use.mdx that was split into a computer-use/ directory -> updated to the current pages. - APIKeyAuthentication flag removed (GA/flag cleanup) -> pruned; API key auth stays documented via APIKeyManagement/TeamApiKeys. - Oz Factory REST API (32 routes): Factory is a private, not-yet-released product (FactoryMcp is dogfood) -> mapped internal until it ships. Refreshed surface_snapshot.json so the next run diffs against this baseline. Deferred (not addressed here, called out for follow-up): - 15 public_api /agent/* routes (messaging, schedules, artifacts, events, webhooks) missing from the OpenAPI spec -> route through sync-openapi-spec (never hand-document private warp-server endpoints). - 32 low-severity terminology findings -> owned by the style_lint skill. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
not sure why this used @guyscherzer8's profile, but approving and merging |
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates the missing_docs drift-watch surface map and refreshed snapshot bookkeeping for internal/TUI-only surfaces, moved computer-use docs paths, removed flags, and newly detected Factory API routes. I found one material bookkeeping issue in the new Factory API mapping.
Concerns
- The Factory routes are tied to the non-GA
FactoryMcpflag in the refreshed snapshot, but the map marks them as permanentlyinternal; this bypasses the existinggated:<Flag>mechanism that would re-surface the API docs/spec decision when the flag promotes.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| # internal until Factory ships publicly; revisit and route through the | ||
| # sync-openapi-spec skill if/when Factory goes GA. See SKILL.md "Public vs. | ||
| # private surfaces". | ||
| GET /factory -> internal |
There was a problem hiding this comment.
FactoryMcp is dogfood in the refreshed snapshot, mapping these routes to internal permanently suppresses them even if the flag promotes; use gated:FactoryMcp for the Factory API routes unless there is a separate permanent-internal signal.
2 participants
Summary
Drift-watch run of the
missing_docsskill. This is the companion audit-bookkeeping PR: it only touches the skill's reference files (feature_surface_map.md,surface_snapshot.json). No new public doc pages were warranted this run — every actionable finding resolved to a surface-map mapping, path fix, prune, or ignore entry.Both audit modes exited 0 (no environment problems, no skipped audits,
unaccountedempty). Re-running coverage after these edits drops the addressed categories to 0.Findings addressed
/add-api-key,/clear,/clear-provider-api-key,/statusline,/status: allSlashCommandSurfaces::TuiOnly(Warp Agent CLI only, not in the GUI desktop app) → mappedinternal, matching the existing TUI-only convention. Pruned the removed/versionentry.agents.statusline:SettingSurfaces::TUI(Warp Agent CLI only) → mappedinternal, likegeneral.autoupdate_enabledandappearance.theme.FileBackedExecutionProfiles(dogfood → GA): internal persistence backend for execution profiles with no distinct user-facing surface (profiles are documented viaagent-profiles-permissions.mdx) → ignore list.AgentModeComputerUse,BackgroundComputerUse,VideoRecordingpointed at a flatcomputer-use.mdxthat was split into acomputer-use/directory → updated to the current pages.APIKeyAuthentication(GA / flag cleanup) → pruned; API key auth stays documented viaAPIKeyManagement/TeamApiKeys.FactoryMcpis dogfood; the@warp/factoryfront-end is internal) → mappedinternaluntil it ships publicly.surface_snapshot.jsonwas regenerated so the next drift-watch run diffs against this baseline.Deferred (not silently dropped)
/agent/*API routes missing from the OpenAPI spec —agent_messaging.go(6),agent_schedules.go(5),agent_artifacts.go(2),agent_events_stream_dispatch.go(1),agent_webhooks.go(1). warp-server is private, so these are not hand-documented. Released ones should be brought in via thesync-openapi-specskill as a separate change; the rest deferred pending release confirmation.style_lintskill per themissing_docsskill's guidance; not addressed here.Reviewers
Resolved from warp/warp-server ownership files via
suggest_reviewers.py:@moirahuang— slash commands (static_commands/commands.rs)@warpdotdev/oss-maintainers—agents.statuslinesetting and execution profilesUnresolved (manual assignment): warp-server
router/handlers/public_api/{factories,factory_automations,agent_schedules,agent_messaging}.gohad no owner match.Conversation: https://staging.warp.dev/conversation/822ffc66-c123-4f33-a169-b61d8d524b9a
Run: https://oz.staging.warp.dev/runs/019faed1-af8f-76f4-96bf-c445ac83a80a
This PR was generated with Oz.