missing_docs: fix audit for Astro layout & document Kitty keyboard protocol

[hongyi-chen]

Summary

The missing_docs skill's audit script was producing false negatives because it assumed a legacy docs/ subdirectory layout and .md filenames. On the current Astro Starlight tree (src/content/docs/, .mdx), the script resolved every mapped doc as missing and surfaced 71+ high-severity "Mapped doc does not exist" findings.

This PR makes the audit useful again, adds keyword-matching logic for slash-command flags, and patches a real coverage gap that surfaced during triage.

What changed

• audit_docs.py

  • Resolve docs from the repo root and look under src/content/docs/ (Astro layout) with a fallback to legacy docs/.
  • Accept .md ↔ .mdx interchangeably, plus README.md ↔ index.mdx, when checking surface-map entries.
  • Surface-map presence is treated as verified by default; the keyword-presence check is now opt-in via --weak-coverage (low-severity, noisier).
  • Broaden camel_to_search_terms to handle slash-command flags (RewindSlashCommand → /rewind, ForkFromCommand → /fork-from), UI-suffix flags (ContextWindowUsageV2), and first-N-words prefixes.

• feature_surface_map.md — fully refreshed:

  • Every entry now points at the real .mdx file. The previous map referenced ~40 paths under agent-platform/warp-agents/* that don't exist; those features actually live under agent-platform/local-agents/* or agent-platform/capabilities/*.
  • Added newly shipped GA flags (AskUserQuestion, OzChangelogUpdates, KittyKeyboardProtocol, WarpPacks, SharedWithMe, BundledSkills, SkillArguments, OpenCodeNotifications, CodexNotifications, etc.) to their respective pages.
  • Moved ListSkills and SyncAmbientPlans to the ignore list (server-side wiring, not user-facing).

• SKILL.md — documents --weak-coverage, the .md/.mdx resolution behavior, and corrects the script invocation path.

• terminal/more-features/full-screen-apps.mdx — adds a Kitty keyboard protocol section. The flag is GA, was unmapped previously, and the feature is most relevant to users running TUI apps that need progressive-enhancement key reporting.

Audit results

Before: 71 high + 47 stale findings (almost all stale-map false positives).

After: default mode reports 0 feature/CLI/API gaps and 47 staleness candidates. --weak-coverage surfaces ~30 mapped pages whose target file exists but where the feature name doesn't appear verbatim — a useful follow-up list for the docs team to review.

Test plan

• npm run build — clean (316 pages built in ~58s)
• python3 .agents/skills/missing_docs/scripts/audit_docs.py --warp-internal /workspace/warp-internal --warp-server /workspace/warp-server — runs without errors
• python3 .agents/skills/missing_docs/scripts/audit_docs.py --weak-coverage --category features — produces the expected weak-coverage list
• Manual review of the new Kitty keyboard protocol section for accuracy

This PR was created by Oz (running Claude Code).

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 26, 2026 11:44pm

[dannyneira]

approving to unblock, should be good to merge once conflicts are resolved

[hongyi-chen]

🔄 Rebased onto current main.

Since this PR was opened, #75 merged with overlapping fixes (path resolution, surface-map cleanup, internal sentinel for hidden CLI commands, VerticalTabsSummaryMode mapping). To avoid reverting any of that work, I reset this branch to main and reapplied only the additions that #75 didn't include:

• src/content/docs/terminal/more-features/full-screen-apps.mdx — new "Kitty keyboard protocol" section so TUI users have a doc page for the GA flag.
• .agents/skills/missing_docs/references/feature_surface_map.md — point KittyKeyboardProtocol at the .mdx file and fix the stale .warp/skills/... script-path comment.
• .agents/skills/missing_docs/scripts/audit_docs.py — add opt-in --weak-coverage flag that, on top of the default "mapped == verified" check, also confirms feature keywords actually appear in the mapped doc (low-severity, noisy by design). Also update the docstring path references.
• .agents/skills/missing_docs/SKILL.md — document --weak-coverage, the .md/.mdx resolution behavior, and the correct crates/warp_features/src/lib.rs source path.

Validation:

• npm run build — 334 pages built clean.
• python3 .agents/skills/missing_docs/scripts/audit_docs.py --help shows the new flag; default run still reports zero gaps.
• python3 .agents/skills/style_lint/style_lint.py --changed reports no issues.

Updated by Oz.