From 392f3334fc0b0a21e02fd5294089a9266cbc48ea Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Fri, 21 Aug 2026 17:16:48 +0000 Subject: [PATCH] chore(missing_docs): refresh surface map and snapshot Bookkeeping for this drift-watch run: repoint two stale map targets, map the newly GA WellKnownMcpIds and FactoryMcp flags, ignore two internal orchestration flags, mark the new Factory REST routes internal, prune routes that no longer exist, and regenerate the surface snapshot. Co-Authored-By: Warp --- .../references/feature_surface_map.md | 109 ++++++++++++++---- .../references/surface_snapshot.json | 70 ++++++++--- 2 files changed, 146 insertions(+), 33 deletions(-) diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index c395f6e0..864120c3 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -25,12 +25,16 @@ auto-surfaces for docs once the flag goes GA. ## Feature flags -> doc pages -AgentMode -> src/content/docs/agents/local-agents/overview.mdx +# The local-agents overview page was folded into the agents landing page +# (/agents/local-agents/overview now 308s to /agents/ in vercel.json). +AgentMode -> src/content/docs/agents/index.mdx AgentManagementView -> src/content/docs/platform/managing-cloud-agents.md AgentManagementDetailsView -> src/content/docs/platform/managing-cloud-agents.md AgentModeComputerUse -> src/content/docs/agents/capabilities/computer-use/index.mdx AgentModeWorkflows -> src/content/docs/knowledge-and-collaboration/warp-drive/workflows.md -AgentOnboarding -> src/content/docs/agents/getting-started/agents-in-warp.mdx +# agents-in-warp was folded into the agents landing page as well +# (/agents/getting-started/agents-in-warp now 308s to /agents/). +AgentOnboarding -> src/content/docs/agents/index.mdx AIRules -> src/content/docs/agents/capabilities/rules.mdx AIResumeButton -> src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx InlineCodeReview -> src/content/docs/agents/local-agents/interactive-code-review.mdx @@ -232,6 +236,17 @@ GeminiEnterprise -> src/content/docs/enterprise/enterprise-features/byollm-gemin # preview -> GA; documented with the rest of Warp's link handling. OscHyperlinks -> src/content/docs/terminal/more-features/files-and-links.mdx +# Well-known managed MCP ids: accepts short integration ids (linear, slack, +# jira) wherever a Warp MCP server UUID is accepted — bare `--mcp` arguments and +# `warp_id` values in MCP configs. Promoted dogfood -> GA; documented in the CLI +# MCP reference (and the cloud agent MCP schema page). +WellKnownMcpIds -> src/content/docs/reference/cli/mcp-servers.mdx + +# Auto-attaches the Warp-hosted Factory MCP server to agent sessions with no +# manual setup. Promoted dogfood -> GA; that zero-config behavior is documented +# in the "Connect and authenticate" section of the Factory MCP page. +FactoryMcp -> src/content/docs/factories/factory-mcp.mdx + ## CLI commands -> doc pages # Top-level Oz CLI commands @@ -380,14 +395,16 @@ 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 -# @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". +# Oz Factory REST API (router/handlers/public_api/factory*.go). Warp Factories +# is now documented publicly (src/content/docs/factories/) as an Early Access +# product, but its REST API is a different question: none of these routes appear +# in warp-server's canonical public spec, so they are not part of the released +# public Oz Agent API and must not be hand-documented. They stay internal; +# revisit and route through the sync-openapi-spec skill if/when the Factory REST +# API is released into the spec. See SKILL.md "Public vs. private surfaces". GET /factory -> internal +GET /factory/access -> internal +GET /factory-alias/{alias} -> internal POST /factory -> internal POST /factory/avatar -> internal GET /factory/{uid} -> internal @@ -398,6 +415,34 @@ POST /factory/{uid}/plan -> internal GET /factory/{uid}/source -> internal PUT /factory/{uid}/source -> internal DELETE /factory/{uid}/source -> internal +# Factory-as-code source browsing, editing, export, and merge plumbing backing +# the factory definition editor in the Oz web app. +GET /factory/{uid}/source/tree -> internal +GET /factory/{uid}/source/file -> internal +PUT /factory/{uid}/source/files -> internal +GET /factory/{uid}/source/export -> internal +POST /factory/{uid}/source/clone-url -> internal +GET /factory/{uid}/source/link-readiness -> internal +POST /factory/{uid}/merges -> internal +POST /factory/{uid}/merges/check -> internal +GET /factory/{uid}/merges/{merge_uid} -> internal +# Factory file JSON schemas and validation, consumed by the factory definition +# editor and the factory-files authoring tooling. +GET /factory-files/schemas -> internal +GET /factory-files/schemas/{schema_version} -> internal +GET /factory-files/schemas/{schema_version}/{document} -> internal +POST /factory-files/validate -> internal +# Factory review (AI review of a factory definition) and its refine loop. +GET /factory/{uid}/review -> internal +POST /factory/{uid}/review/refine -> internal +# Factory outbound webhooks: CRUD, delivery history, and secret rotation. +GET /factory/webhooks -> internal +POST /factory/webhooks -> internal +GET /factory/webhooks/{uid} -> internal +PUT /factory/webhooks/{uid} -> internal +DELETE /factory/webhooks/{uid} -> internal +GET /factory/webhooks/{uid}/deliveries -> internal +POST /factory/webhooks/{uid}/rotate -> internal GET /factory/{uid}/syncs -> internal GET /factory/{uid}/task-by-conversation -> internal GET /factory/{uid}/tasks -> internal @@ -405,12 +450,27 @@ 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 +POST /factory/{uid}/tasks/{task_uid}/cancel -> internal +GET /factory/{uid}/task-by-run -> internal # Also marked `x-internal: true` in warp-server's canonical spec, so the publish # filter strips it from the public docs copy. GET /factory/{uid}/metrics -> internal +GET /factory/{uid}/metrics/cost-by-pr-size -> internal +GET /factory/{uid}/metrics/run-breakdown -> internal +GET /factory/{uid}/metrics/top-prs -> 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/jira/projects -> internal +GET /factory/{uid}/integrations/jira/labels -> internal +GET /factory/{uid}/integrations/jira/statuses -> internal +GET /factory/{uid}/integration-activations -> internal +GET /factory/{uid}/integration-destinations -> internal +GET /factory/{uid}/gitlab-automation-capability -> internal +POST /factory/{uid}/gitlab-automation-capability/refresh -> internal +# Integration pickers used during factory setup, before a factory exists. +GET /factory-setup/integrations/jira/projects -> internal +GET /factory-setup/integrations/linear/teams -> internal GET /factory/automations -> internal POST /factory/automations -> internal GET /factory/automations/events/{provider} -> internal @@ -423,17 +483,16 @@ 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/scorers/{scorer_id}/metrics/pass-rate -> internal +# The scorer pause/resume routes and the autofix-config trio were replaced by +# the self-improvement-config routes below; their dead map entries were pruned. +GET /factory/scorers/{scorer_id}/self-improvement-config -> internal +PUT /factory/scorers/{scorer_id}/self-improvement-config -> internal +DELETE /factory/scorers/{scorer_id}/self-improvement-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 @@ -455,6 +514,8 @@ 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 +POST /factory/{uid}/benchmarks/suites/{suite_uid}/tasks -> internal +POST /factory/{uid}/benchmarks/suites/{suite_uid}/tasks/compose-from-run -> internal GET /factory/{uid}/benchmarks/runs -> internal GET /factory/{uid}/benchmarks/runs/{run_uid} -> internal GET /factory/{uid}/benchmarks/runs/{run_uid}/results -> internal @@ -608,10 +669,8 @@ guides/agent-workflows/warp-vs-claude-code # Custom Starlight 404 page (template: splash). Starlight renders it through its # own prerendered /404 route, so it is intentionally not in the sidebar. 404 -# Jira integration page is draft: true (private beta — the Oz Jira app is not yet -# published to the Atlassian marketplace). Kept out of the sidebar until the -# integration goes GA; the snapshot diff will flag it for docs on promotion. -platform/integrations/jira +# The Jira integration page left draft status and is now listed in src/sidebar.ts, +# so its allowlist entry was pruned. ## Flags to ignore (internal-only, not user-facing) @@ -721,6 +780,16 @@ 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 +# Orchestration plumbing promoted dogfood -> GA. Neither changes what a user sees +# or configures, so both are internal implementation details of the documented +# multi-agent orchestration feature (platform/orchestration/multi-agent-runs.mdx): +# - WaitForEventsParentRegistration: on `wait_for_events`, confirms parent status +# with the server and registers an orchestrator for the ancestor event stream so +# children created out-of-band (CLI/API) still deliver events. +# - OrchestrationUnifiedStack: consolidates child-state tracking behind a single +# tracker, one ancestor SSE per parent family, and one remote-child placeholder. +WaitForEventsParentRegistration +OrchestrationUnifiedStack # 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 diff --git a/.agents/skills/missing_docs/references/surface_snapshot.json b/.agents/skills/missing_docs/references/surface_snapshot.json index 6c6c7d5f..91cc8b3e 100644 --- a/.agents/skills/missing_docs/references/surface_snapshot.json +++ b/.agents/skills/missing_docs/references/surface_snapshot.json @@ -96,6 +96,7 @@ "CreateProjectFlow": "ga", "CreatingSharedSessions": "dogfood", "CrossRepoContext": "dogfood", + "CtrlCCancelsThirdPartyHarness": "dogfood", "CustomModelRouters": "ga", "CycleNextCommandSuggestion": "other", "DebugMode": "other", @@ -110,7 +111,7 @@ "EditableMarkdownMermaid": "dogfood", "EmbeddedCodeReviewComments": "other", "ExpandEditToPane": "ga", - "FactoryMcp": "dogfood", + "FactoryMcp": "ga", "FallbackModelLoadOutputMessaging": "ga", "FastForwardAutoexecuteButton": "ga", "FetchChannelVersionsFromWarpServer": "other", @@ -194,6 +195,7 @@ "OpenWarpLaunchModal": "ga", "OpenWarpNewSettingsModes": "ga", "OrchestrationLaunchModal": "ga", + "OrchestrationUnifiedStack": "ga", "OscHyperlinks": "ga", "OzChangelogUpdates": "ga", "OzHandoff": "ga", @@ -204,7 +206,7 @@ "PRCommentsV2": "ga", "PartialNextCommandSuggestions": "other", "PendingUserQueryIndicator": "ga", - "PeriodicHandoffCheckpoints": "other", + "PeriodicHandoffCheckpoints": "dogfood", "PinnedTabs": "ga", "PluggableNotifications": "ga", "PredictAMQueries": "other", @@ -279,7 +281,7 @@ "VideoRecording": "ga", "ViewingSharedSessions": "ga", "VimCodeEditor": "ga", - "WaitForEventsParentRegistration": "dogfood", + "WaitForEventsParentRegistration": "ga", "WarpControlCli": "dogfood", "WarpManagedSecrets": "ga", "WarpPacks": "ga", @@ -288,7 +290,7 @@ "WebSearchUI": "ga", "WelcomeBlock": "other", "WelcomeTips": "other", - "WellKnownMcpIds": "dogfood", + "WellKnownMcpIds": "ga", "WithSandboxTelemetry": "other", "WorkflowAliases": "ga" }, @@ -680,6 +682,7 @@ "--no-computer-use", "--no-snapshot", "--open", + "--parent-run-id", "--profile", "--prompt", "--remove-all-secrets", @@ -699,7 +702,8 @@ "--snapshot-upload-timeout", "--sort-by", "--sort-order", - "--strict-mcp-startup" + "--strict-mcp-startup", + "--title" ], "api_key": [ "--agent", @@ -818,7 +822,8 @@ "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/scorers/{scorer_id}/self-improvement-config", + "DELETE /api/v1/factory/webhooks/{uid}", "DELETE /api/v1/factory/{uid}", "DELETE /api/v1/factory/{uid}/benchmarks/suites/{suite_uid}", "DELETE /api/v1/factory/{uid}/source", @@ -856,25 +861,42 @@ "GET /api/v1/agent/tasks", "GET /api/v1/agent/tasks/{id}", "GET /api/v1/factory", + "GET /api/v1/factory-alias/{alias}", + "GET /api/v1/factory-files/schemas", + "GET /api/v1/factory-files/schemas/{schema_version}", + "GET /api/v1/factory-files/schemas/{schema_version}/{document}", + "GET /api/v1/factory-setup/integrations/jira/projects", + "GET /api/v1/factory-setup/integrations/linear/teams", + "GET /api/v1/factory/access", "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}/metrics/pass-rate", "GET /api/v1/factory/scorers/{scorer_id}/results", "GET /api/v1/factory/scorers/{scorer_id}/results/reasons", + "GET /api/v1/factory/scorers/{scorer_id}/self-improvement-config", + "GET /api/v1/factory/webhooks", + "GET /api/v1/factory/webhooks/{uid}", + "GET /api/v1/factory/webhooks/{uid}/deliveries", "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}/gitlab-automation-capability", + "GET /api/v1/factory/{uid}/integration-activations", + "GET /api/v1/factory/{uid}/integration-destinations", "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/jira/labels", + "GET /api/v1/factory/{uid}/integrations/jira/projects", + "GET /api/v1/factory/{uid}/integrations/jira/statuses", "GET /api/v1/factory/{uid}/integrations/linear/issues", "GET /api/v1/factory/{uid}/integrations/linear/projects", "GET /api/v1/factory/{uid}/integrations/linear/teams", @@ -883,10 +905,20 @@ "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}/merges/{merge_uid}", "GET /api/v1/factory/{uid}/metrics", + "GET /api/v1/factory/{uid}/metrics/cost-by-pr-size", + "GET /api/v1/factory/{uid}/metrics/run-breakdown", + "GET /api/v1/factory/{uid}/metrics/top-prs", + "GET /api/v1/factory/{uid}/review", "GET /api/v1/factory/{uid}/source", + "GET /api/v1/factory/{uid}/source/export", + "GET /api/v1/factory/{uid}/source/file", + "GET /api/v1/factory/{uid}/source/link-readiness", + "GET /api/v1/factory/{uid}/source/tree", "GET /api/v1/factory/{uid}/syncs", "GET /api/v1/factory/{uid}/task-by-conversation", + "GET /api/v1/factory/{uid}/task-by-run", "GET /api/v1/factory/{uid}/tasks", "GET /api/v1/factory/{uid}/tasks/{task_uid}", "GET /api/v1/harness-support/transcript", @@ -924,20 +956,27 @@ "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-files/validate", "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/webhooks", + "POST /api/v1/factory/webhooks/{uid}/rotate", "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}/benchmarks/suites/{suite_uid}/tasks", + "POST /api/v1/factory/{uid}/benchmarks/suites/{suite_uid}/tasks/compose-from-run", + "POST /api/v1/factory/{uid}/gitlab-automation-capability/refresh", + "POST /api/v1/factory/{uid}/merges", + "POST /api/v1/factory/{uid}/merges/check", "POST /api/v1/factory/{uid}/plan", + "POST /api/v1/factory/{uid}/review/refine", + "POST /api/v1/factory/{uid}/source/clone-url", "POST /api/v1/factory/{uid}/tasks", + "POST /api/v1/factory/{uid}/tasks/{task_uid}/cancel", "POST /api/v1/harness-support/block-snapshot", "POST /api/v1/harness-support/commit-snapshot", "POST /api/v1/harness-support/external-conversation", @@ -961,9 +1000,11 @@ "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/scorers/{scorer_id}/self-improvement-config", + "PUT /api/v1/factory/webhooks/{uid}", "PUT /api/v1/factory/{uid}/integrations/linear/teams/{team_id}/labels", "PUT /api/v1/factory/{uid}/source", + "PUT /api/v1/factory/{uid}/source/files", "PUT /api/v1/memory_stores/{uid}", "PUT /api/v1/memory_stores/{uid}/memories/{memoryUid}" ], @@ -1224,6 +1265,7 @@ "terminal.input.classic_completions_mode": "always_on", "terminal.input.command_corrections": "always_on", "terminal.input.completions_open_while_typing": "always_on", + "terminal.input.enable_ai_command_search_hash_trigger": "always_on", "terminal.input.enable_slash_commands_in_terminal": "always_on", "terminal.input.error_underlining_enabled": "always_on", "terminal.input.extra_meta_keys": "always_on", @@ -1231,6 +1273,7 @@ "terminal.input.input_box_type_setting": "always_on", "terminal.input.middle_click_paste_enabled": "always_on", "terminal.input.outline_codebase_symbols_for_at_context_menu": "always_on", + "terminal.input.right_click_behavior": "always_on", "terminal.input.show_hint_text": "always_on", "terminal.input.show_terminal_input_message_bar": "always_on", "terminal.input.syntax_highlighting": "always_on", @@ -1365,6 +1408,7 @@ "claude-api": "bundled", "create-skill": "bundled", "create-tab-config": "bundled", + "factory-files": "bundled", "factory-mcp": "bundled", "modify-settings": "bundled", "oz-platform": "bundled", @@ -1377,5 +1421,5 @@ "verify-ui-change-in-cloud": "dogfood", "warpctrl": "bundled" }, - "changelog_last_version": "2026.08.07" + "changelog_last_version": "2026.08.13" }