From 8f9972a28db86642c0dd568161339b378a671bb8 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 29 Jul 2026 17:10:25 +0000 Subject: [PATCH] docs-audit: surface map + snapshot bookkeeping (drift-watch) 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 --- .../references/feature_surface_map.md | 83 +++++++++++++++++-- .../references/surface_snapshot.json | 14 +++- 2 files changed, 87 insertions(+), 10 deletions(-) diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index 945b90d2..fe23dd7d 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -28,7 +28,7 @@ auto-surfaces for docs once the flag goes GA. AgentMode -> src/content/docs/agent-platform/local-agents/overview.mdx AgentManagementView -> src/content/docs/platform/managing-cloud-agents.md AgentManagementDetailsView -> src/content/docs/platform/managing-cloud-agents.md -AgentModeComputerUse -> src/content/docs/agent-platform/capabilities/computer-use.mdx +AgentModeComputerUse -> src/content/docs/agent-platform/capabilities/computer-use/index.mdx AgentModeWorkflows -> src/content/docs/knowledge-and-collaboration/warp-drive/workflows.md AgentOnboarding -> src/content/docs/agent-platform/getting-started/agents-in-warp.md AIRules -> src/content/docs/agent-platform/capabilities/rules.mdx @@ -58,7 +58,10 @@ CommandPaletteFileSearch -> src/content/docs/terminal/command-palette.md Ligatures -> src/content/docs/terminal/appearance/text-fonts-cursor.md UIZoom -> src/content/docs/terminal/appearance/size-opacity-blurring.md UsageBasedPricing -> src/content/docs/support-and-community/plans-and-billing/credits.md -APIKeyAuthentication -> src/content/docs/reference/cli/api-keys.md +# The APIKeyAuthentication flag was removed after the public API key auth feature +# stabilized (GA / flag cleanup). API key auth remains documented at +# reference/cli/api-keys.mdx via APIKeyManagement / TeamApiKeys, so no separate +# entry is needed. APIKeyManagement -> src/content/docs/reference/cli/api-keys.md CreatingSharedSessions -> src/content/docs/knowledge-and-collaboration/session-sharing/index.mdx AgentSharedSessions -> src/content/docs/agent-platform/local-agents/session-sharing.mdx @@ -149,9 +152,10 @@ SshRemoteServer -> src/content/docs/terminal/warpify/ssh.mdx # Computer use: session recording (VideoRecording gates the start/stop recording # tools) and window-targeted background capture (BackgroundComputerUse). Both are -# GA and documented on the computer use capability page. -VideoRecording -> src/content/docs/agent-platform/capabilities/computer-use.mdx -BackgroundComputerUse -> src/content/docs/agent-platform/capabilities/computer-use.mdx +# GA and documented on the computer use capability pages (the page was split from +# a flat computer-use.mdx into a computer-use/ directory). +VideoRecording -> src/content/docs/agent-platform/capabilities/computer-use/testing-and-recordings.mdx +BackgroundComputerUse -> src/content/docs/agent-platform/capabilities/computer-use/index.mdx # Feature flags whose only user-facing surface is a documented setting in the # all-settings reference (terminal/settings/all-settings.mdx). @@ -335,6 +339,46 @@ POST /harness-support/finish-task -> internal POST /harness-support/report-shutdown -> internal POST /harness-support/upload-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 +# @warp/factory front-end is internal/computer-use gated), so none of these +# endpoints are part of the released public Oz Agent API. They are marked +# 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 +POST /factory -> internal +POST /factory/avatar -> internal +GET /factory/{uid} -> internal +PATCH /factory/{uid} -> internal +DELETE /factory/{uid} -> internal +POST /factory/{uid}/apply -> internal +POST /factory/{uid}/plan -> internal +GET /factory/{uid}/source -> internal +PUT /factory/{uid}/source -> internal +DELETE /factory/{uid}/source -> internal +GET /factory/{uid}/syncs -> internal +GET /factory/{uid}/task-by-conversation -> internal +GET /factory/{uid}/tasks -> internal +POST /factory/{uid}/tasks -> internal +GET /factory/{uid}/tasks/{task_uid} -> internal +PATCH /factory/{uid}/tasks/{task_uid} -> internal +DELETE /factory/{uid}/tasks/{task_uid} -> 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/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 +DELETE /factory/automations/{id}/subscriptions/{subscription_id} -> internal +GET /factory/scorers -> internal +POST /factory/scorers -> internal +GET /factory/scorers/{scorer_id}/results -> internal + # Agent Memory REST API — research preview (gating flag AIMemories is non-GA), # deferred via `gated:` and auto-surfaces when AIMemories goes GA. See # "Public vs. private surfaces" in SKILL.md. @@ -370,9 +414,21 @@ GET /memory_stores/{uid}/memories/{memoryUid}/versions -> gated:AIMemories # 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 and version commands (Warp Agent CLI surface). +# TUI-only voice input command (Warp Agent CLI surface). The /version command was +# removed from code; its entry has been pruned. /voice -> internal -/version -> 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: +# - /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) +# - /add-api-key, /clear-provider-api-key: store/remove a model-provider API key +/status -> internal +/clear -> internal +/statusline -> internal +/add-api-key -> internal +/clear-provider-api-key -> 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 @@ -395,6 +451,13 @@ warpify.ssh.ssh_tmux_deprecation_notice_pending -> internal # documented in the all-settings reference. general.autoupdate_enabled -> internal +# 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 + # 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 @@ -530,6 +593,12 @@ GitCredentialRefresh # State-mutating recovery for abnormal terminal lifecycle sequences — an internal # reliability mechanism with no user-facing configuration or UI, so it needs no docs. TerminalLifecycleRecovery +# Internal persistence-backend detail: gates storing execution profiles in a +# file-backed settings collection (agents.execution_profiles) versus the legacy +# per-profile Warp Drive cloud objects. It changes where profiles are stored, not +# any user-facing behavior — execution profiles are documented via +# ProfilesDesignRevamp/MultiProfile -> agent-profiles-permissions.mdx — so it needs no docs. +FileBackedExecutionProfiles # Sub-feature toggles and pre-launch flags. Section placement does NOT assert # rollout status (the audit computes that from code); entries here are ignored diff --git a/.agents/skills/missing_docs/references/surface_snapshot.json b/.agents/skills/missing_docs/references/surface_snapshot.json index 9e38f7e3..0564a262 100644 --- a/.agents/skills/missing_docs/references/surface_snapshot.json +++ b/.agents/skills/missing_docs/references/surface_snapshot.json @@ -9,7 +9,6 @@ "AIMemories": "other", "AIResumeButton": "ga", "AIRules": "ga", - "APIKeyAuthentication": "ga", "APIKeyManagement": "ga", "AccountFirstOnboarding": "ga", "ActiveConversationRequiresInteraction": "ga", @@ -110,13 +109,14 @@ "EditableMarkdownMermaid": "dogfood", "EmbeddedCodeReviewComments": "other", "ExpandEditToPane": "ga", + "FactoryMcp": "dogfood", "FallbackModelLoadOutputMessaging": "ga", "FastForwardAutoexecuteButton": "ga", "FetchChannelVersionsFromWarpServer": "other", "FetchGenericStringObjects": "other", "FigmaDetection": "ga", "FileAndDiffSetComments": "dogfood", - "FileBackedExecutionProfiles": "dogfood", + "FileBackedExecutionProfiles": "ga", "FileBasedMcp": "ga", "FileGlobV2Warnings": "dogfood", "FileRetrievalTools": "ga", @@ -850,6 +850,8 @@ "GET /api/v1/factory/scorers", "GET /api/v1/factory/scorers/{scorer_id}/results", "GET /api/v1/factory/{uid}", + "GET /api/v1/factory/{uid}/integrations/linear/teams", + "GET /api/v1/factory/{uid}/integrations/linear/teams/{team_id}/labels", "GET /api/v1/factory/{uid}/source", "GET /api/v1/factory/{uid}/syncs", "GET /api/v1/factory/{uid}/task-by-conversation", @@ -909,17 +911,21 @@ "PUT /api/v1/agent/schedules/{id}", "PUT /api/v1/factory/automations/{id}", "PUT /api/v1/factory/automations/{id}/subscriptions", + "PUT /api/v1/factory/{uid}/integrations/linear/teams/{team_id}/labels", "PUT /api/v1/factory/{uid}/source", "PUT /api/v1/memory_stores/{uid}", "PUT /api/v1/memory_stores/{uid}/memories/{memoryUid}" ], "slash_commands": [ + "/add-api-key", "/add-mcp", "/add-prompt", "/add-rule", "/agent", "/auto-approve", "/changelog", + "/clear", + "/clear-provider-api-key", "/cloud-agent", "/compact", "/compact-and", @@ -964,9 +970,10 @@ "/rewind", "/set-tab-color", "/skills", + "/status", + "/statusline", "/theme", "/usage", - "/version", "/view-logs", "/voice" ], @@ -983,6 +990,7 @@ "agents.profiles.agent_mode_command_execution_allowlist": "always_on", "agents.profiles.agent_mode_command_execution_denylist": "always_on", "agents.profiles.agent_mode_execute_readonly_commands": "always_on", + "agents.statusline": "always_on", "agents.third_party.auto_dismiss_composer_after_submit": "always_on", "agents.third_party.auto_open_composer_on_cli_agent_start": "always_on", "agents.third_party.auto_toggle_composer": "always_on",