Skip to content

docs(skills): missing_docs audit bookkeeping (surface map + snapshot) #494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
hongyi-chen wants to merge 3 commits into
base: main
Choose a base branch
from
+146 −61
Draft

docs(skills): missing_docs audit bookkeeping (surface map + snapshot) #494

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
478815c
docs(skills): update missing_docs surface map and snapshot
hongyi-chen Aug 7, 2026
9fff9cf
Merge remote-tracking branch 'origin/main' into bookkeeping
hongyi-chen Aug 10, 2026
efcdb59
docs(skills): follow lowercase register* route helpers and map the ne…
hongyi-chen Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 106 additions & 57 deletions .agents/skills/missing_docs/references/feature_surface_map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,13 +323,40 @@ POST /oauth/token -> internal
GET /oauth/jwks.json -> internal
GET /.well-known/openid-configuration -> internal

# Consent endpoints backing the web consent screen for third-party OAuth clients
# (router/handlers/public_api/oauth2.go). GET /consent/info maps a client_id to
# the display name shown on the screen, and POST /consent records the grant that
# GET /oauth/authorize redirects to. They are browser-facing plumbing for the
# authorize flow above, absent from warp-server's canonical public spec, so they
# are not a documentable public API surface.
POST /oauth/consent -> internal
GET /oauth/consent/info -> internal

# The per-user grant list behind the consent screen: GET /grants lists the
# third-party clients a user has approved, and DELETE /grants/{client_id}
# revokes one. Same browser-facing plumbing as the consent endpoints above, and
# likewise absent from warp-server's canonical public spec.
GET /oauth/grants -> internal
DELETE /oauth/grants/{client_id} -> internal

# RFC 7591 dynamic client registration (registered only when the separate
# oauth_dcr flag is on) and RFC 7009 token revocation. Machine-facing OAuth
# protocol endpoints for third-party MCP clients, not part of the released
# public Oz Agent API.
POST /oauth/register -> internal
POST /oauth/revoke -> 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, registered only when the dogfood-only
# factory_mcp flag is on). They are machine-facing protocol metadata for an
# unreleased product, absent from warp-server's canonical public spec, so they
# are not a documentable public API surface.
# (router/handlers/public_api/oauth2.go, registered by registerMCPDiscoveryRoutes
# only when the dogfood-only factory_mcp flag is on). They are machine-facing
# protocol metadata for an unreleased product, absent from warp-server's
# canonical public spec, so they are not a documentable public API surface. The
# path-suffixed variants implement RFC 8414 section 5 path-aware discovery for
# the /api/v1/mcp/factory resource.
GET /.well-known/oauth-authorization-server -> internal
GET /.well-known/oauth-authorization-server/api/v1/mcp/factory -> internal
GET /.well-known/openid-configuration/api/v1/mcp/factory -> internal
GET /.well-known/oauth-protected-resource/api/v1/mcp/factory -> internal

# Anonymous-viewer redirect probes (documented exceptions to auth, not API surfaces).
Expand Down Expand Up @@ -361,6 +388,9 @@ POST /harness-support/notify-user -> internal
POST /harness-support/finish-task -> internal
POST /harness-support/report-shutdown -> internal
POST /harness-support/upload-snapshot -> internal
# Also marked `x-internal: true` in warp-server's canonical spec, so the publish
# filter strips it from the public docs copy.
POST /harness-support/commit-snapshot -> internal

# Oz Factory REST API (router/handlers/public_api/factory*.go). Factory is a
# private, not-yet-released product (the FactoryMcp flag is dogfood and the
Expand Down Expand Up @@ -393,17 +423,27 @@ GET /factory/{uid}/metrics -> internal
GET /factory/{uid}/integrations/linear/teams -> internal
GET /factory/{uid}/integrations/linear/teams/{team_id}/labels -> internal
PUT /factory/{uid}/integrations/linear/teams/{team_id}/labels -> internal
GET /factory/{uid}/integrations/linear/issues -> internal
GET /factory/{uid}/integrations/linear/projects -> internal
GET /factory/{uid}/integrations/linear/users -> internal
GET /factory/{uid}/integrations/linear/workflow-states -> internal
GET /factory/{uid}/integrations/slack/conversations -> internal
GET /factory/{uid}/integrations/slack/users -> internal
GET /factory/automations -> internal
POST /factory/automations -> internal
GET /factory/automations/events/{provider} -> internal
GET /factory/automations/{id} -> internal
PUT /factory/automations/{id} -> internal
DELETE /factory/automations/{id} -> internal
PUT /factory/automations/{id}/subscriptions -> internal
PUT /factory/automations/{id}/subscriptions/{subscription_id} -> internal
DELETE /factory/automations/{id}/subscriptions/{subscription_id} -> internal
GET /factory/scorers -> internal
POST /factory/scorers -> internal
GET /factory/scorers/{scorer_id}/results -> internal
GET /factory/scorers/{scorer_id}/results/reasons -> internal
POST /factory/scorers/{scorer_id}/pause -> internal
POST /factory/scorers/{scorer_id}/resume -> internal
GET /factory/scorers/{scorer_id}/autofix-config -> internal
PUT /factory/scorers/{scorer_id}/autofix-config -> internal
DELETE /factory/scorers/{scorer_id}/autofix-config -> internal
Expand Down Expand Up @@ -448,43 +488,44 @@ GET /memory_stores/{uid}/memories/{memoryUid}/versions -> gated:AIMemories
# slash-commands page content; add entries here only for exceptions.
# Gated by the dogfood-only LocalDockerSandbox flag — not user-facing yet.
/docker-sandbox -> internal
# Warp Agent CLI-only (crates/warp_tui) slash commands — added only when the
# settings mode is the Warp Agent CLI (see static_commands/commands.rs). They
# aren't present in the GUI desktop app, so they aren't documented on the public
# slash-commands page. Consistent with the general.autoupdate_enabled Warp Agent
# CLI-only setting mapped to `internal` above.
/exit -> internal
/view-logs -> internal
/auto-approve -> internal
/logout -> internal
# The paired /enable- and /disable-natural-language-detection commands were
# replaced by a single toggle, /natural-language-detection. Like the other Warp
# Agent CLI-only commands above, it isn't in the GUI, so it stays internal.
/natural-language-detection -> internal
# TUI-only voice input command (Warp Agent CLI surface). The /version command was
# removed from code; its entry has been pruned.
/voice -> internal
# More Warp Agent CLI-only (SlashCommandSurfaces::TuiOnly in static_commands/
# commands.rs) commands. None are present in the GUI desktop app, so they aren't
# documented on the public slash-commands page:
# Warp Agent CLI-only (SlashCommandSurfaces::TuiOnly in static_commands/
# commands.rs) slash commands — added only when the settings mode is the Warp
# Agent CLI. They aren't present in the GUI desktop app, so they aren't on the
# public slash-commands page; they are documented in the Warp Agent CLI slash
# command reference instead:
# - /exit: exit the CLI
# - /view-logs: bundle logs into a zip archive
# - /auto-approve: toggle auto-approve for agent actions
# - /logout: log out of Warp
# - /natural-language-detection: single toggle that replaced the removed
# /enable- and /disable-natural-language-detection pair
# - /voice: start voice input (the /version command was removed from code; its
# entry has been pruned)
# - /status: show session and account status
# - /clear: clear the transcript and start a new conversation
# - /statusline: configure the Warp Agent CLI statusline (agents.statusline, internal)
# - /reset-statusline: restore the statusline to its default items and ordering
# - /statusline and /reset-statusline: configure or reset the CLI statusline
# - /api-keys: view and manage model-provider API keys. It replaced the removed
# /add-api-key and /clear-provider-api-key pair, whose entries were pruned.
# - /vim-mode: toggle Vim keybindings in the Warp Agent CLI input
/status -> internal
/clear -> internal
/statusline -> internal
/reset-statusline -> internal
/api-keys -> internal
/vim-mode -> internal
# TUI-only color-theme picker (Warp Agent CLI surface, SlashCommandSurfaces::TuiOnly
# in static_commands/commands.rs). It sets the Warp Agent CLI theme
# (appearance.theme, mapped internal below) and isn't present in the GUI, so it
# stays internal like the other Warp Agent CLI-only commands.
/theme -> internal
# - /connect-grok: connect an X Premium or SuperGrok subscription
# - /manage-billing and /upgrade: open the team billing and upgrade pages
# - /vim-mode: toggle Vim keybindings in the CLI input
# - /theme: set the CLI color theme (appearance.theme, mapped below)
/exit -> src/content/docs/cli/reference.mdx
/view-logs -> src/content/docs/cli/reference.mdx
/auto-approve -> src/content/docs/cli/reference.mdx
/logout -> src/content/docs/cli/reference.mdx
/natural-language-detection -> src/content/docs/cli/reference.mdx
/voice -> src/content/docs/cli/reference.mdx
/status -> src/content/docs/cli/reference.mdx
/clear -> src/content/docs/cli/reference.mdx
/statusline -> src/content/docs/cli/reference.mdx
/reset-statusline -> src/content/docs/cli/reference.mdx
/api-keys -> src/content/docs/cli/reference.mdx
/connect-grok -> src/content/docs/cli/reference.mdx
/manage-billing -> src/content/docs/cli/reference.mdx
/upgrade -> src/content/docs/cli/reference.mdx
/vim-mode -> src/content/docs/cli/reference.mdx
/theme -> src/content/docs/cli/reference.mdx

## Settings -> doc pages

Expand All @@ -498,42 +539,45 @@ GET /memory_stores/{uid}/memories/{memoryUid}/versions -> gated:AIMemories
warpify.ssh.ssh_tmux_deprecation_notice_pending -> internal

# Warp Agent CLI-only (crates/warp_tui) background auto-updater toggle (surface:
# Warp Agent CLI). It isn't present in the GUI settings UI, so it isn't
# documented in the all-settings reference.
general.autoupdate_enabled -> internal
# Warp Agent CLI). It isn't present in the GUI settings UI, so instead of the
# all-settings reference it is documented with the CLI's update behavior.
general.autoupdate_enabled -> src/content/docs/cli/index.mdx

# Warp Agent CLI-only (crates/warp_tui) statusline configuration (surface:
# SettingSurfaces::TUI in app/src/settings/ai.rs; controls the order and
# visibility of the Warp Agent CLI bottom statusline items). It isn't present in
# the GUI settings UI, so it isn't documented in the all-settings reference.
# Paired with the /statusline Warp Agent CLI slash command mapped internal above.
agents.statusline -> internal
# the GUI settings UI, so it is documented on the CLI configuration page rather
# than the all-settings reference, alongside the /statusline and
# /reset-statusline slash commands.
agents.statusline -> src/content/docs/cli/configuration.mdx

# Warp Agent CLI-only (crates/warp_tui) color theme (surface: Warp Agent CLI,
# SettingSurfaces::TUI in tui_theme.rs; "auto|light|dark" matching the host
# terminal background). It isn't present in the GUI settings UI, so it isn't
# documented in the all-settings reference. The GUI theme setting is the separate
# appearance.themes.theme, which is documented. Paired with the /theme Warp Agent
# CLI slash command mapped internal above.
appearance.theme -> internal
# terminal background). It isn't present in the GUI settings UI, so it is
# documented on the CLI configuration page rather than the all-settings
# reference. The GUI theme setting is the separate appearance.themes.theme.
appearance.theme -> src/content/docs/cli/configuration.mdx

# Warp Agent CLI-only (crates/warp_tui) zero-state animation knobs (surface: Warp
# Agent CLI, SettingSurfaces::TUI). They tune the rotating object shown in the
# empty Warp Agent CLI state and aren't present in the GUI settings UI, so they
# aren't documented in the all-settings reference.
appearance.zero_state.object -> internal
appearance.zero_state.rotation_period_seconds -> internal
# are documented in the CLI configuration page's start screen section.
# extrusion_depth stays internal: it is a rendering detail of the built-in
# object with no documented user-facing behavior.
appearance.zero_state.object -> src/content/docs/cli/configuration.mdx
appearance.zero_state.rotation_period_seconds -> src/content/docs/cli/configuration.mdx
appearance.zero_state.extrusion_depth -> internal

# Warp Agent CLI-only (crates/warp_tui) per-section visibility toggles for the
# zero state (surface: SettingSurfaces::TUI in app/src/settings/tui_zero_state.rs).
# Each hides one section of the Warp Agent CLI empty state. They aren't present in
# the GUI settings UI, so they aren't documented in the all-settings reference.
appearance.zero_state.show_signed_in_user -> internal
appearance.zero_state.show_changelog -> internal
appearance.zero_state.show_project_info -> internal
appearance.zero_state.show_mcp -> internal
appearance.zero_state.show_animation -> internal
# the GUI settings UI, so they are documented in the CLI configuration page's
# start screen section.
appearance.zero_state.show_signed_in_user -> src/content/docs/cli/configuration.mdx
appearance.zero_state.show_changelog -> src/content/docs/cli/configuration.mdx
appearance.zero_state.show_project_info -> src/content/docs/cli/configuration.mdx
appearance.zero_state.show_mcp -> src/content/docs/cli/configuration.mdx
appearance.zero_state.show_animation -> src/content/docs/cli/configuration.mdx

# Warp Agent CLI-only toggle that stops the zero-state animation from repainting
# while the terminal is unfocused (app/src/settings/tui_zero_state.rs). Like the
Expand Down Expand Up @@ -618,6 +662,11 @@ OpenWarpLaunchModal
# One-time launch modal announcing multi-agent orchestration; the feature itself
# is documented via RunAgentsTool -> orchestration/multi-agent-runs.mdx.
OrchestrationLaunchModal
# One-time launch modal announcing the Warp Agent CLI (app/src/workspace/view/
# agent_cli_launch_modal/). It shows once, links out to the CLI's get-started
# page, and has no recurring user-facing surface of its own. The CLI it
# announces is documented at src/content/docs/cli/.
AgentCliLaunchModal
GetStartedTab
CreateProjectFlow
# Account-first onboarding is an internal login/onboarding flow variant with no
Expand Down
27 changes: 26 additions & 1 deletion .agents/skills/missing_docs/references/surface_snapshot.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
"APIKeyManagement": "ga",
"AccountFirstOnboarding": "ga",
"ActiveConversationRequiresInteraction": "ga",
"AgentCliLaunchModal": "ga",
"AgentDecidesCommandExecution": "ga",
"AgentHarness": "ga",
"AgentManagementDetailsView": "ga",
Expand Down Expand Up @@ -182,6 +183,7 @@
"McpOauth": "ga",
"McpServer": "ga",
"MinimalistUI": "ga",
"MultiLevelOrchestration": "dogfood",
"MultiProfile": "ga",
"MultiWorkspace": "dogfood",
"NamedAgents": "ga",
Expand Down Expand Up @@ -820,9 +822,12 @@
"DELETE /api/v1/factory/{uid}/tasks/{task_uid}",
"DELETE /api/v1/memory_stores/{uid}",
"DELETE /api/v1/memory_stores/{uid}/memories/{memoryUid}",
"DELETE /api/v1/oauth/grants/{client_id}",
"GET /.well-known/oauth-authorization-server",
"GET /.well-known/oauth-authorization-server/api/v1/mcp/factory",
"GET /.well-known/oauth-protected-resource/api/v1/mcp/factory",
"GET /.well-known/openid-configuration",
"GET /.well-known/openid-configuration/api/v1/mcp/factory",
"GET /api/v1/agent",
"GET /api/v1/agent/artifacts/{uid}",
"GET /api/v1/agent/artifacts/{uid}/download",
Expand Down Expand Up @@ -854,9 +859,16 @@
"GET /api/v1/factory/scorers",
"GET /api/v1/factory/scorers/{scorer_id}/autofix-config",
"GET /api/v1/factory/scorers/{scorer_id}/results",
"GET /api/v1/factory/scorers/{scorer_id}/results/reasons",
"GET /api/v1/factory/{uid}",
"GET /api/v1/factory/{uid}/integrations/linear/issues",
"GET /api/v1/factory/{uid}/integrations/linear/projects",
"GET /api/v1/factory/{uid}/integrations/linear/teams",
"GET /api/v1/factory/{uid}/integrations/linear/teams/{team_id}/labels",
"GET /api/v1/factory/{uid}/integrations/linear/users",
"GET /api/v1/factory/{uid}/integrations/linear/workflow-states",
"GET /api/v1/factory/{uid}/integrations/slack/conversations",
"GET /api/v1/factory/{uid}/integrations/slack/users",
"GET /api/v1/factory/{uid}/metrics",
"GET /api/v1/factory/{uid}/source",
"GET /api/v1/factory/{uid}/syncs",
Expand All @@ -871,6 +883,8 @@
"GET /api/v1/memory_stores/{uid}/memories/{memoryUid}",
"GET /api/v1/memory_stores/{uid}/memories/{memoryUid}/versions",
"GET /api/v1/oauth/authorize",
"GET /api/v1/oauth/consent/info",
"GET /api/v1/oauth/grants",
"GET /api/v1/oauth/jwks.json",
"PATCH /api/v1/agent/runs/{runId}/event-sequence",
"PATCH /api/v1/factory/{uid}",
Expand All @@ -897,10 +911,13 @@
"POST /api/v1/factory/automations",
"POST /api/v1/factory/avatar",
"POST /api/v1/factory/scorers",
"POST /api/v1/factory/scorers/{scorer_id}/pause",
"POST /api/v1/factory/scorers/{scorer_id}/resume",
"POST /api/v1/factory/{uid}/apply",
"POST /api/v1/factory/{uid}/plan",
"POST /api/v1/factory/{uid}/tasks",
"POST /api/v1/harness-support/block-snapshot",
"POST /api/v1/harness-support/commit-snapshot",
"POST /api/v1/harness-support/external-conversation",
"POST /api/v1/harness-support/finish-task",
"POST /api/v1/harness-support/notify-user",
Expand All @@ -911,13 +928,17 @@
"POST /api/v1/harness-support/upload-snapshot",
"POST /api/v1/memory_stores",
"POST /api/v1/memory_stores/{uid}/memories",
"POST /api/v1/oauth/consent",
"POST /api/v1/oauth/device/auth",
"POST /api/v1/oauth/register",
"POST /api/v1/oauth/revoke",
"POST /api/v1/oauth/session",
"POST /api/v1/oauth/token",
"PUT /api/v1/agent/identities/{uid}",
"PUT /api/v1/agent/schedules/{id}",
"PUT /api/v1/factory/automations/{id}",
"PUT /api/v1/factory/automations/{id}/subscriptions",
"PUT /api/v1/factory/automations/{id}/subscriptions/{subscription_id}",
"PUT /api/v1/factory/scorers/{scorer_id}/autofix-config",
"PUT /api/v1/factory/{uid}/integrations/linear/teams/{team_id}/labels",
"PUT /api/v1/factory/{uid}/source",
Expand All @@ -936,6 +957,7 @@
"/cloud-agent",
"/compact",
"/compact-and",
"/connect-grok",
"/continue-locally",
"/conversations",
"/copy-debugging-id",
Expand All @@ -957,6 +979,7 @@
"/index",
"/init",
"/logout",
"/manage-billing",
"/mcp",
"/model",
"/natural-language-detection",
Expand All @@ -982,6 +1005,7 @@
"/status",
"/statusline",
"/theme",
"/upgrade",
"/usage",
"/view-logs",
"/vim-mode",
Expand Down Expand Up @@ -1321,6 +1345,7 @@
"claude-api": "bundled",
"create-skill": "bundled",
"create-tab-config": "bundled",
"factory-mcp": "bundled",
"modify-settings": "bundled",
"oz-platform": "bundled",
"pr-comments": "bundled",
Expand All @@ -1332,5 +1357,5 @@
"verify-ui-change-in-cloud": "dogfood",
"warpctrl": "bundled"
},
"changelog_last_version": "2026.07.31"
"changelog_last_version": "2026.08.07"
}
17 changes: 14 additions & 3 deletions .agents/skills/missing_docs/scripts/audit_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -745,9 +745,20 @@ def _split_top_level_args(s: str) -> list[str]:
return args


def _is_route_registrar(name: str) -> bool:
"""Whether a Go function name looks like a route-registration helper.

Matches both the exported `RegisterFooRoutes` entry points and unexported
helpers like `registerMCPDiscoveryRoutes`, which real handlers use to split
a large registration function up. Missing the unexported ones silently
dropped their routes from the audit universe.
"""
return name.startswith(("Register", "register"))


def _iter_register_calls(body: str):
"""Yield (callee, start_pos, args) for Register*(...) calls, paren-matched."""
for match in re.finditer(r"\b(Register\w+)\(", body):
"""Yield (callee, start_pos, args) for [Rr]egister*(...) calls, paren-matched."""
for match in re.finditer(r"\b([Rr]egister\w+)\(", body):
start = match.end()
depth = 1
i = start
Expand Down Expand Up @@ -911,7 +922,7 @@ def emit(fn_name: str, param_prefix: str):
# to hang off the /api/v1 group (conservative default so routes are never
# silently dropped).
for fn_name in sorted(analyzed):
if fn_name.startswith("Register") and fn_name not in emitted_fns:
if _is_route_registrar(fn_name) and fn_name not in emitted_fns:
emit(fn_name, "/api/v1")

routes = []
Expand Down
Loading