From 2ff553f7b6ac755919622c86a5119a53d4dd4463 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Tue, 16 Jun 2026 10:03:14 -0400
Subject: [PATCH] docs(kitty): document kitty-logging command and watcher
 reminder

---
 README.md           | 16 ++++++++++++++++
 docs/fish-config.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)

diff --git a/README.md b/README.md
index 735604a..126d115 100644
--- a/README.md
+++ b/README.md
@@ -93,6 +93,22 @@ Kitty watcher to skip capture via a sentinel file — no shell or terminal
 restart required. Logging is category **C5** in [Minimal Mode](#minimal-mode);
 `set -U __fish_config_opinionated 0` turns it off along with everything else.
 
+The Kitty scrollback capture is provided by a watcher script that fish-config can
+install and manage for you. Inside Kitty, if it isn't set up yet, you'll see a
+one-time-per-session reminder. Manage it with:
+
+| Command | Action |
+|---|---|
+| `kitty-logging install` | Copy the watcher into your Kitty config and wire it into `kitty.conf` |
+| `kitty-logging uninstall` | Remove the managed block and the watcher file |
+| `kitty-logging status` | Show whether it's wired, the watcher version, and C5 state |
+| `kitty-logging dismiss` | Stop the per-session reminder without installing |
+
+`install` adds a clearly-marked managed block to `kitty.conf` and comments out
+any conflicting `watcher` line. It affects **new** Kitty windows (existing
+windows keep their current watcher until restarted). Disabling C5 logging makes
+the watcher inert without uninstalling it.
+
 ---
 
 ## Documentation
diff --git a/docs/fish-config.md b/docs/fish-config.md
index dea563f..f9e77dc 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -64,6 +64,7 @@ The configuration is split across:
       first_run.fish          One-time init: Fisher bootstrap, theme, welcome
       key_bindings.fish       Custom key bindings and Vi mode
       logging-events.fish     C5 --on-variable event handlers; syncs logging state at startup
+      kitty-watcher-reminder.fish  C5 per-session reminder to set up the Kitty watcher
       paru-wrapper.fish       Auto-generates ~/.local/bin/paru logging wrapper
       puffer.fish             !! / !$ / ./ expansion (bundled from nickeb96/puffer-fish)
       tmux-logging.fish       C5 starts tmux pipe-pane capture when fish runs inside tmux
@@ -1385,6 +1386,29 @@ Add -i (interactive confirmation) to destructive commands:
     replay "source ~/.bashrc"
     replay "export FOO=bar"
 
+### kitty-logging
+
+    Synopsis:  kitty-logging [install|uninstall|status|dismiss] [-h]
+
+    Manages the Kitty scrollback watcher that powers C5 logging. Ships a
+    canonical, version-marked watcher and installs it into the Kitty config
+    directory, wiring it into kitty.conf through a sentinel-marked managed
+    block. Commenting out any conflicting watcher line avoids double-capture.
+
+    Commands:
+      install    Copy/refresh the watcher and add the managed block
+      uninstall  Remove the managed block and the watcher file
+      status     Show wiring, installed watcher version, and C5 state
+      dismiss    Stop the per-session setup reminder
+
+    Runtime capture stays governed by the C5 .logging_disabled sentinel, so
+    disabling __fish_config_op_logging makes the watcher inert without
+    uninstalling. Install affects new Kitty windows only.
+
+    Example:
+      kitty-logging install
+      kitty-logging status
+
 ### tmux-clean
 
     Synopsis:  tmux-clean
@@ -1733,6 +1757,13 @@ at exit, toggling __fish_config_op_logging takes effect on the next exit with
 no restart or sentinel coordination needed — the C5 guard is re-checked when
 the handler fires.
 
+The Kitty watcher is managed by the kitty-logging command: it installs a
+version-marked watcher (fish-config-watcher.py) into the Kitty config directory
+and wires it into kitty.conf via a managed block. Inside Kitty, a non-blocking
+per-session reminder points first-time users at `kitty-logging install` until
+they install or run `kitty-logging dismiss`. Install affects new Kitty windows
+only; runtime disable is still handled by the .logging_disabled sentinel.
+
 Logging coordination via sentinel file
 
 C5 uses a sentinel file to synchronize state between the shell and