docs(audit): refresh missing_docs surface map and snapshot#332
Conversation
- Allowlist the Starlight 404 splash page and the draft Jira integration page (draft: true, non-GA) in the surface map's unlisted-pages section. - Regenerate surface_snapshot.json (advances changelog baseline to 2026.07.09; records new agents.usage_display_mode setting, run-cloud harness CLI flags, NldPromptHistoryMatch dogfood flag, and the POST /factory/avatar route). Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
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 |
![oz-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 audit bookkeeping by adding two unlisted-page allowlist entries and updating the generated surface snapshot for recently detected flags, CLI flags, API routes, settings, and changelog baseline.
Concerns
- The Jira draft page is added to the permanent unlisted-page allowlist, but the audit snapshot does not track docs frontmatter or sidebar promotion, so the structure audit can keep suppressing the page after
draft: trueis removed.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| # 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 |
There was a problem hiding this comment.
audit_unlisted_pages() will continue suppressing it after draft: true is removed; the snapshot does not track docs frontmatter or sidebar promotion, so this will not reliably re-flag on GA. Skip draft pages in the audit itself or remove this allowlist entry before merging.
2 participants
Summary
Companion audit-bookkeeping PR for the
missing_docsdrift-watch run. Collects the shared surface-map and snapshot changes so they don't conflict across the feature PRs.404— the custom Starlight 404 page (template: splash), rendered through Starlight's own/404route, so it's intentionally not in the sidebar.platform/integrations/jira— the Jira integration page isdraft: true(private beta; the Oz Jira app isn't published to the Atlassian marketplace yet). Kept out of the sidebar until GA; the snapshot diff will re-flag it on promotion.--update-snapshot. Advances the changelog baseline to2026.07.09and records the newagents.usage_display_modesetting, theoz agent run-cloudharness flags, theNldPromptHistoryMatchdogfood flag, and thePOST /factory/avatarroute.Findings addressed in sibling PRs
agents.usage_display_modesetting → docs: document agents.usage_display_mode setting #330oz agent run-cloudharness flags (--harness,--claude-auth-secret,--codex-auth-secret) → docs: document harness flags on oz agent run-cloud #331Deferred findings (nothing silently dropped)
API endpoints — deferred to the
sync-openapi-specskill (kept separate per policy). warp-server is private; these 19 public-API routes are not in the released OpenAPI spec, so they must not be hand-documented. Route released ones throughsync-openapi-spec; map the rest internal after confirming status:GET /agent/artifacts/{uid}GET /agent/events,GET /agent/events/stream,POST /agent/events/{run_id}POST /agent/messages,GET /agent/messages/{run_id},POST /agent/messages/{id}/read,POST /agent/messages/{id}/deliveredGET|PUT|DELETE /agent/schedules/{id},POST /agent/schedules/{id}/pause,POST /agent/schedules/{id}/resumeGET|POST /factory,GET|PATCH|DELETE /factory/{uid},POST /factory/avatarTerminology / staleness (32 low-severity findings) — deferred to the
style_lintskill, which owns terminology and style enforcement (e.g. "warp ai", "ai credits", "agent-mode", "warp terminal", "ambient agent" phrasings across ~32 pages).Changelog items (verified, no dedicated docs needed):
terminal/windows/tabs.mdx("Move a tab to another window").Snapshot-only:
NldPromptHistoryMatch(dogfood) — tracked only; no docs until promotion.Validation
npm run buildpasses on the combined tree.Conversation: https://staging.warp.dev/conversation/0ee78198-1342-4558-b918-b484f4655005
Run: https://oz.staging.warp.dev/runs/019f5c6b-ee12-75f1-a353-e0ef6e3edd4f
This PR was generated with Oz.