From daae3022a5b4d9adc638658e74f30c81aacf3008 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 26 May 2026 23:36:41 +0000 Subject: [PATCH] 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 Co-Authored-By: Oz --- .agents/skills/missing_docs/SKILL.md | 9 ++- .../references/feature_surface_map.md | 4 +- .../skills/missing_docs/scripts/audit_docs.py | 60 ++++++++++++++++--- .../more-features/full-screen-apps.mdx | 13 ++++ 4 files changed, 74 insertions(+), 12 deletions(-) diff --git a/.agents/skills/missing_docs/SKILL.md b/.agents/skills/missing_docs/SKILL.md index 7d457959..5d38bf5a 100644 --- a/.agents/skills/missing_docs/SKILL.md +++ b/.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 diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index 56c0ff48..8d149d76 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.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 diff --git a/.agents/skills/missing_docs/scripts/audit_docs.py b/.agents/skills/missing_docs/scripts/audit_docs.py index a11b1b00..020d88d6 100755 --- a/.agents/skills/missing_docs/scripts/audit_docs.py +++ b/.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) diff --git a/src/content/docs/terminal/more-features/full-screen-apps.mdx b/src/content/docs/terminal/more-features/full-screen-apps.mdx index eb3afeb7..3f5acdd2 100644 --- a/src/content/docs/terminal/more-features/full-screen-apps.mdx +++ b/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)
The alt-screen padding setting in appearance preferences.
+ +## 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). +:::