From 2cf61b0590d06786c867798c67ade4181edfb939 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Mon, 17 Aug 2026 20:55:36 -0400 Subject: [PATCH] docs: author the sub-category taxonomy and C0 explanation --- .../01-c1-command-shadows.md | 32 +++++++++++++++++++ .../02-c2-startup-side-effects.md | 25 +++++++++++++++ .../03-c3-key-and-environment-overrides.md | 20 ++++++++++++ .../04-c4-terminal-and-tool-integration.md | 25 +++++++++++++++ .../05-c5-logging-and-capture.md | 19 +++++++++++ .../06-c6-greeting-and-first-run-ui.md | 13 ++++++++ docs/manual/08-components-reference/index.md | 11 +++++++ 7 files changed, 145 insertions(+) diff --git a/docs/manual/08-components-reference/01-c1-command-shadows.md b/docs/manual/08-components-reference/01-c1-command-shadows.md index c316630..eb3b5fb 100644 --- a/docs/manual/08-components-reference/01-c1-command-shadows.md +++ b/docs/manual/08-components-reference/01-c1-command-shadows.md @@ -31,3 +31,35 @@ all of these commands. When C1 is disabled, `rm` uses bare `command rm` with no wrapper — files are permanently deleted, not trashed. There is no intermediate safety net. +## Sub-categories + +`__fish_config_op_aliases` sub-divides into six sub-categories, each with +its own `__fish_config_op_aliases_` toggle: + +## filesystem + +`ls`, `cat`, `cd`, `du`, `mkdir`, `rm`, `mv`, and `cd`/zoxide navigation -- +the everyday filesystem-inspection and -modification shadows. + +## search + +`rg`, with its Kitty hyperlink formatting. + +## network + +`ping`, `ssh`, and `yt-dlp` -- shadows that talk to the network. + +## monitor + +`top` -> `btop`. + +## shell-tools + +`bash` (XDG bashrc + `$SHELL` reset), `less` (`$PAGER` fallback chain), +and the `help config` interception. + +## dev-tools + +`claude` (AGENTS.md/CLAUDE.md auto-linking) and `edit` (multi-editor +launcher), plus `agy`. + diff --git a/docs/manual/08-components-reference/02-c2-startup-side-effects.md b/docs/manual/08-components-reference/02-c2-startup-side-effects.md index e2f0eb5..e9c8b49 100644 --- a/docs/manual/08-components-reference/02-c2-startup-side-effects.md +++ b/docs/manual/08-components-reference/02-c2-startup-side-effects.md @@ -43,3 +43,28 @@ branches, or repos without a remote. The handler fires once per repo entry (not on every sub-directory `cd`). The registry is machine-local at `$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed. +## Sub-categories + +`__fish_config_op_autoexec` sub-divides into five sub-categories, each +with its own `__fish_config_op_autoexec_` toggle: + +## plugin-management + +Fisher bootstrap on first run. + +## pkg-wrappers + +`paru`/`yay` wrapper generation. + +## venv + +Automatic Python virtualenv activation. + +## telemetry + +The WakaTime hook's startup bootstrap. + +## sync + +Auto-pull background fast-forward, and the user-dots convenience symlink. + diff --git a/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md b/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md index 79addf0..9e7102f 100644 --- a/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md +++ b/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md @@ -33,3 +33,23 @@ When C3 is disabled, `exit` falls back to `builtin exit` with no scrollback capture, no Kitty IPC, and no file I/O on exit. The scrollback capture block is independently controlled by C5 (see below). +## Sub-categories + +`__fish_config_op_overrides` sub-divides into three sub-categories, each +with its own `__fish_config_op_overrides_` toggle: + +## key-bindings + +Vi mode, autopair, puffer key intercepts, bang-bang history expansion, +and `smart_exit`'s plain-exit path. + +## environment + +`$PATH`, `$PAGER`/`$EDITOR`/`$GPG_TTY`, and `$CDPATH`. + +## prompt + +Starship, the right prompt, Catppuccin syntax/prompt colors, and FZF +theming (`$FZF_DEFAULT_OPTS`) -- all driven by the same guard as a single +unit, not independently toggleable from each other. + diff --git a/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md b/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md index 0219051..952df73 100644 --- a/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md +++ b/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md @@ -22,3 +22,28 @@ Disabled integration commands (`spwin`, `tab`, `split`, `hist`, `logs`, `upgrade a colored error to stderr naming the variable that disabled them rather than silently failing. +## Sub-categories + +`__fish_config_op_integrations` sub-divides into five sub-categories, +each with its own `__fish_config_op_integrations_` toggle: + +## terminal-abbrs + +The Kitty/WezTerm abbreviation set. + +## window-mgmt + +`spwin`, `tab`, `split`. + +## notifications + +`done`'s completion notifications, and the WakaTime activity hook. + +## history-logs + +`hist`, `logs`. + +## pkg-upgrade + +`upgrade`. + diff --git a/docs/manual/08-components-reference/05-c5-logging-and-capture.md b/docs/manual/08-components-reference/05-c5-logging-and-capture.md index a9f52e4..4867c1e 100644 --- a/docs/manual/08-components-reference/05-c5-logging-and-capture.md +++ b/docs/manual/08-components-reference/05-c5-logging-and-capture.md @@ -112,3 +112,22 @@ Note: C3 and C5 compose independently. C3 controls whether the smart_exit wrapper is active at all; C5 controls only the scrollback-capture block inside it. With C3 disabled, exit is plain builtin exit regardless of C5. +## Sub-categories + +`__fish_config_op_logging` sub-divides into three sub-categories, each +with its own `__fish_config_op_logging_` toggle (all still opt-in +by default, inherited from C5's own opt-in behavior -- see §3 of the +design spec): + +## terminal-capture + +Kitty watcher scrollback capture, and `smart_exit`'s logging-guard path. + +## multiplexer-capture + +tmux `pipe-pane` and zellij `dump-screen` capture. + +## pkg-logs + +`paru`/`yay` AUR log wrappers. + diff --git a/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md b/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md index 699e721..39b33f3 100644 --- a/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md +++ b/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md @@ -13,3 +13,16 @@ When C6 is disabled, no greeting is printed by this config. Any greeting set by the distro or other configs runs normally — this config simply does not override it. +## Sub-categories + +`__fish_config_op_greeting` sub-divides into two sub-categories, each +with its own `__fish_config_op_greeting_` toggle: + +## first-run + +The first-run welcome banner. + +## greeting-message + +The per-session `fish_greeting` override. + diff --git a/docs/manual/08-components-reference/index.md b/docs/manual/08-components-reference/index.md index 8e8fc9f..44969b1 100644 --- a/docs/manual/08-components-reference/index.md +++ b/docs/manual/08-components-reference/index.md @@ -18,3 +18,14 @@ category variable. C4 [Integrations](/08-components-reference/04-c4-terminal-and-tool-integration/) — Kitty/Wezterm integrations, starship hooks, fzf theme C5 [Logging and Capture](/08-components-reference/05-c5-logging-and-capture/) — Session logs, command duration C6 [Greeting & First-Run UI](/08-components-reference/06-c6-greeting-and-first-run-ui/) — Custom startup banner + +## Per-function overrides: `C0`/`always` + +Every guarded function or file can also carry a reserved `always/on` or +`always/off` tag in its `# COMPONENT` header, independent of every C1-C6 +category and sub-category toggle and invisible to `config-settings`. An +`always/off` tag disables that function unconditionally; an `always/on` +tag enables it unconditionally, ignoring the state of every other tagged +sub-category. This is a per-function escape hatch for cases too granular +or too idiosyncratic to justify a taxonomy entry -- edit the header +directly and run `__fish_config_op_registry_rebuild` to apply the change.