chore(missing_docs): refresh surface map and snapshot - #603
Conversation
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 <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR was generated with Warp. Comment |
|
Your GitHub account is not connected to Warp. Connect it here. |
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR refreshes the missing_docs surface map and regenerated snapshot so newly promoted, internal, moved, and removed surfaces are accounted for. I reviewed the annotated diff against the missing_docs public/private guardrails, docs review guidance, the security checklist, and the empty spec context.
Concerns
No blocking concerns found. The added map comments explain why each surface is mapped, ignored, or kept internal, and the snapshot changes are consistent with those bookkeeping updates.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
terminal.input.enable_ai_command_search_hash_trigger and terminal.input.right_click_behavior are now documented in all-settings.mdx (merged via #600), so the settings coverage audit reports zero findings for both. Regenerate the snapshot to also capture new API/slash-command surfaces added upstream since the last snapshot. Co-Authored-By: Warp <agent@warp.dev>
…mmand Rework cycle 2 for PR #603: address the two remaining coverage-gap findings from the pass-2 review. - Map `POST /factory/webhooks/dry-run` and `GET /factory/webhooks/{uid}/deliveries/{delivery_id}` as `internal` alongside the rest of the Factory webhook routes; both are registered in warp-server but absent from the OpenAPI spec. - Map `/team` as `internal` alongside the other TUI-only slash-command exceptions; it is `SlashCommandSurfaces::TuiOnly` in static_commands/commands.rs, so it isn't documented on the public slash-commands page. Co-Authored-By: Warp <agent@warp.dev>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
The surface map and snapshot refresh is accurate and the new entries hold up against the current sources; one rationale comment in the Factory REST API block states something that isn't true, though the internal routing it justifies is correct. Findings inline.
Verdict
Checks: build n/a, tests pass (missing_docs script suite, 27 run / 7 skipped), CI green, visual proof n/a
Found: 0 critical, 1 important, 0 suggestions, 0 nits
Responding as wilson: Open session · View in factory
The rationale claimed none of the Factory REST routes appear in
warp-server's canonical public spec. They do: warp-server's
public_api/openapi.yaml defines /factory and its siblings, each marked
x-internal: true, and public_api/public-openapi-filter.yaml is what
strips them from the published developers/agent-api-openapi.yaml
copy. Correct the rationale to name the actual mechanism (the
x-internal marker and publish filter) and the actual release signal
(those markers coming off), consistent with the existing
GET /factory/{uid}/metrics note a few lines below.
There was a problem hiding this comment.
Overview
The Factory REST API rationale now matches how those routes are actually handled (x-internal: true in warp-server's canonical spec, stripped by the publish filter), which was the only finding. Approving.
Verdict
Checks: build n/a, tests pass (missing_docs script suite, 27 run), CI green on the prior head with the build and Vercel checks still running on c4e038c, visual proof n/a
Found: 0 critical, 0 important, 0 suggestions, 0 nits
Responding as wilson: Open session · View in factory
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 <agent@warp.dev>
#617) * missing_docs: stop the drift-watch triage from silently seeing nothing Found by the first manual validation run of the drift-watch skill. All three defects fail the same way: the run exits 0, reports nothing, and that is indistinguishable from "nothing shipped". 1. Triage baseline ignored the release marker Two independent state files track releases. surface_snapshot.json records what was last *observed*; last_release_processed.json records what was last *triaged*. A bookkeeping PR that regenerates the snapshot advances the first without touching the second, and #603 did exactly that -- on main today the snapshot reads 2026.08.19 while the marker reads 2026.08.18. The gate fires (marker behind) but --diff returns an empty changelog_review (snapshot ahead), so the primary triage input is empty and the release gets marked processed having triaged nothing. The baseline is now the earlier of the two markers. Against current main that moves changelog_review from 0 items to 3. I introduced this when I split the marker out of the snapshot. The reasoning was sound -- the snapshot is regenerated wholesale and would lose the marker -- but it only considered the snapshot falling behind, not running ahead. 2. oz_updates were2. oz_updates were2. oz_updates were2. oz_updatrepo2. oz_updates were2. oz_updates were2. oz_up no2. oz_updates were2. oz_updates were2. oz_updates were2. oz_updatrepo2. nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnntfnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnh was not executable. Texecutable. Texecutable. Texecutable. Texecutable. Texecun. The field nThe field nThe field nThe field nThe field nThe fiel in the currcurrcurrcue pcurrcurrcurrcue pcurrcurrcurrcue pcurrcurrcurrcue pcurrcuchangelog heading would fail silently Section matching is a hardcoded allowlist against a user-facing heading, so the rename would zero out that section with no error. Added the Automation Platform variants, plus a guard that treats bullets under an unrecounrecounrecounrecounrecounrecounrecounrecounrecxes are listed as dededededededededededededededededededededededededededededededededededed ttttttttttttttttttttttttttttttttttttttttttttttttttttter launch posts use prose headings and policing all 277 entries would fail every run. Also adds the __future__ annotations import that check_new_release.py already had. Without it audit_docs.py cannot be imported on Python 3.9,already had. Without it audit_docs.py cannot be imported on Python 3.9,already had. Without it audit_docs.py cannot be importedver the baseline, the normalizer, the tracked/untracked/unknown split, and thtracked/untracked/unknown split, and thtracked/untrp.dev> * missing_docs: treat a wrong-shaped release marker as unreadable Review catch from both bots on #617. read_last_processed_release() called .get() on whatever json.loads returned, so a marker containing valid JSON of the wrong top-level type -- [], a bare string, a number -- raised AttributeError rather than taking the documented fallback to None. That aborts diff-mode triage entirely, which is a worse outcome than the desync the reader was added to fix. Guarded with isinstance(data, dict) and a warning, matching how check_new_release.py's read_state() already handles the same file. The inconsistency between two readers of one file was the actual defect. Regression test covers every bad shape: list, bare string, number, null, truncated JSON, empty file, and an object missing the expected key, plus the missing-marker and well-formed cases so the fallback cannot be achieved by breaking the happy path. Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
1 participant
Summary
Companion bookkeeping PR for this
missing_docsdrift-watch run. It carries every shared-file edit (the surface map and the regenerated snapshot) so the four feature PRs stay conflict-free. It is independently mergeable in any order: map hygiene only requires the mapped target pages to exist onmain, and every page referenced here already does.Feature PRs from the same run: #599 (well-known MCP ids), #600 (terminal input settings), #601 (tab colors), #602 (run-cloud flags).
Surface map changes
Stale targets repointed
AgentModeandAgentOnboardingpointed atagents/local-agents/overview.mdxandagents/getting-started/agents-in-warp.mdx, both deleted.vercel.json308s both URLs to/agents/, so they now map toagents/index.mdx.Newly GA flags mapped
WellKnownMcpIds→reference/cli/mcp-servers.mdx(documented in docs(mcp): document well-known managed integration ids #599).FactoryMcp→factories/factory-mcp.mdx, whose "Connect and authenticate" section already describes the zero-config attachment the flag gates.Newly GA flags ignored (internal implementation)
WaitForEventsParentRegistrationandOrchestrationUnifiedStackare orchestration plumbing behind the already-documented multi-agent orchestration feature. Neither changes anything a user sees or configures.Factory REST API
internal(webhooks, factory-file schemas and validation, source browsing/merges, review, scorer self-improvement config, benchmark tasks, integration pickers, metrics breakdowns, task cancel/lookup). Warp Factories is documented publicly, but none of these routes are in warp-server's canonical public spec, so per the skill's public/private guardrail they are not hand-documented. Revisit throughsync-openapi-specif they are released into the spec.pause/resumepair and theautofix-configtrio, superseded by theself-improvement-configroutes, plus the twofactory/autofix/*worker routes.Allowlist
platform/integrations/jirafrom the unlisted-pages allowlist: the page left draft status and is now insrc/sidebar.ts.Snapshot
surface_snapshot.jsonregenerated with--update-snapshotso the next run diffs against this baseline.Verification
Re-running the audit after these changes leaves zero findings in every code-surface category:
npm run buildpasses on the combined tree.Deferred findings
warp ai,ai credits,agent-mode,warp terminal,ambient agent) across 29 pages. Owned by thestyle_lintskill, which themissing_docsskill explicitly delegates wording issues to.internalas above; needs async-openapi-specpass if/when released.linear_agent_sessionMCP id — recognized server-side but exists for Linear-triggered runs writing agent-session activities, not as a user-facing choice, so it stays undocumented.factory-files— new in the snapshot. Docs don't enumerate bundled skills anywhere, and the subject matter it assists with is already covered byfactories/factory-as-code.mdx, so no doc change was made./connect-grok, repository-qualified skill references).gated:CLI commands, and 12gated:API routes remain deferred by design; the snapshot diff re-surfaces them on promotion.Reviewer routing
scripts/suggest_reviewers.pyresolved the owning code path to the@warpdotdev/oss-maintainersteam in the warp repo, but that team can't be requested on this repository, so the request didn't stick. Please assign a maintainer manually.Rework changes
Cycle 2 — addressed both
[IMPORTANT]coverage-gap findings from the pass-2 review:POST /factory/webhooks/dry-runandGET /factory/webhooks/{uid}/deliveries/{delivery_id}were registered internal Factory routes missing from the surface map. Mapped both-> internalalongside the rest of the webhook route block./teamisSlashCommandSurfaces::TuiOnlyinstatic_commands/commands.rs(the GUI switches teams from the title-bar pill instead) but was missing from the slash-command exceptions. Mapped it-> internalalongside the other TUI-only commands.maininto this branch (picked up an unrelated UI-path snapshot refresh, no conflicts).python3 .agents/skills/missing_docs/scripts/audit_docs.py, all categories):feature_flags,cli_commands,api_routes,slash_commands, andsettingsall reportfinding=0. The only remaining gaps are the 29 low-severitypotentially_stale_docsterminology findings, which are explicitly owned bystyle_lint, not this skill.npm run buildpasses on the merged tree.Cycle 1 — addressed both
[IMPORTANT]findings from the review pass:terminal.input.enable_ai_command_search_hash_trigger— this public GUI setting was only recorded in the snapshot, so the audit still reported it undocumented. It's now documented via docs(settings): document two new terminal.input settings #600 (merged tomain); mergedmaininto this branch to pick up that change.terminal.input.right_click_behavior— same issue and same fix: documented via docs(settings): document two new terminal.input settings #600, now merged into this branch.surface_snapshot.jsonagainst the merged tree. Re-runningpython3 .agents/skills/missing_docs/scripts/audit_docs.py --category settingsnow reports 0 settings findings (both settings showdoc_covered).npm run buildpasses on the merged tree.