chore(missing_docs): bookkeeping for the 2026-09-14 and 2026-09-16 exhaustive audits

[hongyi-chen]

Bookkeeping-only output of two exhaustive missing_docs drift-watch runs, 2026-09-14 and 2026-09-16, over the same stable release. No public doc pages change. No feature PRs accompany this one — every candidate either failed the worthiness gate or already carried a recorded verdict.

What these runs audited

Both audit modes ran against fresh warp (master) and warp-server (develop) checkouts and exited 0, with audits_skipped: [] — no parser sanity guard tripped, so no category was silently skipped.

Completeness accounting reported an empty unaccounted bucket across 296 feature flags, 91 CLI commands, 220 API routes, 65 slash commands, and 232 settings.

Findings by category:

• Feature flags, CLI commands, slash commands, settings, unlisted pages (structure), stale doc references, surface-map hygiene - 0 findings each.
• API endpoints - 1 (medium), also the only surface_changes entry.
• Docs staleness - 24 (low), all already decided.
• --weak-coverage - 82 (low), run for exhaustiveness even though it is off by default.

The release gate (check_new_release.py) exited 10 on both runs: the current stable v0.2026.09.09.08.26.stable_02 was already processed by #736. That is why changelog_review is empty and why last_release_processed.json is untouched here. The standing coverage and snapshot-diff sweep ran anyway, as requested.

What changed

• feature_surface_map.md - one new entry, GET /networking/egress-ranges -> internal.
• changelog_decisions.md - seven rows recording both runs' verdicts, including the re-verifications and the not-a-verdict bookkeeping rows.
• surface_snapshot.json - regenerated on 2026-09-14. The delta is exactly one line: the new route enters the baseline so --diff stops re-reporting it.

The one new surface: GET /networking/egress-ranges

Verdict: deferred (Gate 0). Mapped -> internal. Not hand-documented.

The route returns the canonical outbound IP ranges for Warp-hosted agents, scoped to the authenticated principal's active team (RegisterNetworkingRoutes / EgressRangesHandler in router/handlers/public_api/networking.go, behind middleware.EnforceAuth()).

Gate 0 fails on two independent markers in warp-server's canonical public_api/openapi.yaml: the networking tag carries x-internal: true, and so does the getEgressRanges operation. sync_openapi.py drops x-internal operations wholesale, so the route cannot reach developers/agent-api-openapi.yaml while those markers stand — that file has zero networking paths and zero x-internal entries today. The endpoint backs the Admin Panel's hosted-agent egress CIDR list, not the released public Agent API.

It is not a content gap either: the egress ranges themselves are already published on platform/warp-hosting.mdx under "Networking".

Re-check if the x-internal markers come off, and route it through sync-openapi-spec rather than hand-drafting it.

The 2026-09-16 re-verification

A second exhaustive sweep two days later found nothing new, and verified that rather than assuming it.

Running --update-snapshot against warp at 91dad6a70 and warp-server at 91b349221 (both 2026-09-16) reproduced this branch's surface_snapshot.json byte for byte — across flags, CLI commands and per-module flags, API routes, slash commands, settings, Oz web app routes, server-side agent tools, and bundled skills. No tracked surface moved in the interval, which is why the snapshot is unchanged by the second run and only the ledger gains a row.

Against main the run reproduced the 2026-09-14 findings exactly. With this branch's map entry applied, undocumented_api_endpoints and surface_changes both drop to 0 and only the already-decided staleness rows remain.

The load-bearing evidence was re-derived from source rather than carried forward:

• The networking tag and the getEgressRanges operation still both carry x-internal: true in warp-server public_api/openapi.yaml (lines 31-33 and 42-43).
• All five staleness term classes were re-checked at their source lines — the historical Warp AI FAQ heading, the live "Generate commands as command-line input" heading, AI Command Search, the AI credits bucket name, and the permitted distinguishing Warp terminal usage.
• The skill's three test suites pass (19 reviewer-resolution tests, 18 audit tests, and the release-gate contract tests), so no extractor has silently rotted.

Deferred and rejected findings

Nothing was silently dropped. Each item below has a full row in changelog_decisions.md.

• GET /networking/egress-ranges - deferred, Gate 0, as above. Re-surfaces if the x-internal markers are removed.
• Hardcoded egress CIDR list on platform/warp-hosting.mdx - noted, no change available. The page publishes the ranges as a hardcoded list while warp-server now computes the same set server-side, so the two can drift with nothing to catch it. The page cannot link the endpoint because it is x-internal, and the current list is not known to be wrong. Flagged for the docs owner rather than editing correct content.
• 24 potentially_stale_docs - no docs change; re-verified line by line on both runs. 13 files are the ai credits bucket-name false positive; all 13 warp terminal hits are the distinguishing usage the rule's own reason exempts; warp ai is the historical FAQ heading about the retired chat panel; generate command matches live headings on the page titled "Generate (Legacy)"; ai command matches AI Command Search.
• ai credits stale-term rule - deliberately left unchanged. The ledger's Notes section already records this as an open style-policy question for a human owner, since AGENTS.md contradicts itself (its credits entry bans the prefix; its compute credits entry uses "AI credits" as a bucket name) and style_lint does not flag the term. Narrowing the rule unattended would be the agent resolving a policy call that was explicitly reserved for a person.
• 82 --weak-coverage findings - no docs change; keyword artifacts on internal CamelCase flag names. Four spot-verified: GroupedTabs, CloudRunners, BundledSkills, and AskUserQuestion are all genuinely documented.

Content design plan

Not applicable. Per .agents/references/content-design-plan.md, bookkeeping and snapshot refreshes are in the skip list, and no page was drafted or updated.

Validation

• npm ci && npm run build - passes on both runs (386 Markdown docs, 388 HTML files as of 2026-09-16).
• Re-ran the audit after the changes: undocumented_api_endpoints and surface_changes are both 0, map_hygiene stays 0 (the new map entry validates against a live extracted route), and unaccounted is still empty. Only the 24 already-decided staleness findings remain.

Reviewer

suggest_reviewers.py resolved only a team (@warpdotdev/fa-warp-3, via /logic/ai/ambient_agents/) on both runs; router/handlers/public_api/networking.go itself has no owner entry in warp-server's ownership files. Per the reviewer policy, teams are never requested and there is no fallback, so this PR has no requested reviewer and names the owning team here instead.

Documentation risk

Risk: low
Rationale: Bookkeeping only: surface-map entry, decision-ledger rows, and a regenerated surface snapshot under .agents/. No public doc page changes, no product claims, no command, API, setting, or integration behavior changes.
Source files consulted: warp-server/router/handlers/public_api/networking.go@91b349221, warp-server/public_api/openapi.yaml@91b349221, warp/crates/warp_features/src/lib.rs@91dad6a70
Engineering review status: not-applicable
Docs override: none

Unverified claims

None. No VERIFY markers in the changed content.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 16, 2026 5:10pm UTC

[hongyi-chen]

This PR was generated with Warp.

Comment @warp-agent on this PR to send it follow-up work.

  View origin

[warp-for-oss]

@hongyi-chen

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 /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR records missing-docs bookkeeping for the 2026-09-14 audit: it adds decision-ledger rows, maps GET /networking/egress-ranges as internal, and refreshes the generated surface snapshot. No public documentation pages or executable code change.

Concerns

• One new ledger row records audits_skipped: null, which should be clarified because the audit report represents skipped audits as an array and the PR body says no audits were skipped.
• No security concerns found in the changed bookkeeping files.
• No spec drift found; no approved or repository spec context was provided.

Verdict

Found: 0 critical, 0 important, 1 suggestions

Approve with nits

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

💡 [SUGGESTION] Use audits_skipped: [] or no audits_skipped instead of audits_skipped: null; the audit report stores skipped audits as an array, so null makes this row look like the field was absent rather than empty.

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• No findings.

Verdict

Approve

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• No findings.

Verdict

Approve

[warp-agent-staging]

Reviewed current head c28c01fa2204b3a534e5a7446d717c404f33b156. The audit bookkeeping is internally consistent, its cited source revisions check out, and all required checks pass. The existing audits_skipped ledger suggestion is nonblocking.

Responding as Docs Factory (V2): Open session