missing_docs: document Kitty keyboard protocol and add --weak-coverage audit mode

Rebases the original PR onto current `main` after PR #75 shipped overlapping
path-resolution fixes. The structural cleanup from PR #75 is preserved; this
commit reapplies only the additions that PR #75 didn't include.

- full-screen-apps.mdx: add a "Kitty keyboard protocol" section so the
  newly-shipped flag is documented where TUI users will look.
- feature_surface_map.md: point KittyKeyboardProtocol at the .mdx file and
  fix the stale `.warp/skills/...` script-path comment.
- audit_docs.py: add an 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).
- SKILL.md: document `--weak-coverage`, the `.md`/`.mdx` resolution
  behavior, and the correct `crates/warp_features/src/lib.rs` source path.

Original author: hongyi-chen <hongyigma@gmail.com>
Co-Authored-By: Oz <oz-agent@warp.dev>

Author: hongyi-chen

.agents/skills/missing_docs/SKILL.md

@@ -21,18 +21,23 @@ Find documentation gaps and draft missing pages in one workflow.
 Run the audit script to identify gaps:
 
 ```bash
-python3 .warp/skills/missing_docs/scripts/audit_docs.py
+python3 .agents/skills/missing_docs/scripts/audit_docs.py
 ```
 
 Options:
 - `--category features|cli|api|staleness` — run a single audit category
 - `--severity high|medium|low` — filter by minimum severity
+- `--weak-coverage` — also flag GA features whose mapped doc exists but doesn't mention feature keywords (low-severity, noisy)
 - `--output report.json` — save JSON report to file
 - `--warp-internal PATH` — explicit path to warp-internal (auto-detected from sibling dirs)
 - `--warp-server PATH` — explicit path to warp-server (auto-detected from sibling dirs)
 
+The script resolves doc paths from the docs repo root and accepts `.md` and `.mdx`
+interchangeably (and `README.md` ↔ `index.mdx`), so surface-map entries can use the
+canonical filename even when the on-disk extension differs.
+
 The script performs 4 audits:
-1. **Feature flag coverage** — compares GA flags in `warp_core/src/features.rs` + `app/Cargo.toml` against doc mentions
+1. **Feature flag coverage** — compares GA flags in `crates/warp_features/src/lib.rs` + `app/Cargo.toml` against the surface map; default mode trusts a mapped entry as verified, `--weak-coverage` additionally checks the target page mentions feature keywords
 2. **CLI command coverage** — compares `warp_cli/src/lib.rs` subcommands against `src/content/docs/reference/cli/`
 3. **API endpoint coverage** — compares `router/router.go` routes against `src/content/docs/reference/api-and-sdk/` and the OpenAPI spec
 4. **Docs staleness** — checks for outdated terminology in existing docs

.agents/skills/missing_docs/references/feature_surface_map.md

@@ -7,7 +7,7 @@ Format: `CodeIdentifier -> docs/path/to/page.md` (one per line within each secti
 Lines starting with `#` are comments. Blank lines are ignored.
 
 # Maintenance: when a new GA feature flag ships, add a mapping here.
-# Run `python3 .warp/skills/missing_docs/scripts/audit_docs.py` to find unmapped flags.
+# Run `python3 .agents/skills/missing_docs/scripts/audit_docs.py` to find unmapped flags.
 # This audit is also run as a recurring scheduled cloud agent to catch drift.
 
 ## Feature flags -> doc pages
@@ -130,7 +130,7 @@ AIContextMenuEnabled -> src/content/docs/agent-platform/local-agents/agent-conte
 AtMenuOutsideOfAIMode -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
 AIContextMenuCode -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
 DriveObjectsAsContext -> src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
-KittyKeyboardProtocol -> src/content/docs/terminal/more-features/full-screen-apps.md
+KittyKeyboardProtocol -> src/content/docs/terminal/more-features/full-screen-apps.mdx
 InlineRepoMenu -> src/content/docs/agent-platform/capabilities/codebase-context.mdx
 InlineHistoryMenu -> src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
 SkillArguments -> src/content/docs/agent-platform/capabilities/skills.mdx

.agents/skills/missing_docs/scripts/audit_docs.py

@@ -6,9 +6,10 @@
 warp-server to identify gaps. Produces a structured JSON report.
 
 Usage:
-    python3 .warp/skills/missing_docs/scripts/audit_docs.py
-    python3 .warp/skills/missing_docs/scripts/audit_docs.py --category features
-    python3 .warp/skills/missing_docs/scripts/audit_docs.py --output report.json
+    python3 .agents/skills/missing_docs/scripts/audit_docs.py
+    python3 .agents/skills/missing_docs/scripts/audit_docs.py --category features
+    python3 .agents/skills/missing_docs/scripts/audit_docs.py --output report.json
+    python3 .agents/skills/missing_docs/scripts/audit_docs.py --weak-coverage
 """
 
 import argparse
@@ -267,8 +268,16 @@ def snake_to_pascal(snake: str) -> str:
 
 
 def audit_features(warp_internal: Path, docs_root: Path, surface_map: dict,
-                   docs_text: dict[str, str]) -> list[dict]:
-    """Audit feature flag coverage in docs."""
+                   docs_text: dict[str, str],
+                   weak_coverage: bool = False) -> list[dict]:
+    """Audit feature flag coverage in docs.
+
+    By default, a flag is treated as covered if its mapped doc exists (the
+    surface map maintainer has verified the mapping). When ``weak_coverage``
+    is True, also verify that the target doc actually mentions feature
+    keywords — useful for catching pages that have been renamed or trimmed
+    so the flag is no longer documented in prose.
+    """
     flags = parse_feature_flags(warp_internal)
     default_features = parse_default_features(warp_internal)
     ignore_flags = surface_map.get("ignore_flags", set())
@@ -295,8 +304,34 @@ def audit_features(warp_internal: Path, docs_root: Path, surface_map: dict,
         # Check if mapped in surface map
         if flag in feature_to_doc:
             doc_path = feature_to_doc[flag]
-            if resolve_doc_path(doc_path, repo_root) is not None:
-                continue  # Mapped and doc exists — verified
+            resolved = resolve_doc_path(doc_path, repo_root)
+            if resolved is not None:
+                if not weak_coverage:
+                    # Surface-map presence is treated as verified — the
+                    # maintainer has confirmed the page covers this flag.
+                    continue
+                # Optional weak-coverage check: verify the target page
+                # actually mentions feature keywords. Skip the lowercase
+                # concatenated / snake_case variants since they rarely
+                # match human-written prose.
+                try:
+                    doc_content = resolved.read_text(encoding="utf-8").lower()
+                except Exception:
+                    doc_content = ""
+                terms = camel_to_search_terms(flag)
+                check_terms = [t for t in terms if " " in t or t.startswith("/")]
+                if check_terms and not any(t in doc_content for t in check_terms):
+                    findings.append({
+                        "flag": flag,
+                        "search_terms": terms,
+                        "severity": "low",
+                        "suggested_doc_path": doc_path,
+                        "reason": (
+                            f"Mapped doc {doc_path} exists but does not "
+                            "mention feature keywords (weak coverage)"
+                        ),
+                    })
+                continue
             # Mapped path missing — before flagging, fall back to a content
             # search so we don't raise false positives when a doc has merely
             # been moved.
@@ -698,6 +733,12 @@ def main():
         choices=["high", "medium", "low"],
         help="Filter results by minimum severity",
     )
+    parser.add_argument(
+        "--weak-coverage",
+        action="store_true",
+        help="Also flag features whose mapped doc exists but doesn't mention "
+             "feature keywords (noisy; produces low-severity findings)",
+    )
     args = parser.parse_args()
 
     # Find repos
@@ -737,7 +778,10 @@ def main():
         print(f"Using warp-internal: {warp_internal}", file=sys.stderr)
         if args.category in (None, "features"):
             print("Running feature flag coverage audit...", file=sys.stderr)
-            features_findings = audit_features(warp_internal, docs_root, surface_map, docs_text)
+            features_findings = audit_features(
+                warp_internal, docs_root, surface_map, docs_text,
+                weak_coverage=args.weak_coverage,
+            )
 
         if args.category in (None, "cli"):
             print("Running CLI command coverage audit...", file=sys.stderr)

src/content/docs/terminal/more-features/full-screen-apps.mdx

@@ -53,3 +53,16 @@ Some full-screen applications don't behave well when resizing. If you are experi
 ![alt-screen padding setting](../../../../assets/terminal/padding-settings.png)
 <figcaption>The alt-screen padding setting in appearance preferences.</figcaption>
 </figure>
+
+## Kitty keyboard protocol
+
+Warp supports the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) (CSI u progressive enhancement) so full-screen apps can read keystrokes that legacy terminal escape sequences can't represent — for example, distinguishing `Ctrl+I` from `Tab`, capturing modifier-only key events, or detecting key release events.
+
+When a running app advertises that it supports the protocol, Warp emits the extended escape sequences automatically. No configuration is required.
+
+* **Supported in**: Vim, Neovim, Emacs, tmux, helix, and other modern TUI apps that opt into CSI u.
+* **Falls back to legacy encoding** when the running app doesn't request progressive enhancement, so older programs keep working unchanged.
+
+:::note
+If a TUI app reports unexpected key events after upgrading Warp, confirm the app itself supports the Kitty keyboard protocol. Most apps require an explicit opt-in (for example, `:set keyprotocol` in Neovim).
+:::