diff --git a/.agents/skills/missing_docs/SKILL.md b/.agents/skills/missing_docs/SKILL.md index 7d45795..5d38bf5 100644 --- a/.agents/skills/missing_docs/SKILL.md +++ b/.agents/skills/missing_docs/SKILL.md @@ -21,18 +21,23 @@ Find documentation gaps and draft missing pages in one workflow. Run the audit script to identify gaps: ```bash -python3 .warp/skills/missing_docs/scripts/audit_docs.py +python3 .agents/skills/missing_docs/scripts/audit_docs.py ``` Options: - `--category features|cli|api|staleness` — run a single audit category - `--severity high|medium|low` — filter by minimum severity +- `--weak-coverage` — also flag GA features whose mapped doc exists but doesn't mention feature keywords (low-severity, noisy) - `--output report.json` — save JSON report to file - `--warp-internal PATH` — explicit path to warp-internal (auto-detected from sibling dirs) - `--warp-server PATH` — explicit path to warp-server (auto-detected from sibling dirs) +The script resolves doc paths from the docs repo root and accepts `.md` and `.mdx` +interchangeably (and `README.md` ↔ `index.mdx`), so surface-map entries can use the +canonical filename even when the on-disk extension differs. + The script performs 4 audits: -1. **Feature flag coverage** — compares GA flags in `warp_core/src/features.rs` + `app/Cargo.toml` against doc mentions +1. **Feature flag coverage** — compares GA flags in `crates/warp_features/src/lib.rs` + `app/Cargo.toml` against the surface map; default mode trusts a mapped entry as verified, `--weak-coverage` additionally checks the target page mentions feature keywords 2. **CLI command coverage** — compares `warp_cli/src/lib.rs` subcommands against `src/content/docs/reference/cli/` 3. **API endpoint coverage** — compares `router/router.go` routes against `src/content/docs/reference/api-and-sdk/` and the OpenAPI spec 4. **Docs staleness** — checks for outdated terminology in existing docs diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index 70019d6..f95b81d 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -6,155 +6,181 @@ The audit script reads this file to reduce false positives — entries here are Format: `CodeIdentifier -> docs/path/to/page.md` (one per line within each section). Lines starting with `#` are comments. Blank lines are ignored. +The audit script accepts `.md` and `.mdx` interchangeably and resolves `README.md` to `index.mdx`, +so prefer the canonical filename here even if the on-disk extension is `.mdx`. + # Maintenance: when a new GA feature flag ships, add a mapping here. -# Run `python3 .warp/skills/missing_docs/scripts/audit_docs.py` to find unmapped flags. +# Run `python3 .agents/skills/missing_docs/scripts/audit_docs.py` to find unmapped flags. # This audit is also run as a recurring scheduled Oz agent to catch drift. ## Feature flags -> doc pages -AgentMode -> src/content/docs/agent-platform/warp-agents/README.md -AgentManagementView -> src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.md -AgentManagementDetailsView -> src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.md -AgentModeComputerUse -> src/content/docs/agent-platform/warp-agents/computer-use.md -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/warp-agents/rules.md -AIResumeButton -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/terminal-and-agent-modes.md -CodeReviewView -> src/content/docs/code/code-review.md -InlineCodeReview -> src/content/docs/agent-platform/warp-agents/interactive-code-review.md -FileTree -> src/content/docs/code/code-editor/file-tree.md -CodeFindReplace -> src/content/docs/code/code-editor/find-and-replace.md -VimCodeEditor -> src/content/docs/code/code-editor/code-editor-vim-keybindings.md -McpServer -> src/content/docs/agent-platform/warp-agents/mcp.md -McpOauth -> src/content/docs/agent-platform/warp-agents/mcp.md -ImageAsContext -> src/content/docs/agent-platform/warp-agents/agent-context/images-as-context.md -SelectionAsContext -> src/content/docs/agent-platform/warp-agents/agent-context/selection-as-context.md -DiffSetAsContext -> src/content/docs/agent-platform/warp-agents/agent-context/selection-as-context.md -WebSearchUI -> src/content/docs/agent-platform/warp-agents/web-search.md -WebFetchUI -> src/content/docs/agent-platform/warp-agents/web-search.md -CodebaseContext -> src/content/docs/agent-platform/warp-agents/codebase-context.md -CrossRepoContext -> src/content/docs/agent-platform/warp-agents/codebase-context.md -FullSourceCodeEmbedding -> src/content/docs/agent-platform/warp-agents/codebase-context.md -SearchCodebaseUI -> src/content/docs/agent-platform/warp-agents/codebase-context.md -CloudEnvironments -> src/content/docs/agent-platform/cloud-agents/environments.md -CloudMode -> src/content/docs/agent-platform/cloud-agents/overview.md -AmbientAgentsCommandLine -> src/content/docs/agent-platform/cloud-agents/overview.md -ScheduledAmbientAgents -> src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.md -WarpManagedSecrets -> src/content/docs/agent-platform/cloud-agents/secrets.md -IntegrationCommand -> src/content/docs/reference/cli/integration-setup.md -ConversationManagement -> src/content/docs/agent-platform/warp-agents/cloud-conversations.md -ForkConversationFromBlock -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/conversation-forking.md -Voice -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/voice.md -WarpDrive -> src/content/docs/knowledge-and-collaboration/warp-drive/README.md -EnvVars -> src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.md -CommandPaletteFileSearch -> src/content/docs/terminal/command-palette.md -Themes -> src/content/docs/terminal/appearance/themes.md -Ligatures -> src/content/docs/terminal/appearance/text-fonts-cursor.md -UIZoom -> src/content/docs/terminal/appearance/size-opacity-blurring.md -SSH -> src/content/docs/terminal/warpify/ssh.md -SplitPanes -> src/content/docs/terminal/windows/split-panes.md -Tabs -> src/content/docs/terminal/windows/tabs.md -GlobalHotkey -> src/content/docs/terminal/windows/global-hotkey.md -LaunchConfigurations -> src/content/docs/terminal/sessions/launch-configurations.md -SessionRestoration -> src/content/docs/terminal/sessions/session-restoration.md -BlockBasics -> src/content/docs/terminal/blocks/block-basics.md -Autosuggestions -> src/content/docs/terminal/command-completions/autosuggestions.md -Completions -> src/content/docs/terminal/command-completions/completions.md -CommandHistory -> src/content/docs/terminal/entry/command-history.md -CommandCorrections -> src/content/docs/terminal/entry/command-corrections.md -UsageBasedPricing -> src/content/docs/support-and-community/plans-and-billing/credits.md -APIKeyAuthentication -> src/content/docs/reference/cli/api-keys.md -APIKeyManagement -> src/content/docs/reference/cli/api-keys.md -SecretRedaction -> src/content/docs/support-and-community/privacy-and-security/secret-redaction.md -CreatingSharedSessions -> src/content/docs/knowledge-and-collaboration/session-sharing/README.md -AgentSharedSessions -> src/content/docs/agent-platform/warp-agents/session-sharing.md -ProfilesDesignRevamp -> src/content/docs/agent-platform/warp-agents/agent-profiles-permissions.md -MultiProfile -> src/content/docs/agent-platform/warp-agents/agent-profiles-permissions.md -InlineProfileSelector -> src/content/docs/agent-platform/warp-agents/agent-profiles-permissions.md -ModelChoice -> src/content/docs/agent-platform/warp-agents/model-choice.md -Skills -> src/content/docs/agent-platform/warp-agents/skills.md -ListSkills -> src/content/docs/agent-platform/warp-agents/skills.md -BundledSkills -> src/content/docs/agent-platform/warp-agents/skills.md -Planning -> src/content/docs/agent-platform/warp-agents/planning.md -SyncAmbientPlans -> src/content/docs/agent-platform/warp-agents/planning.md -TaskLists -> src/content/docs/agent-platform/warp-agents/task-lists.md -SlashCommands -> src/content/docs/agent-platform/warp-agents/slash-commands.md -SuggestedRules -> src/content/docs/agent-platform/warp-agents/rules.md -RectSelection -> src/content/docs/terminal/more-features/text-selection.md -ContextWindowUsageV2 -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/README.md -ConfigurableBlockLimits -> src/content/docs/terminal/blocks/block-basics.md -CommandCorrectionKey -> src/content/docs/terminal/entry/command-corrections.md -ClassicCompletions -> src/content/docs/terminal/command-completions/completions.md -DynamicWorkflowEnums -> src/content/docs/knowledge-and-collaboration/warp-drive/workflows.md -SharedWithMe -> src/content/docs/knowledge-and-collaboration/warp-drive/README.md -WarpPacks -> src/content/docs/knowledge-and-collaboration/warp-drive/README.md -TabbedEditorView -> src/content/docs/code/code-editor/README.md -ReadImageFiles -> src/content/docs/agent-platform/warp-agents/agent-context/images-as-context.md -FileRetrievalTools -> src/content/docs/agent-platform/warp-agents/codebase-context.md -ConversationArtifacts -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/README.md -OzChangelogUpdates -> src/content/docs/changelog/README.md -ActiveConversationRequiresInteraction -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/README.md +# Agent Mode and core agent surfaces +AgentMode -> src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +AgentManagementView -> src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +AgentManagementDetailsView -> src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +AgentModeComputerUse -> src/content/docs/agent-platform/capabilities/computer-use.mdx +AgentModeWorkflows -> src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx +AgentOnboarding -> src/content/docs/agent-platform/getting-started/agents-in-warp.mdx +AIRules -> src/content/docs/agent-platform/capabilities/rules.mdx +SuggestedRules -> src/content/docs/agent-platform/capabilities/rules.mdx +AIResumeButton -> src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +AgentView -> src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +InlineHistoryMenu -> src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +AskUserQuestion -> src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +ContextWindowUsageV2 -> src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +ConversationArtifacts -> src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +ActiveConversationRequiresInteraction -> src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx +PRCommentsV2 -> src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx + +# Code review surfaces +CodeReviewView -> src/content/docs/code/code-review.mdx +CodeReviewFind -> src/content/docs/code/code-review.mdx +CodeReviewSaveChanges -> src/content/docs/code/code-review.mdx +DiscardPerFileAndAllChanges -> src/content/docs/code/code-review.mdx +AutoOpenCodeReviewPane -> src/content/docs/code/code-review.mdx +GitOperationsInCodeReview -> src/content/docs/code/code-review.mdx +InlineCodeReview -> src/content/docs/agent-platform/local-agents/interactive-code-review.mdx + +# Code editor surfaces +TabbedEditorView -> src/content/docs/code/code-editor/index.mdx +FileTree -> src/content/docs/code/code-editor/file-tree.mdx +CodeFindReplace -> src/content/docs/code/code-editor/find-and-replace.mdx +VimCodeEditor -> src/content/docs/code/code-editor/code-editor-vim-keybindings.mdx +GlobalSearch -> src/content/docs/code/overview.mdx + +# MCP / tools / context +McpServer -> src/content/docs/agent-platform/capabilities/mcp.mdx +McpOauth -> src/content/docs/agent-platform/capabilities/mcp.mdx +FileBasedMcp -> src/content/docs/agent-platform/capabilities/mcp.mdx +ImageAsContext -> src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx +ReadImageFiles -> src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx +SelectionAsContext -> src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx +DiffSetAsContext -> src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx +ConversationsAsContext -> src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx +AgentViewBlockContext -> src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx +AIContextMenuEnabled -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx +AtMenuOutsideOfAIMode -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx +AIContextMenuCode -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx +DriveObjectsAsContext -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx +WebSearchUI -> src/content/docs/agent-platform/capabilities/web-search.mdx +WebFetchUI -> src/content/docs/agent-platform/capabilities/web-search.mdx +CodebaseContext -> src/content/docs/agent-platform/capabilities/codebase-context.mdx +CrossRepoContext -> src/content/docs/agent-platform/capabilities/codebase-context.mdx +FullSourceCodeEmbedding -> src/content/docs/agent-platform/capabilities/codebase-context.mdx +SearchCodebaseUI -> src/content/docs/agent-platform/capabilities/codebase-context.mdx +FileRetrievalTools -> src/content/docs/agent-platform/capabilities/codebase-context.mdx +InlineRepoMenu -> src/content/docs/agent-platform/capabilities/codebase-context.mdx + +# Cloud agents +CloudEnvironments -> src/content/docs/agent-platform/cloud-agents/environments.mdx +CloudMode -> src/content/docs/agent-platform/cloud-agents/overview.mdx +AmbientAgentsCommandLine -> src/content/docs/agent-platform/cloud-agents/overview.mdx +CloudModeFromLocalSession -> src/content/docs/agent-platform/cloud-agents/overview.mdx +ScheduledAmbientAgents -> src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx +WarpManagedSecrets -> src/content/docs/agent-platform/cloud-agents/secrets.mdx + +# CLI / API integration +IntegrationCommand -> src/content/docs/reference/cli/integration-setup.mdx +APIKeyAuthentication -> src/content/docs/reference/cli/api-keys.mdx +APIKeyManagement -> src/content/docs/reference/cli/api-keys.mdx +TeamApiKeys -> src/content/docs/reference/cli/api-keys.mdx + +# Conversations / forking / voice +ConversationManagement -> src/content/docs/agent-platform/local-agents/cloud-conversations.mdx +CloudConversations -> src/content/docs/agent-platform/local-agents/cloud-conversations.mdx +ForkConversationFromBlock -> src/content/docs/agent-platform/local-agents/interacting-with-agents/conversation-forking.mdx +Voice -> src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx -# Recently shipped GA features -VerticalTabs -> src/content/docs/terminal/windows/vertical-tabs.md -TabConfigs -> src/content/docs/terminal/windows/tab-configs.md -PluggableNotifications -> src/content/docs/terminal/more-features/notifications.md -RevertToCheckpoints -> src/content/docs/agent-platform/warp-agents/slash-commands.md -RewindSlashCommand -> src/content/docs/agent-platform/warp-agents/slash-commands.md -ForkFromCommand -> src/content/docs/agent-platform/warp-agents/slash-commands.md -SummarizationConversationCommand -> src/content/docs/agent-platform/warp-agents/slash-commands.md -CodeReviewFind -> src/content/docs/code/code-review.md -CodeReviewSaveChanges -> src/content/docs/code/code-review.md -DiscardPerFileAndAllChanges -> src/content/docs/code/code-review.md -AutoOpenCodeReviewPane -> src/content/docs/code/code-review.md -GitOperationsInCodeReview -> src/content/docs/code/code-review.md -AgentView -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/terminal-and-agent-modes.md -AgentViewBlockContext -> src/content/docs/agent-platform/warp-agents/agent-context/blocks-as-context.md -CloudConversations -> src/content/docs/agent-platform/warp-agents/cloud-conversations.md -CloudModeFromLocalSession -> src/content/docs/agent-platform/cloud-agents/overview.md -TeamApiKeys -> src/content/docs/reference/cli/api-keys.md -PRCommentsSlashCommand -> src/content/docs/agent-platform/warp-agents/slash-commands.md -PRCommentsV2 -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/README.md -CLIAgentRichInput -> src/content/docs/agent-platform/cli-agents/rich-input.md -HOANotifications -> src/content/docs/agent-platform/warp-agents/agent-notifications.md -OpenCodeNotifications -> src/content/docs/agent-platform/cli-agents/opencode.md -CodexNotifications -> src/content/docs/agent-platform/cli-agents/codex.md -HOARemoteControl -> src/content/docs/agent-platform/cli-agents/remote-control.md -GlobalSearch -> src/content/docs/code/overview.md -FileBasedMcp -> src/content/docs/agent-platform/warp-agents/mcp.md -ConversationsAsContext -> src/content/docs/agent-platform/warp-agents/agent-context/blocks-as-context.md -GithubPrPromptChip -> src/content/docs/agent-platform/warp-agents/agent-notifications.md -AskUserQuestion -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/README.md -AIContextMenuEnabled -> src/content/docs/agent-platform/warp-agents/agent-context/using-to-add-context.md -AtMenuOutsideOfAIMode -> src/content/docs/agent-platform/warp-agents/agent-context/using-to-add-context.md -AIContextMenuCode -> src/content/docs/agent-platform/warp-agents/agent-context/using-to-add-context.md -DriveObjectsAsContext -> src/content/docs/agent-platform/warp-agents/agent-context/using-to-add-context.md -KittyKeyboardProtocol -> src/content/docs/terminal/more-features/full-screen-apps.md -InlineRepoMenu -> src/content/docs/agent-platform/warp-agents/codebase-context.md -InlineHistoryMenu -> src/content/docs/agent-platform/warp-agents/interacting-with-agents/terminal-and-agent-modes.md -SkillArguments -> src/content/docs/agent-platform/warp-agents/skills.md +# Drive +WarpDrive -> src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx +SharedWithMe -> src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx +WarpPacks -> src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx +EnvVars -> src/content/docs/knowledge-and-collaboration/warp-drive/environment-variables.mdx +DynamicWorkflowEnums -> src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx + +# Terminal appearance and behavior +CommandPaletteFileSearch -> src/content/docs/terminal/command-palette.mdx +Themes -> src/content/docs/terminal/appearance/themes.mdx +Ligatures -> src/content/docs/terminal/appearance/text-fonts-cursor.mdx +UIZoom -> src/content/docs/terminal/appearance/size-opacity-blurring.mdx +SSH -> src/content/docs/terminal/warpify/ssh.mdx +SplitPanes -> src/content/docs/terminal/windows/split-panes.mdx +Tabs -> src/content/docs/terminal/windows/tabs.mdx +VerticalTabs -> src/content/docs/terminal/windows/vertical-tabs.mdx +TabConfigs -> src/content/docs/terminal/windows/tab-configs.mdx +GlobalHotkey -> src/content/docs/terminal/windows/global-hotkey.mdx +LaunchConfigurations -> src/content/docs/terminal/sessions/launch-configurations.mdx +SessionRestoration -> src/content/docs/terminal/sessions/session-restoration.mdx +BlockBasics -> src/content/docs/terminal/blocks/block-basics.mdx +ConfigurableBlockLimits -> src/content/docs/terminal/blocks/block-basics.mdx +Autosuggestions -> src/content/docs/terminal/command-completions/autosuggestions.mdx +Completions -> src/content/docs/terminal/command-completions/completions.mdx +ClassicCompletions -> src/content/docs/terminal/command-completions/completions.mdx +CommandHistory -> src/content/docs/terminal/entry/command-history.mdx +CommandCorrections -> src/content/docs/terminal/entry/command-corrections.mdx +CommandCorrectionKey -> src/content/docs/terminal/entry/command-corrections.mdx +RectSelection -> src/content/docs/terminal/more-features/text-selection.mdx +PluggableNotifications -> src/content/docs/terminal/more-features/notifications.mdx +KittyKeyboardProtocol -> src/content/docs/terminal/more-features/full-screen-apps.mdx + +# Sharing and permissions +CreatingSharedSessions -> src/content/docs/knowledge-and-collaboration/session-sharing/index.mdx +AgentSharedSessions -> src/content/docs/agent-platform/local-agents/session-sharing.mdx +SecretRedaction -> src/content/docs/support-and-community/privacy-and-security/secret-redaction.mdx +ProfilesDesignRevamp -> src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx +MultiProfile -> src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx +InlineProfileSelector -> src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx + +# Models, planning, skills, slash commands, notifications +ModelChoice -> src/content/docs/agent-platform/capabilities/model-choice.mdx +Skills -> src/content/docs/agent-platform/capabilities/skills.mdx +ListSkills -> src/content/docs/agent-platform/capabilities/skills.mdx +BundledSkills -> src/content/docs/agent-platform/capabilities/skills.mdx +SkillArguments -> src/content/docs/agent-platform/capabilities/skills.mdx +Planning -> src/content/docs/agent-platform/capabilities/planning.mdx +SyncAmbientPlans -> src/content/docs/agent-platform/capabilities/planning.mdx +TaskLists -> src/content/docs/agent-platform/capabilities/task-lists.mdx +SlashCommands -> src/content/docs/agent-platform/capabilities/slash-commands.mdx +RevertToCheckpoints -> src/content/docs/agent-platform/capabilities/slash-commands.mdx +RewindSlashCommand -> src/content/docs/agent-platform/capabilities/slash-commands.mdx +ForkFromCommand -> src/content/docs/agent-platform/capabilities/slash-commands.mdx +SummarizationConversationCommand -> src/content/docs/agent-platform/capabilities/slash-commands.mdx +PRCommentsSlashCommand -> src/content/docs/agent-platform/capabilities/slash-commands.mdx +HOANotifications -> src/content/docs/agent-platform/capabilities/agent-notifications.mdx +GithubPrPromptChip -> src/content/docs/agent-platform/capabilities/agent-notifications.mdx + +# Pricing and changelog +UsageBasedPricing -> src/content/docs/support-and-community/plans-and-billing/credits.mdx +OzChangelogUpdates -> src/content/docs/changelog/index.mdx + +# CLI agents +CLIAgentRichInput -> src/content/docs/agent-platform/cli-agents/rich-input.mdx +OpenCodeNotifications -> src/content/docs/agent-platform/cli-agents/opencode.mdx +CodexNotifications -> src/content/docs/agent-platform/cli-agents/codex.mdx +HOARemoteControl -> src/content/docs/agent-platform/cli-agents/remote-control.mdx ## CLI commands -> doc pages # Top-level Oz CLI commands -oz agent -> src/content/docs/reference/cli/README.md -oz environment -> src/content/docs/reference/cli/integration-setup.md -oz mcp -> src/content/docs/reference/cli/mcp-servers.md -oz run -> src/content/docs/reference/cli/README.md -oz model -> src/content/docs/reference/cli/README.md -oz login -> src/content/docs/reference/cli/README.md -oz logout -> src/content/docs/reference/cli/README.md -oz integration -> src/content/docs/reference/cli/integration-setup.md -oz schedule -> src/content/docs/reference/cli/README.md -oz secret -> src/content/docs/reference/cli/README.md -oz provider -> src/content/docs/reference/cli/README.md +oz agent -> src/content/docs/reference/cli/index.mdx +oz environment -> src/content/docs/reference/cli/integration-setup.mdx +oz mcp -> src/content/docs/reference/cli/mcp-servers.mdx +oz run -> src/content/docs/reference/cli/index.mdx +oz model -> src/content/docs/reference/cli/index.mdx +oz login -> src/content/docs/reference/cli/index.mdx +oz logout -> src/content/docs/reference/cli/index.mdx +oz integration -> src/content/docs/reference/cli/integration-setup.mdx +oz schedule -> src/content/docs/reference/cli/index.mdx +oz secret -> src/content/docs/reference/cli/index.mdx +oz provider -> src/content/docs/reference/cli/index.mdx ## API endpoints -> doc pages # Public API endpoints -POST /agent/run -> src/content/docs/reference/api-and-sdk/README.md -GET /agent/runs -> src/content/docs/reference/api-and-sdk/README.md -GET /agent/runs/{runId} -> src/content/docs/reference/api-and-sdk/README.md +POST /agent/run -> src/content/docs/reference/api-and-sdk/index.mdx +GET /agent/runs -> src/content/docs/reference/api-and-sdk/index.mdx +GET /agent/runs/{runId} -> src/content/docs/reference/api-and-sdk/index.mdx # Internal/infrastructure endpoints (not part of public API, no docs needed) GET /block/embed/:id -> internal @@ -236,6 +262,7 @@ NewTabStyling AmbientAgentsRTC OzBranding OzLaunchModal +OpenWarpLaunchModal GetStartedTab CreateProjectFlow CodeLaunchModal @@ -243,6 +270,10 @@ ValidateAutosuggestions ClearAutosuggestionOnEscape OzPlatformSkills +# Server-side / infrastructure flags that don't need user-facing docs +ListSkills +SyncAmbientPlans + # UI implementation details (not user-facing features) FallbackModelLoadOutputMessaging IncrementalAutoReload diff --git a/.agents/skills/missing_docs/scripts/audit_docs.py b/.agents/skills/missing_docs/scripts/audit_docs.py index f6c0237..df89204 100755 --- a/.agents/skills/missing_docs/scripts/audit_docs.py +++ b/.agents/skills/missing_docs/scripts/audit_docs.py @@ -96,7 +96,7 @@ def parse_stale_terms(path: Path) -> list[tuple[str, str]]: # Helpers # --------------------------------------------------------------------------- -def find_repo(name: str, explicit_path: str | None, docs_root: Path) -> Path | None: +def find_repo(name: str, explicit_path: str | None, base: Path) -> Path | None: """Find a sibling repo by name, or use the explicit path.""" if explicit_path: p = Path(explicit_path).resolve() @@ -106,7 +106,7 @@ def find_repo(name: str, explicit_path: str | None, docs_root: Path) -> Path | N return None # Try sibling directory (docs is at .../code/docs, look for .../code/) - sibling = docs_root.parent / name + sibling = base.parent / name if sibling.exists(): return sibling return None @@ -142,23 +142,44 @@ def camel_to_search_terms(flag_name: str) -> list[str]: """ # Split on camel case boundaries words = re.sub(r"([a-z])([A-Z])", r"\1 \2", flag_name).split() - terms = [] + lower_words = [w.lower() for w in words] + terms: list[str] = [] # Full phrase - full = " ".join(w.lower() for w in words) - terms.append(full) + terms.append(" ".join(lower_words)) # Last 2-3 words (the most distinctive part) if len(words) > 2: - terms.append(" ".join(w.lower() for w in words[-2:])) - terms.append(" ".join(w.lower() for w in words[-3:])) + terms.append(" ".join(lower_words[-2:])) + terms.append(" ".join(lower_words[-3:])) + + # First 2 words (e.g. "code review" from CodeReviewFind) + if len(words) > 2: + terms.append(" ".join(lower_words[:2])) + + # Strip a trailing UI/V2 suffix that is rarely present in docs + suffix_stripped = [w for w in lower_words if w not in {"ui", "v2", "v1", "view", "command", "menu"}] + if suffix_stripped and suffix_stripped != lower_words: + terms.append(" ".join(suffix_stripped)) # Lowercase concatenated (matches code references) terms.append(flag_name.lower()) # snake_case version - snake = "_".join(w.lower() for w in words) - terms.append(snake) + terms.append("_".join(lower_words)) + + # Slash-command form for *Command / *SlashCommand flags + if flag_name.endswith("SlashCommand"): + base = flag_name[: -len("SlashCommand")] + kebab = re.sub(r"([a-z])([A-Z])", r"\1-\2", base).lower() + terms.append("/" + kebab) + elif flag_name.endswith("Command"): + base = flag_name[: -len("Command")] + if base: + kebab = re.sub(r"([a-z])([A-Z])", r"\1-\2", base).lower() + terms.append("/" + kebab) + # Also try "fork-from" -> "fork from" + terms.append(kebab.replace("-", " ")) return list(dict.fromkeys(terms)) # dedupe preserving order @@ -234,8 +255,30 @@ def snake_to_pascal(snake: str) -> str: return "".join(word.capitalize() for word in snake.split("_")) +def _resolve_mapped_doc(repo_root: Path, doc_path: str) -> Path | None: + """Resolve a surface-map doc path against the repo root, accepting .md or .mdx.""" + candidates = [repo_root / doc_path] + if doc_path.endswith(".md"): + candidates.append(repo_root / (doc_path[:-3] + ".mdx")) + elif doc_path.endswith(".mdx"): + candidates.append(repo_root / (doc_path[:-4] + ".md")) + for c in candidates: + if c.exists(): + return c + # Also try README -> index swap (Astro Starlight uses index.mdx instead of README.md) + if doc_path.endswith("/README.md"): + alt = repo_root / (doc_path[:-len("README.md")] + "index.mdx") + if alt.exists(): + return alt + alt = repo_root / (doc_path[:-len("README.md")] + "index.md") + if alt.exists(): + return alt + return None + + def audit_features(warp_internal: Path, docs_root: Path, surface_map: dict, - docs_text: dict[str, str]) -> list[dict]: + docs_text: dict[str, str], repo_root: Path, + weak_coverage: bool = False) -> list[dict]: """Audit feature flag coverage in docs.""" flags = parse_feature_flags(warp_internal) default_features = parse_default_features(warp_internal) @@ -259,10 +302,8 @@ def audit_features(warp_internal: Path, docs_root: Path, surface_map: dict, # Check if mapped in surface map if flag in feature_to_doc: doc_path = feature_to_doc[flag] - full_path = docs_root.parent / doc_path - if full_path.exists(): - continue # Mapped and doc exists — verified - else: + resolved = _resolve_mapped_doc(repo_root, doc_path) + if resolved is None: findings.append({ "flag": flag, "search_terms": camel_to_search_terms(flag), @@ -271,6 +312,28 @@ def audit_features(warp_internal: Path, docs_root: Path, surface_map: dict, "reason": f"Mapped doc {doc_path} does not exist", }) continue + if not weak_coverage: + # Surface-map presence is treated as verified — the maintainer + # has confirmed the page covers this flag. + continue + # Optional weak-coverage check: verify keywords actually appear. + try: + doc_content = resolved.read_text(encoding="utf-8").lower() + except Exception: + doc_content = "" + terms = camel_to_search_terms(flag) + # Use prose phrases and slash-command forms; skip lowercase-concat / + # snake_case which rarely match human-written copy. + check_terms = [t for t in terms if " " in t or t.startswith("/")] + if check_terms and not any(t in doc_content for t in check_terms): + findings.append({ + "flag": flag, + "search_terms": terms, + "severity": "low", + "suggested_doc_path": doc_path, + "reason": f"Mapped doc {doc_path} exists but does not mention feature keywords (weak coverage)", + }) + continue # Not in surface map — search docs for mentions terms = camel_to_search_terms(flag) @@ -344,7 +407,7 @@ def parse_subcommands_from_file(warp_internal: Path, filename: str) -> list[str] def audit_cli(warp_internal: Path, docs_root: Path, surface_map: dict, - docs_text: dict[str, str]) -> list[dict]: + docs_text: dict[str, str], repo_root: Path) -> list[dict]: """Audit CLI command coverage in docs.""" commands = parse_cli_commands(warp_internal) cli_to_doc = surface_map.get("cli_to_doc", {}) @@ -366,7 +429,7 @@ def audit_cli(warp_internal: Path, docs_root: Path, surface_map: dict, # Check surface map if cmd_str in cli_to_doc: doc_path = cli_to_doc[cmd_str] - if (docs_root.parent / doc_path).exists(): + if _resolve_mapped_doc(repo_root, doc_path) is not None: continue # Mapped and exists # Search CLI docs for the command name @@ -637,18 +700,28 @@ def main(): choices=["high", "medium", "low"], help="Filter results by minimum severity", ) + parser.add_argument( + "--weak-coverage", + action="store_true", + help="Also flag features whose mapped doc exists but doesn't mention " + "feature keywords (noisy; produces low-severity findings)", + ) args = parser.parse_args() # Find repos - docs_root = SKILL_DIR.parent.parent.parent # .warp/skills/missing_docs -> docs root - docs_root = docs_root / "docs" + repo_root = SKILL_DIR.parent.parent.parent # .agents/skills/missing_docs -> docs repo root + # Astro Starlight layout: docs live under src/content/docs + docs_root = repo_root / "src" / "content" / "docs" + if not docs_root.exists(): + # Fall back to legacy layout + docs_root = repo_root / "docs" if not docs_root.exists(): print(f"Error: docs directory not found at {docs_root}", file=sys.stderr) sys.exit(1) - warp_internal = find_repo("warp-internal", args.warp_internal, docs_root) - warp_server = find_repo("warp-server", args.warp_server, docs_root) + warp_internal = find_repo("warp-internal", args.warp_internal, repo_root) + warp_server = find_repo("warp-server", args.warp_server, repo_root) # Parse surface map surface_map = parse_surface_map(SURFACE_MAP_PATH) @@ -668,11 +741,14 @@ def main(): print(f"Using warp-internal: {warp_internal}", file=sys.stderr) if args.category in (None, "features"): print("Running feature flag coverage audit...", file=sys.stderr) - features_findings = audit_features(warp_internal, docs_root, surface_map, docs_text) + features_findings = audit_features( + warp_internal, docs_root, surface_map, docs_text, repo_root, + weak_coverage=args.weak_coverage, + ) if args.category in (None, "cli"): print("Running CLI command coverage audit...", file=sys.stderr) - cli_findings = audit_cli(warp_internal, docs_root, surface_map, docs_text) + cli_findings = audit_cli(warp_internal, docs_root, surface_map, docs_text, repo_root) if args.category in (None, "staleness"): print("Running docs staleness audit...", file=sys.stderr) diff --git a/src/content/docs/terminal/more-features/full-screen-apps.mdx b/src/content/docs/terminal/more-features/full-screen-apps.mdx index 2aa78d4..b442050 100644 --- a/src/content/docs/terminal/more-features/full-screen-apps.mdx +++ b/src/content/docs/terminal/more-features/full-screen-apps.mdx @@ -53,3 +53,16 @@ Some full-screen applications don't behave well when resizing. If you are experi ![alt-screen padding setting](../../../../assets/terminal/padding-settings.png)
The alt-screen padding setting in appearance preferences.
+ +## Kitty keyboard protocol + +Warp supports the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) (CSI u progressive enhancement) so full-screen apps can read keystrokes that legacy terminal escape sequences can't represent — for example, distinguishing `Ctrl+I` from `Tab`, capturing modifier-only key events, or detecting key release events. + +When a running app advertises that it supports the protocol, Warp emits the extended escape sequences automatically. No configuration is required. + +* **Supported in**: Vim, Neovim, Emacs, tmux, helix, and other modern TUI apps that opt into CSI u. +* **Falls back to legacy encoding** when the running app doesn't request progressive enhancement, so older programs keep working unchanged. + +:::note +If a TUI app reports unexpected key events after upgrading Warp, confirm the app itself supports the Kitty keyboard protocol. Most apps require an explicit opt-in (for example, `:set keyprotocol` in Neovim). +:::