From 9969f43ba36fc383421ff501578cda80aa57a99b Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Tue, 25 Aug 2026 01:28:18 -0400
Subject: [PATCH] fix(docs): reformat Prompt and Theme section and fix MDX
 code-block bug
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Verified every claim in the Prompt and Theme section against the actual
source and corrected several inaccuracies: the Starship wrapper's missing
C3 gate, the fallback prompt's vi-mode states and segment order, the FZF
theme's real location (conf.d/theme.fish, not integrations/fzf.fish) and
color set, and the Catppuccin theme-switch example using the wrong
fish_config subcommand (choose, not save). The right-prompt Docker-context
example was rewritten to show that it's independent of exit status.

While reformatting, found that any block build-manual.py couldn't classify
as shell/table/tree fell back to plain 4-space markdown indentation, which
silently renders as squashed, unreadable paragraph text on any page that
also contains an <Aside> or <FileTree> — MDX has no indented-code-block
syntax, unlike plain Markdown. This affected 07-customization.mdx plus four
other pages. Fixed the fallback to emit a fenced ```text block instead,
since fences work in both MDX and plain Markdown; this also gives every
affected block Starlight's normal code-block styling instead of a bare grey
slab.

docs/fish-config.md is intentionally left stale here — CI regenerates and
auto-commits it from docs/manual/** on push to main.
---
 docs/build-manual.py            |  10 +++-
 docs/manual/07-customization.md | 100 ++++++++++++++++++++++----------
 docs/verify-manual.py           |  29 ++++++++-
 3 files changed, 104 insertions(+), 35 deletions(-)

diff --git a/docs/build-manual.py b/docs/build-manual.py
index 5f1227d..524bba2 100644
--- a/docs/build-manual.py
+++ b/docs/build-manual.py
@@ -189,7 +189,7 @@ SHELL_HEADS = frozenset(
     if jobs kitty ls man math mkdir mv nvim npm pacman paru pip pip3 pkg printf
     python python3 rm set shutdown source string sudo switch systemctl test time
     tmux touch trash type wget wezterm while yay zellij zypper
-    fish_default_key_bindings fish_vi_key_bindings
+    fish_default_key_bindings fish_vi_key_bindings fish_config
     """.split()
 )
 
@@ -394,7 +394,13 @@ def _render_para(para: list[str], entry_name: str | None, deeper: bool) -> str:
     table = _as_ruled_table(para) or _as_table(para) or _as_file_tree(para)
     if table is not None:
         return table
-    return "\n".join(INDENT + line for line in para)
+    # MDX (used for any page that also carries an <Aside> or <FileTree>)
+    # has no indented-code-block syntax — a plain 4-space-indented block
+    # silently renders as flowed paragraph text there, collapsing every
+    # line break. A fenced block works in both MDX and plain Markdown, so
+    # it's the only fallback that's safe regardless of which one a given
+    # page ends up promoted to.
+    return "```text\n" + "\n".join(para) + "\n```"
 
 
 def _prettify_block(block: list[str], entry_name: str | None) -> str:
diff --git a/docs/manual/07-customization.md b/docs/manual/07-customization.md
index 81f2049..abfd609 100644
--- a/docs/manual/07-customization.md
+++ b/docs/manual/07-customization.md
@@ -167,11 +167,14 @@ The primary prompt is Starship, initialized by conf.d/starship.fish.
 Configure it via ~/.config/starship.toml.
 
 conf.d/starship.fish defines a fish_prompt wrapper that only activates when
-starship is in PATH. It emits OSC 133;A (prompt start) immediately before
-Starship renders and OSC 133;B (input start) immediately after, placing both
-markers on the prompt line itself. This allows ov to use them as sticky
-section headers when browsing scrollback logs. Without Starship, fish's
-built-in prompt handles these markers automatically.
+starship is in PATH and C3 overrides are enabled (see Opinionated
+Components above). It emits OSC 133;A (prompt start) immediately before
+Starship renders and OSC 133;B (input start) immediately after, placing
+both markers on the prompt line itself. This allows ov to use them as
+sticky section headers when browsing scrollback logs. It also prints a
+blank line before the prompt, skipped in private mode or on a freshly
+cleared screen. Without Starship, fish's built-in prompt handles these
+markers automatically.
 
 ### Catppuccin Fallback Prompt
 
@@ -179,47 +182,84 @@ When Starship is absent or C3 overrides are disabled, a built-in nim-style
 two-line prompt activates from functions/fish_prompt.fish. No external
 dependencies — fish builtins only.
 
-Layout:
+Layout (a dim job line appears between the two rows for each running
+background job):
 
     ┬─[user@host:~/path] (main)
+    │ nvim notes.md
     ╰─>$
 
 Elements:
 
-    user        Yellow (Catppuccin Yellow); red if root
-    @host       Blue (local) or Teal (SSH)
-    ~/path      prompt_pwd abbreviation (Catppuccin Text)
-    (main)      Current git branch in Catppuccin Pink; omitted outside repos
-    ─[V:name]   Active Python venv basename; omitted when none
-    ─[N/I/R/V]  Vi-mode indicator when vi bindings are active
-    ┬─ / ╰─>    Connector lines: Catppuccin Green on success, Red on failure
+    Segment           Meaning
+    ────────────────────────────────────────────────────────────────
+    user              Yellow (Catppuccin Yellow); red if root
+    @host             Blue (local) or Teal (SSH)
+    ~/path            prompt_pwd abbreviation (Catppuccin Text)
+    ─[N/I/R/V/O]      Vi-mode indicator (Normal/Insert/Replace/Visual/Operator);
+                      shown only when vi or hybrid key bindings are active
+    ─[V:name]         Active Python venv basename; omitted when none
+    (main)            Current git branch in Catppuccin Pink, with ↑/↓
+                      upstream-tracking arrows when applicable;
+                      omitted outside repos
+    ┬─ / ╰─>          Connector lines: Catppuccin Green on success,
+                      Red on failure
 
-The right prompt (fish_right_prompt.fish) always renders, regardless of C3
-state. On failure it shows a red ✘ and the exit code; on success it shows
-only the dim timestamp. When starship is installed and C3 is enabled, the
-active Docker context is also shown (if non-default):
+The right prompt (fish_right_prompt.fish) always renders, independently of
+which left prompt is active:
 
-    ✘ 1   󰡨 myctx   Fri Jun 12 00:51:21 2026     ← failed, starship+C3 active
-    ✘ 1   Fri Jun 12 00:51:21 2026               ← failed, fallback prompt
-    Fri Jun 12 00:51:21 2026                     ← success (no ✘)
+    Segment           Shown when
+    ────────────────────────────────────────────────────────────────
+    ✘ <code>          The previous command exited non-zero (red)
+    󰡨 <context>       docker and starship are both installed, C3
+                      overrides are enabled, and the active Docker
+                      context is set and non-default
+    <timestamp>       Always (dim, Catppuccin Overlay0)
+
+The exit-status and Docker segments are independent — for example, right
+after a failing command with a non-default Docker context active:
+
+    ✘ 1  󰡨 myctx  Fri Jun 12 00:51:21 2026
+
+A successful command with the same Docker context shows the segment too:
+
+    󰡨 myctx  Fri Jun 12 00:51:21 2026
+
+And without Starship (or with C3 disabled, or Docker not installed), only
+the exit-status prefix and timestamp ever appear:
+
+    ✘ 1  Fri Jun 12 00:51:21 2026
 
 ### FZF
 
-FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in
-integrations/fzf.fish. The colors applied:
+FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS, set in
+conf.d/theme.fish (opinionated; disabled by `__fish_config_op_overrides`,
+see Opinionated Components above). The colors applied:
 
-    Background:   #1E1E2E (base)    #313244 (surface0)
-    Foreground:   #CDD6F4 (text)
-    Highlights:   #F38BA8 (red)     #CBA6F7 (mauve)    #B4BEFE (lavender)
+    Hex        Role                     Catppuccin name
+    ────────────────────────────────────────────────────────
+    #1E1E2E    Background               Base
+    #313244    Highlighted background   Surface0
+    #45475A    Selected background      Surface1
+    #CDD6F4    Foreground               Text
+    #F38BA8    Highlight / header       Red
+    #CBA6F7    Info / prompt            Mauve
+    #B4BEFE    Marker                   Lavender
+    #F5E0DC    Spinner / pointer        Rosewater
+    #6C7086    Border                   Overlay0
 
-To customize, override FZF_DEFAULT_OPTS in local.fish.
+To customize, override FZF_DEFAULT_OPTS in local.fish — it is sourced after
+conf.d/theme.fish on every session, so a `set -Ux FZF_DEFAULT_OPTS ...`
+there always wins.
 
 ### Catppuccin Mocha Syntax Highlighting
 
 The Catppuccin Mocha theme ships with this config in themes/ and is applied
-on first run via `conf.d/first_run.fish`. Colors are stored in fish_variables
-(universal). To switch variants, install a different theme from themes/:
+automatically on first run via `conf.d/first_run.fish` (gated by
+`__fish_config_op_autoexec`; see Opinionated Components above). Colors are
+stored in fish_variables (universal). Three other bundled variants are
+available in themes/ — Latte, Frappé, and Macchiato. To switch:
 
-    fish_config theme save "Catppuccin Latte"
+    fish_config theme choose "Catppuccin Latte"
 
-`---`
+---
diff --git a/docs/verify-manual.py b/docs/verify-manual.py
index 68806b7..29b6a9f 100644
--- a/docs/verify-manual.py
+++ b/docs/verify-manual.py
@@ -626,19 +626,42 @@ def test_as_ruled_table_rejects_ambiguous_columns():
 
 
 def test_prettify_leaves_reference_tables_alone():
-    """Column-aligned blocks are data, not shell, and must not be fenced."""
+    """Column-aligned blocks too small for a real table are data, not shell,
+    and must not get shell syntax highlighting — but they still need SOME
+    fence, since indentation alone doesn't survive MDX (see
+    test_prettify_fallback_fences_instead_of_indenting)."""
     import build_manual
 
     table = "    XDG_CONFIG_HOME    ~/.config\n    XDG_CACHE_HOME     ~/.cache"
-    assert "```" not in build_manual.prettify(table), "a reference table got fenced"
+    out = build_manual.prettify(table)
+    assert "```fish" not in out, f"a reference table got shell-highlighted:\n{out}"
+    assert "```text" in out, f"a reference table lost its fence:\n{out}"
 
     binds = "    n / nv / neovim    nvim\n    e                  edit"
-    assert "```" not in build_manual.prettify(binds), "an abbreviation table got fenced"
+    out = build_manual.prettify(binds)
+    assert "```fish" not in out, f"an abbreviation table got shell-highlighted:\n{out}"
+    assert "```text" in out, f"an abbreviation table lost its fence:\n{out}"
 
     shell = "    set -U __fish_user_dots_path /path/to/dots"
     assert "```fish" in build_manual.prettify(shell), "a shell block was not fenced"
 
 
+def test_prettify_fallback_fences_instead_of_indenting():
+    """The catch-all fallback must emit a fenced block, not bare indentation.
+
+    MDX (used for any page that also carries an <Aside> or <FileTree>) has
+    no indented-code-block syntax: a plain 4-space-indented block silently
+    renders as flowed paragraph text there, collapsing every line break. A
+    fenced block is the only fallback shape that's safe in both MDX and
+    plain Markdown.
+    """
+    import build_manual
+
+    para = ["✘ 1   Fri Jun 12 00:51:21 2026     ← failed"]
+    out = build_manual._render_para(para, None, False)
+    assert out == "```text\n" + para[0] + "\n```", f"unexpected fallback output:\n{out}"
+
+
 def test_prettify_titles_paths_and_commented_examples():
     """A bare file path or a leading '# in x.fish' comment become a title."""
     import build_manual