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

Merged
hongyi-chen merged 3 commits into from
Aug 12, 2026
Merged

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
9c55166
docs: refresh the missing_docs surface map and snapshot
hongyi-chen Aug 12, 2026
a9b5d8a
docs(skills): missing_docs audit bookkeeping (surface map + snapshot)
hongyi-chen Aug 12, 2026
8e8333c
Merge branch 'main' into docs/missing-docs-audit-bookkeeping
hongyi-chen Aug 12, 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
66 changes: 61 additions & 5 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 @@ -325,13 +325,30 @@ GET /.well-known/openid-configuration -> 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

# OAuth consent screen, connected-apps (grant) management, token revocation, and
# RFC 7591 dynamic client registration backing the MCP harness OAuth flows
# (router/handlers/public_api/oauth2.go; registration is additionally
# flag-gated). Like the device-flow endpoints above, these are protocol and web
# plumbing rather than a released public REST surface, and they are absent from
# warp-server's canonical public spec.
GET /oauth/consent/info -> internal
POST /oauth/consent -> internal
GET /oauth/grants -> internal
DELETE /oauth/grants/{client_id} -> internal
POST /oauth/register -> internal
POST /oauth/revoke -> internal

# Anonymous-viewer redirect probes (documented exceptions to auth, not API surfaces).
GET /agent/sessions/{session_uuid}/redirect -> internal
GET /agent/conversations/{conversation_id}/redirect -> internal
Expand Down Expand Up @@ -361,6 +378,7 @@ POST /harness-support/notify-user -> internal
POST /harness-support/finish-task -> internal
POST /harness-support/report-shutdown -> internal
POST /harness-support/upload-snapshot -> internal
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 @@ -403,10 +421,44 @@ PUT /factory/automations/{id}/subscriptions -> internal
DELETE /factory/automations/{id}/subscriptions/{subscription_id} -> internal
GET /factory/scorers -> internal
POST /factory/scorers -> internal
PATCH /factory/scorers/{scorer_id} -> internal
DELETE /factory/scorers/{scorer_id} -> internal
POST /factory/scorers/{scorer_id}/pause -> internal
POST /factory/scorers/{scorer_id}/resume -> internal
GET /factory/scorers/{scorer_id}/results -> internal
GET /factory/scorers/{scorer_id}/results/reasons -> 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
GET /factory/runs/{run_id}/scores -> internal
POST /factory/run-scoring/dispatches -> internal
POST /factory/autofix/runs/{autofix_run_id}/file-tasks -> internal
POST /factory/autofix/worker-results/{worker_result_id}/report -> internal
PUT /factory/automations/{id}/subscriptions/{subscription_id} -> internal
GET /factory/{uid}/integrations/github/branches -> internal
GET /factory/{uid}/integrations/github/labels -> internal
GET /factory/{uid}/integrations/github/teams -> internal
GET /factory/{uid}/integrations/github/users -> internal
GET /factory/{uid}/integrations/github/workflows -> 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
# Factory benchmark suites and benchmark runs
# (router/handlers/public_api/benchmarks.go). Same unreleased Factory product as
# the routes above, and absent from warp-server's canonical public spec.
GET /factory/{uid}/benchmarks/suites -> internal
POST /factory/{uid}/benchmarks/suites -> internal
GET /factory/{uid}/benchmarks/suites/{suite_uid} -> internal
PATCH /factory/{uid}/benchmarks/suites/{suite_uid} -> internal
DELETE /factory/{uid}/benchmarks/suites/{suite_uid} -> internal
POST /factory/{uid}/benchmarks/suites/{suite_uid}/runs -> internal
GET /factory/{uid}/benchmarks/runs -> internal
GET /factory/{uid}/benchmarks/runs/{run_uid} -> internal
GET /factory/{uid}/benchmarks/runs/{run_uid}/results -> internal
POST /factory/{uid}/benchmarks/runs/{run_uid}/cancel -> internal

# Orchestration messaging and lifecycle-event endpoints. These are marked
# `x-internal: true` in warp-server's canonical spec (public_api/openapi.yaml),
Expand Down Expand Up @@ -539,7 +591,7 @@ appearance.zero_state.show_animation -> internal
# while the terminal is unfocused (app/src/settings/tui_zero_state.rs). Like the
# other zero-state knobs it isn't in the GUI settings UI, so it's documented on
# the Warp Agent CLI configuration page instead of the all-settings reference.
appearance.zero_state.freeze_animation_when_unfocused -> src/content/docs/cli/configuration.mdx
appearance.zero_state.freeze_animation_when_unfocused -> src/content/docs/agents/cli/configuration.mdx

# Warp Agent CLI-only (crates/warp_tui) push-to-talk key for voice input (surface:
# SettingSurfaces::TUI in app/src/settings/tui_voice.rs). The GUI equivalent is the
Expand Down Expand Up @@ -618,6 +670,10 @@ 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. Its "Get started" button
# links to the CLI quickstart, and the CLI itself is documented under
# agents/cli/, so the modal has no separate documentable surface.
AgentCliLaunchModal
GetStartedTab
CreateProjectFlow
# Account-first onboarding is an internal login/onboarding flow variant with no
Expand Down
53 changes: 49 additions & 4 deletions .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 All @@ -202,9 +204,11 @@
"PRCommentsV2": "ga",
"PartialNextCommandSuggestions": "other",
"PendingUserQueryIndicator": "ga",
"PeriodicHandoffCheckpoints": "other",
"PinnedTabs": "ga",
"PluggableNotifications": "ga",
"PredictAMQueries": "other",
"PricingTransparency": "dogfood",
"ProfilesDesignRevamp": "ga",
"Projects": "dogfood",
"PromptCacheExpiryWarning": "dogfood",
Expand Down Expand Up @@ -264,7 +268,6 @@
"ToggleBootstrapBlock": "dogfood",
"TransferControlTool": "ga",
"TrimTrailingBlankLines": "ga",
"TuiCostTransparency": "dogfood",
"UIZoom": "ga",
"UndoClosedPanes": "ga",
"UsageBasedPricing": "ga",
Expand Down Expand Up @@ -814,15 +817,20 @@
"DELETE /api/v1/agent/schedules/{id}",
"DELETE /api/v1/factory/automations/{id}",
"DELETE /api/v1/factory/automations/{id}/subscriptions/{subscription_id}",
"DELETE /api/v1/factory/scorers/{scorer_id}",
"DELETE /api/v1/factory/scorers/{scorer_id}/autofix-config",
"DELETE /api/v1/factory/{uid}",
"DELETE /api/v1/factory/{uid}/benchmarks/suites/{suite_uid}",
"DELETE /api/v1/factory/{uid}/source",
"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 @@ -851,12 +859,30 @@
"GET /api/v1/factory/automations",
"GET /api/v1/factory/automations/events/{provider}",
"GET /api/v1/factory/automations/{id}",
"GET /api/v1/factory/runs/{run_id}/scores",
"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}/benchmarks/runs",
"GET /api/v1/factory/{uid}/benchmarks/runs/{run_uid}",
"GET /api/v1/factory/{uid}/benchmarks/runs/{run_uid}/results",
"GET /api/v1/factory/{uid}/benchmarks/suites",
"GET /api/v1/factory/{uid}/benchmarks/suites/{suite_uid}",
"GET /api/v1/factory/{uid}/integrations/github/branches",
"GET /api/v1/factory/{uid}/integrations/github/labels",
"GET /api/v1/factory/{uid}/integrations/github/teams",
"GET /api/v1/factory/{uid}/integrations/github/users",
"GET /api/v1/factory/{uid}/integrations/github/workflows",
"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,9 +897,13 @@
"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/scorers/{scorer_id}",
"PATCH /api/v1/factory/{uid}",
"PATCH /api/v1/factory/{uid}/benchmarks/suites/{suite_uid}",
"PATCH /api/v1/factory/{uid}/tasks/{task_uid}",
"POST /api/v1/agent/events/{run_id}",
"POST /api/v1/agent/handoff/upload-snapshot",
Expand All @@ -894,13 +924,22 @@
"POST /api/v1/agent/schedules/{id}/resume",
"POST /api/v1/agent/tasks/{id}/cancel",
"POST /api/v1/factory",
"POST /api/v1/factory/autofix/runs/{autofix_run_id}/file-tasks",
"POST /api/v1/factory/autofix/worker-results/{worker_result_id}/report",
"POST /api/v1/factory/automations",
"POST /api/v1/factory/avatar",
"POST /api/v1/factory/run-scoring/dispatches",
"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}/benchmarks/runs/{run_uid}/cancel",
"POST /api/v1/factory/{uid}/benchmarks/suites",
"POST /api/v1/factory/{uid}/benchmarks/suites/{suite_uid}/runs",
"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 +950,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 +979,7 @@
"/cloud-agent",
"/compact",
"/compact-and",
"/connect-grok",
"/continue-locally",
"/conversations",
"/copy-debugging-id",
Expand All @@ -957,6 +1001,7 @@
"/index",
"/init",
"/logout",
"/manage-billing",
"/mcp",
"/model",
"/natural-language-detection",
Expand All @@ -982,6 +1027,7 @@
"/status",
"/statusline",
"/theme",
"/upgrade",
"/usage",
"/view-logs",
"/vim-mode",
Expand Down Expand Up @@ -1225,8 +1271,6 @@
"artifacts/:artifactUid",
"design",
"environments",
"evaluations",
"evaluations/:evaluationId",
"integrations",
"login",
"login/callback",
Expand Down Expand Up @@ -1321,6 +1365,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 +1377,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