From 5395841583125a3edf3c4efbe086c61c9c6ef30b Mon Sep 17 00:00:00 2001
From: Suppaseth Charoenkarnka <kengio@gmail.com>
Date: Thu, 28 May 2026 18:54:46 +0700
Subject: [PATCH 1/6] =?UTF-8?q?feat(cli):=203=20UX=20fixes=20=E2=80=94=20c?=
 =?UTF-8?q?ompact=20--help,=20silent=20plugin-update=20sub-output,=20--jso?=
 =?UTF-8?q?n=20minified=20(v3.2.15)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All from live testing of v3.2.14 / earlier turns:

A. --help compact-with-wrap (revert v3.2.12 next_line_help)
   - root Cli: drop `next_line_help = true` so commands + options render compactly again
   - For args carrying `[default]` + `[possible values]` (-o/--output, --mode, --harness on harness run / skill run), set `hide_default_value` + `hide_possible_values` and embed a manual `\n[default: …, possible values: …]` tail in the `help` string — desc inline, bracketed block wraps to indented next line
   - HarnessMode variant docs stripped back to a comment block (was forcing long-format Possible values block in clap's renderer)
   - v31_integration test `root_help_renders_long_format` renamed to `root_help_renders_compact_with_wrapped_defaults` with the new positive assertions

B. plugin update: silence orchestrator's per-step `▸` lines
   - New `vault_sync::run_silent` forces `progress_writer = Some(io::sink())`, killing both intro/outro frame AND per-step `▸ <label>` lines on TTY
   - `plugin_update::run` switches to `run_silent` so the framed `⚡  Plugin Update` header appears as the FIRST thing after the brand banner. The animated spinner is now the only progress signal during work — matches doctor/update
   - v3.2.13's `run_embedded` removed (no remaining caller; the in-between 'silenced banner but kept step lines' mode wasn't useful)

C. --json minified by default
   - resolve_output_mode: `--json` and `--output json` no longer auto-prettify on TTY
   - To get indented JSON: pass `--json --pretty` (or `--output json --pretty`)
   - Easier copy/paste of the structured response into scripts/curl; humans can still opt back into pretty
   - Tests in mode.rs split into mono+pretty pairs

Tests: 1284 passed; clippy clean; fmt clean.

NOT MERGED — user reviewing locally first.
---
 CHANGELOG.md                                  |  8 ++-
 Cargo.lock                                    |  8 +--
 Cargo.toml                                    |  2 +-
 crates/onebrain-cli/src/cli.rs                | 53 ++++++++++++-------
 .../onebrain-cli/src/commands/vault_sync.rs   | 32 ++++++++---
 crates/onebrain-cli/src/output/mode.rs        | 41 +++++++++++---
 crates/onebrain-cli/src/v31/plugin_update.rs  | 13 +++--
 crates/onebrain-cli/tests/v31_integration.rs  | 51 ++++++++++++------
 8 files changed, 145 insertions(+), 63 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b3ab6dc..bb95293 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,5 @@
 ---
-latest_version: 3.2.14
+latest_version: 3.2.15
 released: 2026-05-28
 ---
 
@@ -12,6 +12,12 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [3.2.15] — 2026-05-28 — `--help` compact-with-wrap · `plugin update` silent sub-output · `--json` minified by default
+
+- **Break: `--help` reverts to compact layout** (command + description on the same line) — v3.2.12's blanket `next_line_help = true` pushed every arg into long format, which user testing flagged as "ดูยาก" (hard to read). For args carrying `[default]` + `[possible values]` (`-o, --output`, `--mode`, `--harness` on `skill run` / `harness run`), the description still renders inline but the bracketed value block wraps to a new indented line below. Achieved by `hide_default_value = true` + `hide_possible_values = true` + a manual `\n[default: …, possible values: …]` tail on the `help` string.
+- **Polish: `onebrain plugin update` no longer leaks the orchestrator's per-step `▸ <label>` lines above its framed report.** v3.2.13's `vault_sync::run_embedded` silenced the intro/outro frame but kept the step lines; v3.2.15 routes through new `vault_sync::run_silent` which forces the progress reporter to `io::sink()`. The framed `⚡  Plugin Update` header now appears as the FIRST thing in the report (right after the brand banner), with the animated spinner as the only progress signal during work — matches `doctor`/`update`'s established UX. `run_embedded` (intro-only suppression) removed; no remaining caller wanted the in-between mode.
+- **Break: `--json` (and `--output json`) now emits MINIFIED single-line JSON.** Pre-3.2.15 auto-prettified the JSON when stdout was a TTY, which was convenient for humans glancing at a structured response interactively but made the "copy/paste into curl / a script" path noisier. To get indented JSON now, pass `--json --pretty` (or `--output json --pretty`) explicitly.
+
 ## [3.2.14] — 2026-05-28 — `plugin update` animated spinner pacing (doctor/update parity)
 
 - **Polish: `onebrain plugin update` now animates the three step rows with the same braille spinner + random 800–2000ms pacing that `doctor` and `onebrain update` use.** Each step paints `⠋ <label>` with the cycling spinner for the random dwell, then `\r`-clears and writes the resolved `✓ <label>  <detail>` row — so the framed report reads as live work instead of an instant flash. Animation gates on a real-colour stdout TTY AND respects `--quiet` (`should_animate(mode, stdout_is_tty, cli.quiet)`); pipes / CI / structured output / `--quiet` runs all fall through to the static `_to` path unchanged.
diff --git a/Cargo.lock b/Cargo.lock
index 8823bfb..d5835db 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1166,7 +1166,7 @@ checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
 [[package]]
 name = "onebrain-cache"
-version = "3.2.14"
+version = "3.2.15"
 dependencies = [
  "chrono",
  "onebrain-core",
@@ -1179,7 +1179,7 @@ dependencies = [
 
 [[package]]
 name = "onebrain-cli"
-version = "3.2.14"
+version = "3.2.15"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -1208,7 +1208,7 @@ dependencies = [
 
 [[package]]
 name = "onebrain-core"
-version = "3.2.14"
+version = "3.2.15"
 dependencies = [
  "chrono",
  "indexmap",
@@ -1224,7 +1224,7 @@ dependencies = [
 
 [[package]]
 name = "onebrain-fs"
-version = "3.2.14"
+version = "3.2.15"
 dependencies = [
  "chrono",
  "dirs",
diff --git a/Cargo.toml b/Cargo.toml
index afff63a..a895a7b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ default-members = ["crates/*"]
 resolver = "2"
 
 [workspace.package]
-version = "3.2.14"
+version = "3.2.15"
 edition = "2021"
 license = "AGPL-3.0-only"
 authors = ["OneBrain Contributors"]
diff --git a/crates/onebrain-cli/src/cli.rs b/crates/onebrain-cli/src/cli.rs
index cafb4e4..44c7ca1 100644
--- a/crates/onebrain-cli/src/cli.rs
+++ b/crates/onebrain-cli/src/cli.rs
@@ -13,7 +13,6 @@ use std::path::PathBuf;
     name = "onebrain",
     version,
     disable_help_subcommand = true,
-    next_line_help = true,
     propagate_version = true
 )]
 pub struct Cli {
@@ -26,14 +25,16 @@ pub struct Cli {
     #[arg(long, global = true, value_name = "PATH")]
     pub vault: Option<PathBuf>,
 
-    /// Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically.
     #[arg(
         short = 'o',
         long,
         global = true,
         default_value = "text",
         value_parser = ["text", "json", "yaml", "table", "tsv"],
-        value_name = "FMT"
+        value_name = "FMT",
+        hide_default_value = true,
+        hide_possible_values = true,
+        help = "Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically\n[default: text, possible values: text, json, yaml, table, tsv]"
     )]
     pub output: String,
 
@@ -507,13 +508,23 @@ pub enum HarnessVerb {
         vault_dir: Option<PathBuf>,
         /// The prompt to send. If omitted, the prompt is read from stdin.
         prompt: Option<String>,
-        /// Whether to inject the vault's OneBrain context before answering.
-        /// `with-context` loads CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, `ad-hoc`
-        /// skips (cwd=`$TMPDIR`, no vault flag).
-        #[arg(long, value_enum, default_value_t = HarnessMode::WithContext)]
+        #[arg(
+            long,
+            value_enum,
+            default_value_t = HarnessMode::WithContext,
+            hide_default_value = true,
+            hide_possible_values = true,
+            help = "Whether to inject the vault's OneBrain context before answering. `with-context` loads CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, `ad-hoc` skips (cwd=`$TMPDIR`, no vault flag)\n[default: with-context, possible values: with-context, ad-hoc]"
+        )]
         mode: HarnessMode,
-        /// AI runtime to run the prompt through (default: claude).
-        #[arg(long, value_enum, default_value_t = HarnessArg::Claude)]
+        #[arg(
+            long,
+            value_enum,
+            default_value_t = HarnessArg::Claude,
+            hide_default_value = true,
+            hide_possible_values = true,
+            help = "AI runtime to run the prompt through\n[default: claude, possible values: claude, gemini]"
+        )]
         harness: HarnessArg,
         /// Model passed through to the harness (`claude --model <m>` /
         /// `gemini -m <m>`). Omit to use the harness default.
@@ -542,17 +553,13 @@ pub enum HarnessVerb {
 #[derive(ValueEnum, Debug, Clone, Copy, PartialEq, Eq, Default)]
 #[value(rename_all = "kebab-case")]
 pub enum HarnessMode {
-    /// Pass `--add-dir <vault>` (claude) / `--include-directories <vault>`
-    /// (gemini) and run with `cwd = <vault>` so the harness loads OneBrain's
-    /// CLAUDE.md / INSTRUCTIONS.md / GEMINI.md — full project context.
-    /// Requires a vault (exit 78 if missing).
+    // Variant docs intentionally omitted so clap doesn't render a multi-line
+    // `Possible values:` block under `--mode <MODE>` — that block was the
+    // last thing forcing `harness run --help` into clap's "long" format. The
+    // semantics now live in (a) the help-string wrap on the `mode` arg above
+    // and (b) the enum-level rustdoc on `HarnessMode` for source readers.
     #[default]
     WithContext,
-    /// No `--add-dir` / `--include-directories` flag, and `cwd` is forced to
-    /// `$TMPDIR` so claude / gemini can't auto-walk-up from a vault subdir
-    /// and silently re-load OneBrain's `CLAUDE.md` / `GEMINI.md`. Answers the
-    /// raw prompt with no project context — vault not required. User-level
-    /// config (`~/.claude/CLAUDE.md`) still loads — that's separate.
     AdHoc,
 }
 
@@ -1075,8 +1082,14 @@ pub enum SkillVerb {
         /// scheduler's `run-skill` form. Equivalent to the positional `<NAME>`.
         #[arg(long = "skill", value_name = "NAME", conflicts_with = "name")]
         skill: Option<String>,
-        /// AI runtime to run the skill through (default: claude).
-        #[arg(long, value_enum, default_value_t = HarnessArg::Claude)]
+        #[arg(
+            long,
+            value_enum,
+            default_value_t = HarnessArg::Claude,
+            hide_default_value = true,
+            hide_possible_values = true,
+            help = "AI runtime to run the skill through\n[default: claude, possible values: claude, gemini]"
+        )]
         harness: HarnessArg,
         /// Model passed through to the harness (`claude --model <m>` /
         /// `gemini -m <m>`). Omit to use the harness default. A faster model
diff --git a/crates/onebrain-cli/src/commands/vault_sync.rs b/crates/onebrain-cli/src/commands/vault_sync.rs
index 0f9d152..aae1cad 100644
--- a/crates/onebrain-cli/src/commands/vault_sync.rs
+++ b/crates/onebrain-cli/src/commands/vault_sync.rs
@@ -27,22 +27,28 @@ use std::path::PathBuf;
 /// to occasionally duplicate one line than leave the user with a silent
 /// non-zero exit.
 pub fn run(vault_root_override: Option<PathBuf>, branch: Option<String>) -> Result<i32> {
-    run_with(vault_root_override, branch, false)
+    run_with(vault_root_override, branch, false, false)
 }
 
-/// Identical to [`run`] but sets `VaultSyncOptions::embedded = true`, which
-/// suppresses the orchestrator's "OneBrain Vault Sync" intro frame and
-/// `vault-sync: done` outro. Used by `onebrain plugin update`, which wraps the
-/// sub-op inside its own framed report — the orchestrator frame would just
-/// fight the parent frame for the user's eye.
-pub fn run_embedded(vault_root_override: Option<PathBuf>, branch: Option<String>) -> Result<i32> {
-    run_with(vault_root_override, branch, true)
+/// Same as [`run`] but suppresses the orchestrator's "OneBrain Vault Sync"
+/// intro/outro frame AND routes the per-step progress reporter to
+/// `io::sink()` — so neither the framed banner nor the per-step `▸ <label>`
+/// lines leak. Used by `onebrain plugin update` (v3.2.15+), which renders
+/// its own framed doctor-style report. The framed report's animated spinner
+/// is the only progress signal the user sees, matching `doctor`/`update`.
+///
+/// (v3.2.13 introduced `run_embedded` for the intro-only suppression; v3.2.15
+/// folded that into the silent path because no remaining caller wanted the
+/// in-between "embedded but with step lines" mode.)
+pub fn run_silent(vault_root_override: Option<PathBuf>, branch: Option<String>) -> Result<i32> {
+    run_with(vault_root_override, branch, true, true)
 }
 
 fn run_with(
     vault_root_override: Option<PathBuf>,
     branch: Option<String>,
     embedded: bool,
+    silent: bool,
 ) -> Result<i32> {
     // Bun v2.3.3 parity: optional positional `<vault_root>` lets the caller
     // supply the vault path directly (skipping the cwd walk-up). When absent,
@@ -65,11 +71,21 @@ fn run_with(
     // narrow — any other path is the caller's responsibility.
     refuse_dangerous_vault_path(&vault_root_path)?;
 
+    // `silent` overrides any TTY-vs-non-TTY heuristic: orchestrator routes
+    // `progress_writer = Some(io::sink())` through `PlainProgress`, which
+    // discards every step line. `embedded` is still threaded so the build
+    // chooses the correct progress impl when `silent = false`.
+    let progress_writer: Option<Box<dyn std::io::Write + Send>> = if silent {
+        Some(Box::new(std::io::sink()))
+    } else {
+        None
+    };
     let result = run_vault_sync(
         vault_root_path.as_path(),
         VaultSyncOptions {
             branch,
             embedded,
+            progress_writer,
             ..VaultSyncOptions::default()
         },
     );
diff --git a/crates/onebrain-cli/src/output/mode.rs b/crates/onebrain-cli/src/output/mode.rs
index 7cf5369..2f3fbf5 100644
--- a/crates/onebrain-cli/src/output/mode.rs
+++ b/crates/onebrain-cli/src/output/mode.rs
@@ -98,18 +98,20 @@ impl TtyInputs {
 /// precedence here is only relevant for the unit tests that feed flags
 /// directly without going through clap.
 pub fn resolve_output_mode(i: &TtyInputs) -> OutputMode {
+    // v3.2.15: `--json` (alone) emits minified single-line JSON regardless of
+    // TTY. Pre-3.2.15 auto-prettified on TTY which was convenient for humans
+    // glancing at a structured response interactively, but made the
+    // "copy/paste the response into curl / a script" path noisier than
+    // necessary. To get indented JSON now, pass `--json --pretty` explicitly.
+    // The `--output json` long form follows the same rule for parity.
     if i.json_shortcut {
-        return OutputMode::Json {
-            pretty: i.pretty || i.stdout_is_tty,
-        };
+        return OutputMode::Json { pretty: i.pretty };
     }
     if i.yaml_shortcut {
         return OutputMode::Yaml;
     }
     match i.output_flag.as_str() {
-        "json" => OutputMode::Json {
-            pretty: i.pretty || i.stdout_is_tty,
-        },
+        "json" => OutputMode::Json { pretty: i.pretty },
         "yaml" => OutputMode::Yaml,
         "table" => OutputMode::Table,
         "tsv" => OutputMode::Tsv,
@@ -270,9 +272,22 @@ mod tests {
     }
 
     #[test]
-    fn json_shortcut_picks_json_mode() {
+    fn json_shortcut_picks_json_mode_minified_by_default() {
+        // v3.2.15: `--json` alone is minified (single-line) so scripts can
+        // copy/paste the response without re-flattening. `--json --pretty`
+        // is the opt-in for indented output. Pre-3.2.15 auto-prettified on
+        // TTY, which made the copy/paste path noisier than necessary.
         let mut i = base();
         i.json_shortcut = true;
+        assert_eq!(resolve_output_mode(&i), OutputMode::Json { pretty: false });
+    }
+
+    #[test]
+    fn json_shortcut_with_pretty_flag_is_indented() {
+        // v3.2.15: explicit `--json --pretty` opts into indented JSON.
+        let mut i = base();
+        i.json_shortcut = true;
+        i.pretty = true;
         assert_eq!(resolve_output_mode(&i), OutputMode::Json { pretty: true });
     }
 
@@ -284,9 +299,19 @@ mod tests {
     }
 
     #[test]
-    fn output_flag_json_picks_json_mode() {
+    fn output_flag_json_picks_json_mode_minified_by_default() {
+        // v3.2.15 parity: `--output json` follows the same rule as the
+        // `--json` shortcut — minified unless `--pretty` is also set.
         let mut i = base();
         i.output_flag = "json".into();
+        assert_eq!(resolve_output_mode(&i), OutputMode::Json { pretty: false });
+    }
+
+    #[test]
+    fn output_flag_json_with_pretty_is_indented() {
+        let mut i = base();
+        i.output_flag = "json".into();
+        i.pretty = true;
         assert_eq!(resolve_output_mode(&i), OutputMode::Json { pretty: true });
     }
 
diff --git a/crates/onebrain-cli/src/v31/plugin_update.rs b/crates/onebrain-cli/src/v31/plugin_update.rs
index 4557cda..ecb9262 100644
--- a/crates/onebrain-cli/src/v31/plugin_update.rs
+++ b/crates/onebrain-cli/src/v31/plugin_update.rs
@@ -73,12 +73,15 @@ pub fn run(
     // 2. Sync plugin tarball — same backend as v3.0 `vault-sync`.
     //    v3.2.13: invoke via the embedded-progress entry so the orchestrator
     //    skips its "OneBrain Vault Sync" intro frame and "vault-sync: done"
-    //    outro — those are redundant under plugin update's own framed report
-    //    and were a key part of the "weird" mixed-styles UX the user flagged.
-    //    Step spinners still emit (they're transient) so the user sees
-    //    download/sync activity during a long fetch.
+    //    outro.
+    //    v3.2.15: ALSO route through `run_silent` so the per-step `▸ <label>`
+    //    TTY lines don't leak above the parent's framed report (user testing
+    //    on v3.2.14 flagged "ไม่มี header เลย" — the step lines appeared
+    //    BEFORE the parent's `⚡  Plugin Update` header). The framed report's
+    //    animated spinner is the only progress signal, matching what
+    //    `doctor`/`update` already do.
     if !dry_run {
-        let exit = crate::commands::vault_sync::run_embedded(Some(vault_root.clone()), branch)
+        let exit = crate::commands::vault_sync::run_silent(Some(vault_root.clone()), branch)
             .context("plugin update: vault-sync failed")?;
         // `vault_sync::run` returns Ok(0) on success, Ok(1) on critical fail.
         if exit != 0 {
diff --git a/crates/onebrain-cli/tests/v31_integration.rs b/crates/onebrain-cli/tests/v31_integration.rs
index 0e4dc81..b23c58a 100644
--- a/crates/onebrain-cli/tests/v31_integration.rs
+++ b/crates/onebrain-cli/tests/v31_integration.rs
@@ -67,29 +67,48 @@ fn root_help_shows_3_root_verbs_and_visible_groups() {
 }
 
 #[test]
-fn root_help_renders_long_format() {
-    // v3.2.12 introduces `next_line_help = true` on the root `Cli`, which
-    // makes every command and option render in clap's "long" format: name on
-    // its own line followed by an indented description. The other layout
-    // tests use OR-fallback patterns (`  init\n` OR `  init `) so a clap
-    // renderer drift or an accidental removal of the attribute doesn't break
-    // ordering/visibility invariants — but those fallbacks would silently
-    // absorb a regression of the long format itself. THIS test positively
-    // asserts the shipped shape so any reversion fails loudly.
+fn root_help_renders_compact_with_wrapped_defaults() {
+    // v3.2.15 reverts the v3.2.12 `next_line_help = true` blanket — that
+    // attribute pushed EVERY arg into long format (name on its own line) and
+    // made `--help` read as "ดูยาก" per user testing. The new shape:
+    //   - Commands: compact (`  init        Initialize a new vault`)
+    //   - Options without defaults: compact
+    //   - Options WITH `[default]` + `[possible values]`: description still
+    //     inline, the bracketed value block wraps to a new line indented to
+    //     the description column.
+    //
+    // This positive assertion pins the new layout so a re-introduction of
+    // `next_line_help = true` (or removal of the `hide_default_value` /
+    // `hide_possible_values` + manual help-string wrap on `--output`) fails
+    // loudly.
     let out = Command::cargo_bin("onebrain")
         .unwrap()
         .arg("--help")
         .assert()
         .success();
     let stdout = String::from_utf8_lossy(&out.get_output().stdout).to_string();
-    // The exact indent depth (10 spaces) is what clap 4.x renders for
-    // next-line-help children; the substring below tolerates trailing
-    // description content drift but pins the layout itself.
+    // Commands compact — `  init        Initialize...` on one line.
+    assert!(
+        stdout.contains("  init        Initialize a new vault"),
+        "expected compact command row `  init        Initialize a new vault`; \
+         `next_line_help = true` may have crept back. Got:\n{stdout}"
+    );
+    // `-o, --output` description on the same line; `[default: text, \
+    // possible values: ...]` wrapped to a new aligned line below.
     assert!(
-        stdout.contains("  init\n          Initialize a new vault"),
-        "expected long-format `--help` (verb on its own line, description \
-         indented on the next). Either `next_line_help = true` was removed \
-         from `Cli`, or clap's renderer changed the indent shape. Got:\n{stdout}"
+        stdout.contains(
+            "  -o, --output <FMT>  Output format. Default `text` is TTY-friendly; \
+             pipe-detected calls drop color/pretty automatically\n\
+                                  [default: text, possible values: text, json, yaml, table, tsv]"
+                .replace("             ", "")
+                .as_str()
+        ) || stdout.contains(
+            "  -o, --output <FMT>  Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically\n                      [default: text, possible values: text, json, yaml, table, tsv]"
+        ),
+        "expected `-o, --output` description inline with `[default: text, \
+         possible values: ...]` wrapped to indented next line. The \
+         `hide_default_value` / `hide_possible_values` + manual help-string \
+         wrap on `Cli::output` may have been removed. Got:\n{stdout}"
     );
 }
 

From 723b24514eada4dda4c6a80b6cac476ee56abeb9 Mon Sep 17 00:00:00 2001
From: Suppaseth Charoenkarnka <kengio@gmail.com>
Date: Thu, 28 May 2026 20:25:45 +0700
Subject: [PATCH 2/6] feat(plugin update): version tracking + flag-per-line in
 --help + per-command emoji (v3.2.15 round 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three more UX fixes from this turn's live testing (rolled into the v3.2.15
PR per user request 'ทำรวมใน PR เดียวกัน'):

D. Per-command emoji — pre-3.2.15 both doctor and update used 🧠 (same as
   the OneBrain wordmark banner). v3.2.15: doctor → 🔬, update → 🚀,
   plugin update → 🔄.

E. skill/harness --help flag-per-line — the run subcommand's description
   in those help screens was a dense dot-separated single-line summary.
   Now uses #[command(about = ...\n...)] so each --flag lands on its
   own indented line.

F. plugin update version tracking — captures
   .claude-plugin/plugin.json::version BEFORE + AFTER vault-sync.
   Surfaces the delta in:
     - vault-sync step row: vX → vY / vX · up-to-date / installed vY /
       current vY · skipped (dry-run)
     - verdict footer: updated vX → vY / update complete · vY /
       already up-to-date · vY / dry-run · current vY
     - JSON envelope: version_before / version_after (additive)

Implementation: shared helpers plugin_update_vault_detail +
plugin_update_verdict_text in dispatch.rs so the static and animated
renderers stay in sync.

1284 passed; clippy clean; fmt clean. NOT MERGED — user testing locally.
---
 CHANGELOG.md                                  |   7 +-
 crates/onebrain-cli/src/cli.rs                |  33 ++-
 crates/onebrain-cli/src/commands/doctor.rs    |  10 +-
 ...rouped_report_snapshot_mixed_statuses.snap |   2 +-
 crates/onebrain-cli/src/commands/update.rs    |  21 +-
 crates/onebrain-cli/src/output/progress.rs    |   4 +-
 crates/onebrain-cli/src/v31/dispatch.rs       | 200 ++++++++++++++----
 crates/onebrain-cli/src/v31/plugin_update.rs  |  53 ++++-
 8 files changed, 261 insertions(+), 69 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bb95293..9a03775 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,10 +12,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
-## [3.2.15] — 2026-05-28 — `--help` compact-with-wrap · `plugin update` silent sub-output · `--json` minified by default
+## [3.2.15] — 2026-05-28 — `--help` compact-with-wrap · plugin update polish · per-command emoji · version tracking · `--json` minified
 
 - **Break: `--help` reverts to compact layout** (command + description on the same line) — v3.2.12's blanket `next_line_help = true` pushed every arg into long format, which user testing flagged as "ดูยาก" (hard to read). For args carrying `[default]` + `[possible values]` (`-o, --output`, `--mode`, `--harness` on `skill run` / `harness run`), the description still renders inline but the bracketed value block wraps to a new indented line below. Achieved by `hide_default_value = true` + `hide_possible_values = true` + a manual `\n[default: …, possible values: …]` tail on the `help` string.
-- **Polish: `onebrain plugin update` no longer leaks the orchestrator's per-step `▸ <label>` lines above its framed report.** v3.2.13's `vault_sync::run_embedded` silenced the intro/outro frame but kept the step lines; v3.2.15 routes through new `vault_sync::run_silent` which forces the progress reporter to `io::sink()`. The framed `⚡  Plugin Update` header now appears as the FIRST thing in the report (right after the brand banner), with the animated spinner as the only progress signal during work — matches `doctor`/`update`'s established UX. `run_embedded` (intro-only suppression) removed; no remaining caller wanted the in-between mode.
+- **Polish: `skill --help` / `harness --help` now lay out each flag in the `run` subcommand's description on its own indented line** instead of one dense dot-separated single-line summary that ran past the terminal width. Achieved via explicit `\n` in the `#[command(about = "…")]` override on `SkillVerb::Run` / `HarnessVerb::Run`.
+- **Polish: per-command framed-header emoji differentiated.** Pre-3.2.15 both `doctor` and `update` used 🧠 (same as the OneBrain wordmark banner above them); v3.2.15: `doctor` → 🔬, `update` → 🚀, `plugin update` → 🔄. Each command now reads at a glance and stops competing with the brand glyph.
+- **Polish: `onebrain plugin update` no longer leaks the orchestrator's per-step `▸ <label>` lines above its framed report.** v3.2.13's `vault_sync::run_embedded` silenced the intro/outro frame but kept the step lines; v3.2.15 routes through new `vault_sync::run_silent` which forces the progress reporter to `io::sink()`. The framed `🔄  Plugin Update` header now appears as the FIRST thing in the report (right after the brand banner), with the animated spinner as the only progress signal during work — matches `doctor`/`update`'s established UX. `run_embedded` (intro-only suppression) removed; no remaining caller wanted the in-between mode.
+- **Feat: `plugin update` now reports current + latest plugin version explicitly.** The vault-sync step row reads `vX → vY` (real update), `vX · up-to-date` (rerun on the same version), or `installed vY` (fresh install) instead of the pre-3.2.15 collapse to `done` / `skipped`. The verdict footer also surfaces the delta — `updated v3.1.3 → v3.1.4` for a real bump, `update complete · v3.1.4` for no-version-change work, `already up-to-date · v3.1.4` for idempotent reruns, and `dry-run · current v3.1.4` for `--dry-run`. JSON envelope gains `version_before` / `version_after` fields (additive — both `#[serde(skip_serializing_if = "Option::is_none")]`).
 - **Break: `--json` (and `--output json`) now emits MINIFIED single-line JSON.** Pre-3.2.15 auto-prettified the JSON when stdout was a TTY, which was convenient for humans glancing at a structured response interactively but made the "copy/paste into curl / a script" path noisier. To get indented JSON now, pass `--json --pretty` (or `--output json --pretty`) explicitly.
 
 ## [3.2.14] — 2026-05-28 — `plugin update` animated spinner pacing (doctor/update parity)
diff --git a/crates/onebrain-cli/src/cli.rs b/crates/onebrain-cli/src/cli.rs
index 44c7ca1..2faafbe 100644
--- a/crates/onebrain-cli/src/cli.rs
+++ b/crates/onebrain-cli/src/cli.rs
@@ -496,11 +496,18 @@ pub struct HarnessCmd {
 pub enum HarnessVerb {
     /// Detect the active harness (Claude Code / Gemini / direct).
     Detect,
-    /// Run a prompt through claude or gemini headlessly. Flags:
-    /// `--harness {claude,gemini}` · `--model <m>` (e.g. `claude-haiku-4-5`,
-    /// `gemini-2.5-flash`) · `--mode {with-context, ad-hoc}` — with-context
-    /// (default) loads vault CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, ad-hoc skips
-    /// project context. Omit `<PROMPT>` to read from stdin (`cat note.md | …`).
+    // v3.2.15: use `#[command(about = "...")]` with explicit `\n` so each
+    // flag in the inline summary lands on its own indented line under
+    // `harness --help`'s Commands: list (per user testing — the dot-separated
+    // single-line form was too dense to scan). The hidden `long_about` keeps
+    // the same content for `harness run --help` (clap derives both from
+    // `about` when `long_about` is unset).
+    #[command(about = "Run a prompt through claude or gemini headlessly.\n\
+        Flags:\n  \
+          --harness {claude,gemini}\n  \
+          --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
+          --mode {with-context, ad-hoc} — with-context (default) loads vault CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, ad-hoc skips project context\n\
+        Omit <PROMPT> to read from stdin (`cat note.md | …`).")]
     Run {
         /// Vault root override · also accepts global `--vault`, and walks up from cwd when omitted.
         /// Ignored when `--mode ad-hoc`.
@@ -1067,10 +1074,18 @@ pub enum SkillVerb {
     /// List installed skills (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
     List,
-    /// Run a OneBrain skill (`/onebrain:<name>`) in headless mode. Flags:
-    /// `--harness {claude,gemini}` · `--model <m>` (e.g. `claude-haiku-4-5`,
-    /// `gemini-2.5-flash`) · `--skill <name>` (parity alias for the positional
-    /// `<NAME>`) · `--arg key=value` (pass-through). Replaces v3.0 `run-skill`.
+    // v3.2.15: same flag-per-line treatment as `HarnessVerb::Run` — per user
+    // testing the dot-separated single-line form was too dense to scan under
+    // `skill --help`.
+    #[command(
+        about = "Run a OneBrain skill (`/onebrain:<name>`) in headless mode.\n\
+        Flags:\n  \
+          --harness {claude,gemini}\n  \
+          --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
+          --skill <name> (parity alias for the positional <NAME>)\n  \
+          --arg key=value (pass-through)\n\
+        Replaces v3.0 `run-skill`."
+    )]
     Run {
         /// Vault root override · also accepts global `--vault`, and walks up from cwd when omitted.
         #[arg(long = "vault-dir", value_name = "PATH", hide = true)]
diff --git a/crates/onebrain-cli/src/commands/doctor.rs b/crates/onebrain-cli/src/commands/doctor.rs
index 955aa61..1098728 100644
--- a/crates/onebrain-cli/src/commands/doctor.rs
+++ b/crates/onebrain-cli/src/commands/doctor.rs
@@ -1296,7 +1296,7 @@ fn render_grouped_report<W: Write>(
     // via the shared framed-header helper that `update` also uses.
     write_framed_header(
         &mut w,
-        "🧠",
+        "🔬",
         &format!("OneBrain Doctor · {vault_name}"),
         color,
         rule_width,
@@ -1319,7 +1319,7 @@ fn render_grouped_report<W: Write>(
 /// headers, check lines, hint `└` lines) and the header title, clamped to a
 /// [`RULE_WIDTH`] floor. Measured by rendering the body uncoloured to a buffer
 /// so ANSI escapes don't inflate the count; the body's glyphs (`✓ ⚠ ✗ └ ─`)
-/// are single-column, so a `char` count equals the display width. The 🧠 in the
+/// are single-column, so a `char` count equals the display width. The 🔬 in the
 /// header title renders as two columns, accounted for explicitly.
 fn doctor_rule_width(results: &[DoctorResult], vault_name: &str) -> usize {
     use crate::output::ProgressRenderer;
@@ -1336,7 +1336,7 @@ fn doctor_rule_width(results: &[DoctorResult], vault_name: &str) -> usize {
         .map(|l| l.chars().count())
         .max()
         .unwrap_or(0);
-    // Header line is ` 🧠  <title>`: 1 lead space + 2 emoji columns + 2 spaces.
+    // Header line is ` 🔬  <title>`: 1 lead space + 2 emoji columns + 2 spaces.
     let header_cols = 5 + format!("OneBrain Doctor · {vault_name}").chars().count();
     body_max.max(header_cols).max(RULE_WIDTH)
 }
@@ -1476,9 +1476,9 @@ mod tests {
     fn static_report_shows_header_section_labels_and_glyphs() {
         let out = render_static_report(&nine_check_results(), false);
         // Doctor's own header (distinct from the brand banner). Two spaces
-        // after the wide 🧠 glyph so the title doesn't butt against it.
+        // after the wide 🔬 glyph so the title doesn't butt against it.
         assert!(
-            out.contains("🧠  OneBrain Doctor · ob-1"),
+            out.contains("🔬  OneBrain Doctor · ob-1"),
             "header: {out:?}"
         );
         // Section headers.
diff --git a/crates/onebrain-cli/src/commands/snapshots/onebrain__commands__doctor__tests__grouped_report_snapshot_mixed_statuses.snap b/crates/onebrain-cli/src/commands/snapshots/onebrain__commands__doctor__tests__grouped_report_snapshot_mixed_statuses.snap
index 1634e01..eb3946d 100644
--- a/crates/onebrain-cli/src/commands/snapshots/onebrain__commands__doctor__tests__grouped_report_snapshot_mixed_statuses.snap
+++ b/crates/onebrain-cli/src/commands/snapshots/onebrain__commands__doctor__tests__grouped_report_snapshot_mixed_statuses.snap
@@ -3,7 +3,7 @@ source: crates/onebrain-cli/src/commands/doctor.rs
 expression: output
 ---
 ────────────────────────────────────────────────────────
- 🧠  OneBrain Doctor · ob-1
+ 🔬  OneBrain Doctor · ob-1
 ────────────────────────────────────────────────────────
 
  Config
diff --git a/crates/onebrain-cli/src/commands/update.rs b/crates/onebrain-cli/src/commands/update.rs
index 6f49017..26405c1 100644
--- a/crates/onebrain-cli/src/commands/update.rs
+++ b/crates/onebrain-cli/src/commands/update.rs
@@ -90,7 +90,7 @@ pub fn run(check: bool, fresh: bool, json: bool, plan: bool, mode: &OutputMode)
     Ok(result.exit_code)
 }
 
-/// TTY-mode `UpdateOptions`: a framed 🧠 header, colorized phase lines, and a
+/// TTY-mode `UpdateOptions`: a framed 🚀 header, colorized phase lines, and a
 /// braille spinner (matching `doctor`) on the two phases that take time —
 /// `fetch` (the version check, padded to a deliberate beat so it reads as real
 /// work even on a warm cache) and `install` (the real download). The install
@@ -101,7 +101,7 @@ fn build_tty_options(dry_run: bool, fresh: bool) -> UpdateOptions {
     let pb_cell: Arc<Mutex<Option<ProgressBar>>> = Arc::new(Mutex::new(None));
 
     // stdout sink — replace the plain "OneBrain Update" title with the framed
-    // 🧠 header, color the well-known phase lines, and route everything via the
+    // 🚀 header, color the well-known phase lines, and route everything via the
     // install spinner's `println` when one is active so output doesn't trample.
     let pb_for_stdout = Arc::clone(&pb_cell);
     let stdout_sink: Box<dyn FnMut(&str) + Send> = Box::new(move |line: &str| {
@@ -193,13 +193,17 @@ fn braille_spinner(msg: impl Into<String>) -> ProgressBar {
     pb
 }
 
-/// The framed 🧠 update header (shared layout with `doctor`), rendered to a
+/// The framed 🚀 update header (shared layout with `doctor`), rendered to a
 /// string for the stdout sink. The TTY path always has colour on.
+/// v3.2.15: emoji set differentiated per command (was 🧠 — collided with
+/// `doctor`'s 🧠 AND with the brand wordmark banner). `🚀` reads as
+/// "self-update / take off / fast release" for the CLI's own bump path;
+/// `doctor` now uses `🔬` (lab), `plugin update` uses `🔄` (sync).
 fn framed_update_header() -> String {
     let mut buf = Vec::new();
     let _ = crate::output::write_framed_header(
         &mut buf,
-        "🧠",
+        "🚀",
         "OneBrain Update",
         true,
         crate::output::RULE_WIDTH,
@@ -332,10 +336,13 @@ mod tests {
 
     #[test]
     fn render_stdout_line_frames_the_title() {
-        // The "OneBrain Update" title becomes the framed 🧠 header (two spaces
-        // after the glyph, full-width rules) — same layout as doctor's header.
+        // The "OneBrain Update" title becomes the framed 🚀 header (two spaces
+        // after the glyph, full-width rules) — same layout as doctor's header
+        // (v3.2.15: doctor uses 🔬, update uses 🚀, plugin update uses 🔄 —
+        // each command gets its own distinct glyph instead of the previous
+        // shared 🧠 that doubled as the brand banner).
         let out = render_stdout_line("OneBrain Update");
-        assert!(out.contains("🧠  OneBrain Update"), "framed title: {out:?}");
+        assert!(out.contains("🚀  OneBrain Update"), "framed title: {out:?}");
         assert!(out.contains('─'), "framed rule: {out:?}");
     }
 
diff --git a/crates/onebrain-cli/src/output/progress.rs b/crates/onebrain-cli/src/output/progress.rs
index 35fd40b..03a361d 100644
--- a/crates/onebrain-cli/src/output/progress.rs
+++ b/crates/onebrain-cli/src/output/progress.rs
@@ -624,10 +624,10 @@ mod tests {
     #[test]
     fn framed_header_two_spaces_after_emoji_and_full_width_rules() {
         let mut buf = Vec::new();
-        write_framed_header(&mut buf, "🧠", "OneBrain Update", false, RULE_WIDTH).unwrap();
+        write_framed_header(&mut buf, "🚀", "OneBrain Update", false, RULE_WIDTH).unwrap();
         let out = String::from_utf8(buf).unwrap();
         assert!(
-            out.contains("🧠  OneBrain Update"),
+            out.contains("🚀  OneBrain Update"),
             "two spaces after emoji: {out:?}"
         );
         let lines: Vec<&str> = out.lines().collect();
diff --git a/crates/onebrain-cli/src/v31/dispatch.rs b/crates/onebrain-cli/src/v31/dispatch.rs
index e3c3e86..57fb0ef 100644
--- a/crates/onebrain-cli/src/v31/dispatch.rs
+++ b/crates/onebrain-cli/src/v31/dispatch.rs
@@ -627,7 +627,7 @@ pub(crate) fn render_plugin_update_animated_to<W: std::io::Write>(
     let reset = if color { "\x1b[0m" } else { "" };
 
     // ── Header (no animation — same as static path) ───────────────────
-    write_framed_header(&mut writer, "⚡", "Plugin Update", color, rule_width)?;
+    write_framed_header(&mut writer, "🔄", "Plugin Update", color, rule_width)?;
 
     // ── Step list (animated) ──────────────────────────────────────────
     // Same per-step Ok/Fail mapping as the static `render_plugin_update_text`
@@ -635,11 +635,13 @@ pub(crate) fn render_plugin_update_animated_to<W: std::io::Write>(
     // shows the braille spinner with its label for ~800–2000ms before the
     // `\r`-clear-and-resolve transition — matches `doctor`/`update`.
     let partial_failed = report.partial_failure.is_some();
-    let vault_detail = if report.vault_synced {
-        "done"
-    } else {
-        "skipped"
-    };
+    let vault_detail = plugin_update_vault_detail(
+        report.vault_synced,
+        report.dry_run,
+        partial_failed,
+        report.version_before.as_deref(),
+        report.version_after.as_deref(),
+    );
     let hooks_detail = format!("{} rewritten", report.hooks_rewritten);
     let plists_detail = if partial_failed {
         "failed".to_string()
@@ -691,19 +693,15 @@ pub(crate) fn render_plugin_update_animated_to<W: std::io::Write>(
     };
     let verdict_glyph = verdict_status.glyph();
     let verdict_prefix = verdict_status.ansi_prefix(color);
-    let verdict_text: &str = match (partial_failed, report.dry_run) {
-        (true, _) => "partial failure",
-        (false, true) => "dry-run · no changes written",
-        (false, false) => {
-            let any_change =
-                report.vault_synced || report.hooks_rewritten > 0 || report.plists_rewritten;
-            if any_change {
-                "update complete"
-            } else {
-                "already up-to-date"
-            }
-        }
-    };
+    let verdict_text = plugin_update_verdict_text(
+        partial_failed,
+        report.dry_run,
+        report.vault_synced,
+        report.hooks_rewritten,
+        report.plists_rewritten,
+        report.version_before.as_deref(),
+        report.version_after.as_deref(),
+    );
     let total_str = "3 steps";
     let left_cols = 1 + 1 + 2 + verdict_text.chars().count();
     let gap = rule_width
@@ -729,6 +727,87 @@ pub(crate) fn render_plugin_update_animated_to<W: std::io::Write>(
     Ok(())
 }
 
+/// Compose the `vault sync` step row's detail string from the captured
+/// version delta + run flags. Shared by both the static and animated
+/// renderers so a future tweak (e.g. trimming the `v` prefix) lands in
+/// exactly one place.
+///
+/// Decision table (v3.2.15):
+/// - partial-failed AND step ran  → version-aware `vX → vY` / `vX · up-to-date`
+///   / `installed vY` / fallback `done` (the plist step is what failed; the
+///   vault row tells the user what version it ended up on)
+/// - partial-failed AND step skipped → `skipped`
+/// - dry-run with known current → `current vX · skipped`
+/// - dry-run unknown → `skipped`
+/// - happy path with versions → `vX → vY` / `vX · up-to-date` / `installed vY`
+/// - happy path no version info → `done` (back-compat with pre-3.2.15)
+/// - step didn't run → `skipped`
+fn plugin_update_vault_detail(
+    vault_synced: bool,
+    dry_run: bool,
+    partial_failed: bool,
+    before: Option<&str>,
+    after: Option<&str>,
+) -> String {
+    if dry_run {
+        return match before {
+            Some(v) => format!("current v{v} · skipped"),
+            None => "skipped".to_string(),
+        };
+    }
+    if !vault_synced {
+        return "skipped".to_string();
+    }
+    // Vault step ran. Partial failure on a later step doesn't change what
+    // version landed on disk, so the row still reports the delta here.
+    let _ = partial_failed; // (kept in the signature for future per-step blame)
+    match (before, after) {
+        (Some(a), Some(b)) if a == b => format!("v{a} · up-to-date"),
+        (Some(a), Some(b)) => format!("v{a} → v{b}"),
+        (None, Some(b)) => format!("installed v{b}"),
+        _ => "done".to_string(),
+    }
+}
+
+/// Compose the verdict footer's right-hand text (e.g. `updated v3.1.3 → v3.1.4`,
+/// `already up-to-date · v3.1.4`). Mirrors the step-detail helper above with
+/// the verdict-summary phrasing.
+fn plugin_update_verdict_text(
+    partial_failed: bool,
+    dry_run: bool,
+    vault_synced: bool,
+    hooks_rewritten: u32,
+    plists_rewritten: bool,
+    before: Option<&str>,
+    after: Option<&str>,
+) -> String {
+    if partial_failed {
+        return "partial failure".to_string();
+    }
+    if dry_run {
+        return match before {
+            Some(v) => format!("dry-run · current v{v}"),
+            None => "dry-run · no changes written".to_string(),
+        };
+    }
+    // Real version bump trumps everything — that IS the headline outcome.
+    if let (Some(a), Some(b)) = (before, after) {
+        if a != b {
+            return format!("updated v{a} → v{b}");
+        }
+    }
+    let any_change = vault_synced || hooks_rewritten > 0 || plists_rewritten;
+    let suffix = after
+        .or(before)
+        .map(|v| format!(" · v{v}"))
+        .unwrap_or_default();
+    if any_change {
+        format!("update complete{suffix}")
+    } else {
+        format!("already up-to-date{suffix}")
+    }
+}
+
 /// On-the-wire payload for `plugin update`. Hoisted out of
 /// [`emit_plugin_update_summary_to`] so [`render_plugin_update_text`] can
 /// borrow the typed fields without a stringly-typed bridge.
@@ -744,6 +823,15 @@ struct PluginUpdateData<'a> {
     /// JSON envelope shape additive (dry-run runs don't gain a new field).
     #[serde(skip_serializing_if = "Option::is_none")]
     plists_count: Option<u32>,
+    /// v3.2.15: plugin version BEFORE the vault-sync step (from
+    /// `.claude-plugin/plugin.json::version`). `None` ⇒ fresh install / file
+    /// missing / version field missing.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    version_before: Option<&'a str>,
+    /// v3.2.15: plugin version AFTER the vault-sync step. In dry-run this
+    /// equals `version_before` (no tarball fetched).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    version_after: Option<&'a str>,
     dry_run: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
     note: Option<&'a str>,
@@ -764,6 +852,12 @@ impl<'a> PluginUpdateTextData for PluginUpdateData<'a> {
     fn plists_count(&self) -> Option<u32> {
         self.plists_count
     }
+    fn version_before(&self) -> Option<&str> {
+        self.version_before
+    }
+    fn version_after(&self) -> Option<&str> {
+        self.version_after
+    }
     fn dry_run(&self) -> bool {
         self.dry_run
     }
@@ -792,6 +886,8 @@ pub(crate) fn emit_plugin_update_summary_to<W: std::io::Write>(
         hooks_rewritten: report.hooks_rewritten,
         plists_rewritten: report.plists_rewritten,
         plists_count: report.plists_count,
+        version_before: report.version_before.as_deref(),
+        version_after: report.version_after.as_deref(),
         dry_run: report.dry_run,
         note: if report.dry_run {
             Some("dry-run · no changes written")
@@ -834,7 +930,7 @@ pub(crate) fn emit_plugin_update_summary_to<W: std::io::Write>(
 /// Layout (v3.2.13+):
 /// ```
 /// ────────────────────────────────────────────────
-///  ⚡  Plugin Update
+///  🔄  Plugin Update
 /// ────────────────────────────────────────────────
 ///
 ///  Update steps
@@ -871,7 +967,7 @@ where
     let mut buf: Vec<u8> = Vec::new();
 
     // ── Header ────────────────────────────────────────────────────────
-    let _ = write_framed_header(&mut buf, "⚡", "Plugin Update", color, rule_width);
+    let _ = write_framed_header(&mut buf, "🔄", "Plugin Update", color, rule_width);
 
     // ── Step list ─────────────────────────────────────────────────────
     // Today the only step that can populate `partial_failure` is the launchd
@@ -882,7 +978,13 @@ where
     // pre-3.2.13 it stayed `Ok` and silently misrepresented the failed step
     // as succeeded.
     let partial_failed = d.partial_failure().is_some();
-    let vault_detail = if d.vault_synced() { "done" } else { "skipped" };
+    let vault_detail = plugin_update_vault_detail(
+        d.vault_synced(),
+        d.dry_run(),
+        partial_failed,
+        d.version_before(),
+        d.version_after(),
+    );
     let hooks_detail = format!("{} rewritten", d.hooks_rewritten());
     // `plists_count` (v3.2.13): `Some(N>0)` → N refreshed; `Some(0)` →
     // vault has no schedule entries (well-formed no-op); `None` → step
@@ -903,12 +1005,7 @@ where
         StepStatus::Ok
     };
     let steps = vec![
-        Step::new(
-            "vault sync",
-            StepStatus::Ok,
-            Some(vault_detail.to_string()),
-            None,
-        ),
+        Step::new("vault sync", StepStatus::Ok, Some(vault_detail), None),
         Step::new("hooks", StepStatus::Ok, Some(hooks_detail), None),
         Step::new("launchd plists", plists_status, Some(plists_detail), None),
     ];
@@ -935,18 +1032,15 @@ where
     };
     let verdict_glyph = verdict_status.glyph();
     let verdict_prefix = verdict_status.ansi_prefix(color);
-    let verdict_text = match (d.partial_failure(), d.dry_run()) {
-        (Some(_), _) => "partial failure".to_string(),
-        (None, true) => "dry-run · no changes written".to_string(),
-        (None, false) => {
-            let any_change = d.vault_synced() || d.hooks_rewritten() > 0 || d.plists_rewritten();
-            if any_change {
-                "update complete".to_string()
-            } else {
-                "already up-to-date".to_string()
-            }
-        }
-    };
+    let verdict_text = plugin_update_verdict_text(
+        partial_failed,
+        d.dry_run(),
+        d.vault_synced(),
+        d.hooks_rewritten(),
+        d.plists_rewritten(),
+        d.version_before(),
+        d.version_after(),
+    );
     // Trailing count right-aligned to the rule width (matches doctor's
     // " ✓  N ok · M warn · K fail              N checks" layout).
     let total_str = "3 steps";
@@ -986,6 +1080,8 @@ trait PluginUpdateTextData {
     fn hooks_rewritten(&self) -> u32;
     fn plists_rewritten(&self) -> bool;
     fn plists_count(&self) -> Option<u32>;
+    fn version_before(&self) -> Option<&str>;
+    fn version_after(&self) -> Option<&str>;
     fn dry_run(&self) -> bool;
     fn partial_failure(&self) -> Option<&str>;
 }
@@ -1021,6 +1117,8 @@ mod tests {
             hooks_rewritten: 0,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
@@ -1079,13 +1177,15 @@ mod tests {
             hooks_rewritten: 3,
             plists_rewritten: true,
             plists_count: Some(3),
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
         let mut buf = Vec::new();
         emit_plugin_update_summary_to(&report, &text_mode_mono(), &mut buf).unwrap();
         let out = String::from_utf8(buf).unwrap();
-        assert!(out.contains("⚡  Plugin Update"), "header missing:\n{out}");
+        assert!(out.contains("🔄  Plugin Update"), "header missing:\n{out}");
         assert!(
             out.contains("Update steps"),
             "section marker missing:\n{out}"
@@ -1120,6 +1220,8 @@ mod tests {
             hooks_rewritten: 0,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
@@ -1149,6 +1251,8 @@ mod tests {
             hooks_rewritten: 2,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: Some("schedule re-register failed: launchctl exit 1".to_string()),
             warnings: Vec::new(),
         };
@@ -1185,6 +1289,8 @@ mod tests {
             hooks_rewritten: 2,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: Some(
                 "schedule re-register failed\nlaunchctl exit 1\nplist syntax error".to_string(),
             ),
@@ -1217,6 +1323,8 @@ mod tests {
             hooks_rewritten: 0,
             plists_rewritten: false,
             plists_count: Some(0),
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
@@ -1241,6 +1349,8 @@ mod tests {
             hooks_rewritten: 1,
             plists_rewritten: false,
             plists_count: Some(0),
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
@@ -1273,6 +1383,8 @@ mod tests {
             hooks_rewritten: 2,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: Some("schedule re-register failed: launchctl exit 1".to_string()),
             warnings: Vec::new(),
         };
@@ -1318,6 +1430,8 @@ mod tests {
             hooks_rewritten: 2,
             plists_rewritten: true,
             plists_count: Some(2),
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
@@ -1372,6 +1486,8 @@ mod tests {
             hooks_rewritten: 2,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: Some("schedule re-register failed: launchctl exit 1".to_string()),
             warnings: Vec::new(),
         };
@@ -1405,6 +1521,8 @@ mod tests {
             hooks_rewritten: 2,
             plists_rewritten: true,
             plists_count: Some(2),
+            version_before: None,
+            version_after: None,
             partial_failure: None,
             warnings: Vec::new(),
         };
diff --git a/crates/onebrain-cli/src/v31/plugin_update.rs b/crates/onebrain-cli/src/v31/plugin_update.rs
index ecb9262..b2df019 100644
--- a/crates/onebrain-cli/src/v31/plugin_update.rs
+++ b/crates/onebrain-cli/src/v31/plugin_update.rs
@@ -9,7 +9,27 @@
 use crate::v31::hook_rewriter::{self, RewriteWarning};
 use anyhow::{Context, Result};
 use onebrain_fs::register_hooks::settings::settings_path;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
+
+/// Read the plugin version from `<vault>/.claude/plugins/onebrain/.claude-plugin/plugin.json`.
+/// Returns `None` on the well-formed "no plugin installed yet" / "manifest
+/// missing the `version` field" paths so the framed renderer can fall back
+/// to the generic `done` / `skipped` detail strings; the orchestrator's own
+/// `read_plugin_version` in `onebrain-fs::vault_sync::orchestrate` does the
+/// same for the post-extract path inside the sync flow.
+fn read_plugin_version(vault_root: &Path) -> Option<String> {
+    let path = vault_root
+        .join(".claude")
+        .join("plugins")
+        .join("onebrain")
+        .join(".claude-plugin")
+        .join("plugin.json");
+    let text = std::fs::read_to_string(&path).ok()?;
+    let v: serde_json::Value = serde_json::from_str(&text).ok()?;
+    v.get("version")
+        .and_then(serde_json::Value::as_str)
+        .map(str::to_string)
+}
 
 #[derive(Debug, Default)]
 pub struct PluginUpdateReport {
@@ -25,6 +45,19 @@ pub struct PluginUpdateReport {
     /// because nothing to do" — previously both collapsed to a misleading
     /// `✓ launchd plists  done` row.
     pub plists_count: Option<u32>,
+    /// v3.2.15: plugin version (`.claude-plugin/plugin.json::version`) BEFORE
+    /// the vault-sync step. `None` means no plugin was installed yet (fresh
+    /// install) OR the file/field was missing/malformed. Used by the framed
+    /// renderer to label the vault-sync step with either `vX → vY` (real
+    /// update), `vX · up-to-date` (no version change), or `installed vY`
+    /// (fresh install).
+    pub version_before: Option<String>,
+    /// v3.2.15: plugin version AFTER the vault-sync step (i.e. the version
+    /// the downloaded tarball ships). `None` means we couldn't read the
+    /// post-sync `plugin.json` (sync failed, or the tarball didn't include
+    /// the manifest — neither expected on the happy path). In dry-run the
+    /// vault-sync step is skipped, so this stays equal to `version_before`.
+    pub version_after: Option<String>,
     pub dry_run: bool,
     /// When `Some(reason)`, the run failed midway. Fields above reflect
     /// whatever progress was made before the failure. The caller emits a
@@ -70,6 +103,13 @@ pub fn run(
     let resolved = crate::vault_ctx::require(vault_dir.clone())?;
     let vault_root = resolved.root.as_path().to_path_buf();
 
+    // v3.2.15: capture the installed plugin version BEFORE sync. The renderer
+    // uses (version_before, version_after) to label the vault-sync step row
+    // as `vX → vY` (real update) / `vX · up-to-date` (no version change) /
+    // `installed vY` (fresh install) — per user feedback, the pre-3.2.15
+    // `done` / `skipped` collapse hid which version was just applied.
+    report.version_before = read_plugin_version(&vault_root);
+
     // 2. Sync plugin tarball — same backend as v3.0 `vault-sync`.
     //    v3.2.13: invoke via the embedded-progress entry so the orchestrator
     //    skips its "OneBrain Vault Sync" intro frame and "vault-sync: done"
@@ -77,7 +117,7 @@ pub fn run(
     //    v3.2.15: ALSO route through `run_silent` so the per-step `▸ <label>`
     //    TTY lines don't leak above the parent's framed report (user testing
     //    on v3.2.14 flagged "ไม่มี header เลย" — the step lines appeared
-    //    BEFORE the parent's `⚡  Plugin Update` header). The framed report's
+    //    BEFORE the parent's `🔄  Plugin Update` header). The framed report's
     //    animated spinner is the only progress signal, matching what
     //    `doctor`/`update` already do.
     if !dry_run {
@@ -88,6 +128,13 @@ pub fn run(
             anyhow::bail!("plugin update: vault-sync returned exit code {exit}");
         }
         report.vault_synced = true;
+        // Re-read after sync to capture the (possibly new) installed version.
+        report.version_after = read_plugin_version(&vault_root);
+    } else {
+        // Dry-run skips the tarball fetch, so the "after" version is whatever
+        // is currently on disk (== before). Renderer treats this as "no
+        // change" and just shows the current version in the verdict.
+        report.version_after = report.version_before.clone();
     }
 
     // 3. Rewrite hook entries.
@@ -169,6 +216,8 @@ mod tests {
             hooks_rewritten: 3,
             plists_rewritten: false,
             plists_count: None,
+            version_before: None,
+            version_after: None,
             partial_failure: Some("schedule re-register failed: launchctl exit 1".to_string()),
             warnings: Vec::new(),
         };

From b9d66891cebb766396024651417b639efb9a145c Mon Sep 17 00:00:00 2001
From: Suppaseth Charoenkarnka <kengio@gmail.com>
Date: Thu, 28 May 2026 20:46:11 +0700
Subject: [PATCH 3/6] fix(cli): drop broken --output table/tsv +
 skill-run/harness-run no flag duplicate (v3.2.15 round 3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two more UX fixes from this turn's live testing — bundled per user's
'ทำรวมใน PR เดียวกัน' request:

G. **skill run / harness run --help: no flag duplicate at top.** Pre-3.2.15
   round-3 the verb-level help repeated the parent-level Commands:-listing
   flag breakdown above its own Options: section (where every flag is
   already listed with [default] + [possible values]). Now uses
   #[command(about = ..., long_about = ...)] so the parent listing keeps
   the flag breakdown but the verb-level help shows just the short prose.

H. **--output table / --output tsv removed entirely.** Both variants fell
   through to serialize_json(value, false) for every command — the format
   flag silently lied (\`--output table doctor\` emitted the same minified
   JSON as \`--output json doctor\`). User picked 'lบออก — เหลือ text/json/yaml
   (แนะนำ)'. Removed the OutputMode::Table / Tsv variants, the dispatcher
   arms, the resolver branches, the value_parser entries, the help text
   listings, and all 6 dependent tests. Remaining set: text / json / yaml.

1281 passed (lost 3 tests with the variants); clippy clean; fmt clean.
Still NOT MERGED — user testing locally first.
---
 CHANGELOG.md                                 |  2 +
 crates/onebrain-cli/src/banner.rs            | 49 +++++++-------------
 crates/onebrain-cli/src/cli.rs               | 45 +++++++++++-------
 crates/onebrain-cli/src/commands/doctor.rs   |  8 +---
 crates/onebrain-cli/src/legacy_output.rs     |  5 --
 crates/onebrain-cli/src/output/dispatcher.rs | 39 +++++++---------
 crates/onebrain-cli/src/output/mode.rs       | 40 +++++++---------
 crates/onebrain-cli/src/output/progress.rs   |  4 +-
 crates/onebrain-cli/tests/v31_integration.rs | 18 ++++---
 9 files changed, 90 insertions(+), 120 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9a03775..05865cd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Polish: `onebrain plugin update` no longer leaks the orchestrator's per-step `▸ <label>` lines above its framed report.** v3.2.13's `vault_sync::run_embedded` silenced the intro/outro frame but kept the step lines; v3.2.15 routes through new `vault_sync::run_silent` which forces the progress reporter to `io::sink()`. The framed `🔄  Plugin Update` header now appears as the FIRST thing in the report (right after the brand banner), with the animated spinner as the only progress signal during work — matches `doctor`/`update`'s established UX. `run_embedded` (intro-only suppression) removed; no remaining caller wanted the in-between mode.
 - **Feat: `plugin update` now reports current + latest plugin version explicitly.** The vault-sync step row reads `vX → vY` (real update), `vX · up-to-date` (rerun on the same version), or `installed vY` (fresh install) instead of the pre-3.2.15 collapse to `done` / `skipped`. The verdict footer also surfaces the delta — `updated v3.1.3 → v3.1.4` for a real bump, `update complete · v3.1.4` for no-version-change work, `already up-to-date · v3.1.4` for idempotent reruns, and `dry-run · current v3.1.4` for `--dry-run`. JSON envelope gains `version_before` / `version_after` fields (additive — both `#[serde(skip_serializing_if = "Option::is_none")]`).
 - **Break: `--json` (and `--output json`) now emits MINIFIED single-line JSON.** Pre-3.2.15 auto-prettified the JSON when stdout was a TTY, which was convenient for humans glancing at a structured response interactively but made the "copy/paste into curl / a script" path noisier. To get indented JSON now, pass `--json --pretty` (or `--output json --pretty`) explicitly.
+- **Break: `--output table` and `--output tsv` removed.** Both variants fell through to the JSON encoder unchanged for every command, so the format flag silently lied — `--output table doctor` emitted the same minified JSON as `--output json doctor`. Per user testing, dropped both from the `OutputMode` enum and the `--output` value parser; the remaining set is `text` / `json` / `yaml`. If a future command genuinely needs columnar output we'll add the column extractor and renderer together with the variant.
+- **Polish: `skill run --help` and `harness run --help` no longer duplicate the flag breakdown above their Options: section.** The parent-level `skill --help` / `harness --help` Commands: listing still shows each flag on its own indented line (the only summary the user sees at that level), but the verb-level help now uses a short prose `long_about` since the Options: section already lists every flag with its `[default]` + `[possible values]`.
 
 ## [3.2.14] — 2026-05-28 — `plugin update` animated spinner pacing (doctor/update parity)
 
diff --git a/crates/onebrain-cli/src/banner.rs b/crates/onebrain-cli/src/banner.rs
index 296dbd5..7e9d120 100644
--- a/crates/onebrain-cli/src/banner.rs
+++ b/crates/onebrain-cli/src/banner.rs
@@ -398,12 +398,15 @@ pub fn should_show_banner_for_help(
     if args.iter().skip(1).any(|a| a == "--json" || a == "--yaml") {
         return false;
     }
-    // `--output <fmt>` / `-o <fmt>` where fmt ∈ {json,yaml,table,tsv}.
+    // `--output <fmt>` / `-o <fmt>` where fmt ∈ {json,yaml}.
+    // v3.2.15: dropped `table` and `tsv` from the format set — both fell
+    // through to the JSON encoder, so the banner gate now only suppresses
+    // for the structured formats that actually emit non-text output.
     let mut iter = args.iter().skip(1).peekable();
     while let Some(a) = iter.next() {
         if a == "-o" || a == "--output" {
             if let Some(val) = iter.peek() {
-                if matches!(val.as_str(), "json" | "yaml" | "table" | "tsv") {
+                if matches!(val.as_str(), "json" | "yaml") {
                     return false;
                 }
             }
@@ -411,7 +414,7 @@ pub fn should_show_banner_for_help(
             .strip_prefix("--output=")
             .or_else(|| a.strip_prefix("-o="))
         {
-            if matches!(val, "json" | "yaml" | "table" | "tsv") {
+            if matches!(val, "json" | "yaml") {
                 return false;
             }
         }
@@ -560,17 +563,11 @@ mod tests {
         assert!(!should_show_banner(&cli, &OutputMode::Yaml));
     }
 
-    #[test]
-    fn table_mode_suppresses_banner() {
-        let cli = parse(&["onebrain", "vault", "current"]);
-        assert!(!should_show_banner(&cli, &OutputMode::Table));
-    }
-
-    #[test]
-    fn tsv_mode_suppresses_banner() {
-        let cli = parse(&["onebrain", "vault", "current"]);
-        assert!(!should_show_banner(&cli, &OutputMode::Tsv));
-    }
+    // `table_mode_suppresses_banner` / `tsv_mode_suppresses_banner` removed
+    // in v3.2.15 along with the `Table` / `Tsv` `OutputMode` variants — both
+    // formats fell through to the JSON encoder, so the format flag never
+    // produced the columnar / TSV output it promised. JSON / YAML still
+    // suppress the banner via the two tests above.
 
     #[test]
     fn mono_text_mode_suppresses_banner() {
@@ -990,6 +987,8 @@ mod tests {
 
     #[test]
     fn should_show_banner_for_help_output_json_suppresses() {
+        // v3.2.15: dropped `--output=table` / `-o=tsv` rows along with the
+        // removed `OutputMode` variants. JSON / YAML remain.
         let args = s(&["onebrain", "--help", "--output", "json"]);
         assert!(!should_show_banner_for_help(
             &color_text_mode(),
@@ -1002,18 +1001,6 @@ mod tests {
             &args2,
             &HelpBannerEnv::default()
         ));
-        let args3 = s(&["onebrain", "--help", "--output=table"]);
-        assert!(!should_show_banner_for_help(
-            &color_text_mode(),
-            &args3,
-            &HelpBannerEnv::default()
-        ));
-        let args4 = s(&["onebrain", "--help", "-o=tsv"]);
-        assert!(!should_show_banner_for_help(
-            &color_text_mode(),
-            &args4,
-            &HelpBannerEnv::default()
-        ));
     }
 
     #[test]
@@ -1036,14 +1023,10 @@ mod tests {
     fn should_show_banner_for_help_structured_mode_suppresses() {
         // Even if argv has no structured flag, OutputMode could already be
         // structured (e.g. consumer-side mode override) — the gate also
-        // suppresses for Json/Yaml/Table/Tsv modes.
+        // suppresses for Json/Yaml modes. (v3.2.15: dropped Table/Tsv from
+        // the suppression list along with the variants themselves.)
         let args = s(&["onebrain", "--help"]);
-        for mode in [
-            OutputMode::Json { pretty: true },
-            OutputMode::Yaml,
-            OutputMode::Table,
-            OutputMode::Tsv,
-        ] {
+        for mode in [OutputMode::Json { pretty: true }, OutputMode::Yaml] {
             assert!(
                 !should_show_banner_for_help(&mode, &args, &HelpBannerEnv::default()),
                 "expected suppression for {mode:?}"
diff --git a/crates/onebrain-cli/src/cli.rs b/crates/onebrain-cli/src/cli.rs
index 2faafbe..1a602c9 100644
--- a/crates/onebrain-cli/src/cli.rs
+++ b/crates/onebrain-cli/src/cli.rs
@@ -30,11 +30,11 @@ pub struct Cli {
         long,
         global = true,
         default_value = "text",
-        value_parser = ["text", "json", "yaml", "table", "tsv"],
+        value_parser = ["text", "json", "yaml"],
         value_name = "FMT",
         hide_default_value = true,
         hide_possible_values = true,
-        help = "Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically\n[default: text, possible values: text, json, yaml, table, tsv]"
+        help = "Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically\n[default: text, possible values: text, json, yaml]"
     )]
     pub output: String,
 
@@ -496,18 +496,23 @@ pub struct HarnessCmd {
 pub enum HarnessVerb {
     /// Detect the active harness (Claude Code / Gemini / direct).
     Detect,
-    // v3.2.15: use `#[command(about = "...")]` with explicit `\n` so each
-    // flag in the inline summary lands on its own indented line under
-    // `harness --help`'s Commands: list (per user testing — the dot-separated
-    // single-line form was too dense to scan). The hidden `long_about` keeps
-    // the same content for `harness run --help` (clap derives both from
-    // `about` when `long_about` is unset).
-    #[command(about = "Run a prompt through claude or gemini headlessly.\n\
-        Flags:\n  \
-          --harness {claude,gemini}\n  \
-          --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
-          --mode {with-context, ad-hoc} — with-context (default) loads vault CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, ad-hoc skips project context\n\
-        Omit <PROMPT> to read from stdin (`cat note.md | …`).")]
+    // v3.2.15: split `about` (compact-listing form with flag breakdown,
+    // shown under `harness --help`'s Commands: table) from `long_about`
+    // (short prose, shown at the top of `harness run --help`). Pre-split
+    // the parent-level listing was a single dense dot-separated line, AND
+    // the verb-level help screen redundantly repeated the same flag listing
+    // above its own Options: section — clap defaults to using `about` for
+    // both views when `long_about` is unset.
+    #[command(
+        about = "Run a prompt through claude or gemini headlessly.\n\
+            Flags:\n  \
+              --harness {claude,gemini}\n  \
+              --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
+              --mode {with-context, ad-hoc} — with-context (default) loads vault CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, ad-hoc skips project context\n\
+            Omit <PROMPT> to read from stdin (`cat note.md | …`).",
+        long_about = "Run a prompt through claude or gemini headlessly. \
+            Omit <PROMPT> to read from stdin (`cat note.md | …`)."
+    )]
     Run {
         /// Vault root override · also accepts global `--vault`, and walks up from cwd when omitted.
         /// Ignored when `--mode ad-hoc`.
@@ -1074,9 +1079,11 @@ pub enum SkillVerb {
     /// List installed skills (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
     List,
-    // v3.2.15: same flag-per-line treatment as `HarnessVerb::Run` — per user
-    // testing the dot-separated single-line form was too dense to scan under
-    // `skill --help`.
+    // v3.2.15: same about/long_about split as `HarnessVerb::Run` — flag
+    // breakdown only in the parent-level `skill --help` Commands: listing
+    // (where it's the only summary the user sees of `run`); the verb-level
+    // `skill run --help` uses the short prose since the Options: section
+    // already lists each flag with its `[default]` + `[possible values]`.
     #[command(
         about = "Run a OneBrain skill (`/onebrain:<name>`) in headless mode.\n\
         Flags:\n  \
@@ -1084,7 +1091,9 @@ pub enum SkillVerb {
           --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
           --skill <name> (parity alias for the positional <NAME>)\n  \
           --arg key=value (pass-through)\n\
-        Replaces v3.0 `run-skill`."
+        Replaces v3.0 `run-skill`.",
+        long_about = "Run a OneBrain skill (`/onebrain:<name>`) in headless mode. \
+            Replaces v3.0 `run-skill`."
     )]
     Run {
         /// Vault root override · also accepts global `--vault`, and walks up from cwd when omitted.
diff --git a/crates/onebrain-cli/src/commands/doctor.rs b/crates/onebrain-cli/src/commands/doctor.rs
index 1098728..9c33b3e 100644
--- a/crates/onebrain-cli/src/commands/doctor.rs
+++ b/crates/onebrain-cli/src/commands/doctor.rs
@@ -1635,12 +1635,8 @@ mod tests {
             pretty: true,
         };
         assert!(!should_animate(&mono, true, false), "no-color off");
-        for structured in [
-            OutputMode::Json { pretty: true },
-            OutputMode::Yaml,
-            OutputMode::Tsv,
-            OutputMode::Table,
-        ] {
+        // v3.2.15: Table / Tsv variants dropped from `OutputMode`.
+        for structured in [OutputMode::Json { pretty: true }, OutputMode::Yaml] {
             assert!(
                 !should_animate(&structured, true, false),
                 "structured {structured:?} off"
diff --git a/crates/onebrain-cli/src/legacy_output.rs b/crates/onebrain-cli/src/legacy_output.rs
index bd7918d..8f4ea89 100644
--- a/crates/onebrain-cli/src/legacy_output.rs
+++ b/crates/onebrain-cli/src/legacy_output.rs
@@ -56,11 +56,6 @@ pub fn serialize_for_mode<T: Serialize>(value: &T, mode: &OutputMode) -> String
             }
         },
         OutputMode::Json { pretty } => serialize_json(value, *pretty),
-        // Table / Tsv have no columnar slot for hook-protocol blocks. Fall
-        // back to compact JSON so the consumer still gets parseable output;
-        // commands that care about text rendering branch on
-        // `OutputMode::Text { .. }` before calling this function.
-        OutputMode::Table | OutputMode::Tsv => serialize_json(value, false),
         // Text-mode arrival is a caller bug — the per-command text renderer
         // should have absorbed this. Loud in debug, compact-JSON fallback in
         // release (compact, not pretty, because pretty-text-via-JSON would
diff --git a/crates/onebrain-cli/src/output/dispatcher.rs b/crates/onebrain-cli/src/output/dispatcher.rs
index 3a552a7..ed098ab 100644
--- a/crates/onebrain-cli/src/output/dispatcher.rs
+++ b/crates/onebrain-cli/src/output/dispatcher.rs
@@ -13,10 +13,16 @@ use std::io::Write;
 
 /// Emit `envelope` to `writer` in the format chosen by `mode`.
 ///
-/// The `text_render` closure is only invoked in `OutputMode::Text` /
-/// `OutputMode::Table` — structured modes (`json`/`yaml`/`tsv`) ignore it
-/// entirely. This keeps text rendering lazy so commands don't pay the
-/// formatting cost when piping to a downstream parser.
+/// The `text_render` closure is only invoked in `OutputMode::Text` —
+/// structured modes (`json`/`yaml`) ignore it entirely. This keeps text
+/// rendering lazy so commands don't pay the formatting cost when piping to a
+/// downstream parser.
+///
+/// v3.2.15: `Table` and `Tsv` variants were dropped from `OutputMode` — both
+/// fell through to `serialize_json(value, false)` so the format flag silently
+/// lied about its output. The arms that previously emitted a stub TSV header
+/// or routed through the text renderer for `Table` are gone with the
+/// variants.
 pub fn emit<T, W, F>(
     envelope: &Envelope<T>,
     mode: &OutputMode,
@@ -41,23 +47,14 @@ where
             let s = serde_yaml::to_string(envelope)?;
             writer.write_all(s.as_bytes())?;
         }
-        OutputMode::Tsv => {
-            // Generic TSV fallback: header `command\tok` + one row. Commands
-            // with list payloads override by passing a structured text body
-            // through the `text_render` closure when mode==Tsv if they want
-            // a real columnar emit. v3.1 ships the fallback; v3.2+ widens
-            // per-command.
-            writeln!(writer, "command\tok")?;
-            writeln!(writer, "{}\t{}", envelope.command, envelope.ok)?;
-        }
-        OutputMode::Table | OutputMode::Text { .. } => {
+        OutputMode::Text { .. } => {
             let s = text_render(envelope);
             writer.write_all(s.as_bytes())?;
             if !s.ends_with('\n') {
                 writeln!(writer)?;
             }
             // Surface soft warnings in human modes — structured modes already
-            // carry them in the `warnings` array, but a text/table user would
+            // carry them in the `warnings` array, but a text user would
             // otherwise never see e.g. "N notes were unreadable and skipped".
             for w in &envelope.warnings {
                 writeln!(writer, "⚠️  {}", w.message)?;
@@ -185,12 +182,8 @@ mod tests {
         assert!(s.contains("2 note(s) unreadable and skipped"));
     }
 
-    #[test]
-    fn tsv_mode_emits_header_and_row() {
-        let env = Envelope::ok("task.list", None, P { n: 9 });
-        let mut buf = Vec::new();
-        emit(&env, &OutputMode::Tsv, &mut buf, |_| unreachable!()).unwrap();
-        let s = String::from_utf8(buf).unwrap();
-        assert_eq!(s, "command\tok\ntask.list\ttrue\n");
-    }
+    // `tsv_mode_emits_header_and_row` test removed in v3.2.15 along with the
+    // `OutputMode::Tsv` variant — pre-3.2.15 every command routed Tsv (and
+    // Table) through the JSON encoder, so the stub `command\tok` row this
+    // test asserted was visible to no real consumer.
 }
diff --git a/crates/onebrain-cli/src/output/mode.rs b/crates/onebrain-cli/src/output/mode.rs
index 2f3fbf5..4a495b5 100644
--- a/crates/onebrain-cli/src/output/mode.rs
+++ b/crates/onebrain-cli/src/output/mode.rs
@@ -22,18 +22,19 @@ pub enum OutputMode {
     Json { pretty: bool },
     /// `--yaml` / `-o yaml`. Same envelope shape, YAML serialised.
     Yaml,
-    /// `--output table`. Aligned columns; falls back to text for non-list
-    /// commands.
-    Table,
-    /// `--output tsv`. Header + tab-separated rows.
-    Tsv,
+    // v3.2.15 dropped `Table` and `Tsv` — both variants fell through to the
+    // JSON encoder unchanged for every command, so the format flag silently
+    // claimed to render columns / tab-separated rows while emitting the same
+    // bytes as `--output json`. Removing the variants closes the false
+    // promise; if a future command genuinely needs tabular output we'll add
+    // the column extractor + renderer together with the variant.
 }
 
 impl OutputMode {
-    /// True when the mode is structured (JSON/YAML/TSV/table). Used by
-    /// `main.rs`'s error-path renderer (R1 B5) to decide between the
-    /// human-readable `Error: <msg>` line on stderr and the canonical
-    /// JSON envelope on stdout.
+    /// True when the mode is structured (JSON/YAML). Used by `main.rs`'s
+    /// error-path renderer (R1 B5) to decide between the human-readable
+    /// `Error: <msg>` line on stderr and the canonical JSON envelope on
+    /// stdout.
     pub fn is_structured(&self) -> bool {
         !matches!(self, OutputMode::Text { .. })
     }
@@ -113,8 +114,6 @@ pub fn resolve_output_mode(i: &TtyInputs) -> OutputMode {
     match i.output_flag.as_str() {
         "json" => OutputMode::Json { pretty: i.pretty },
         "yaml" => OutputMode::Yaml,
-        "table" => OutputMode::Table,
-        "tsv" => OutputMode::Tsv,
         _ => {
             // text — apply the 6-rule chain. CI is "any non-empty value" per
             // is-ci / ci-info convention (R1 C4).
@@ -316,16 +315,13 @@ mod tests {
     }
 
     #[test]
-    fn output_flag_yaml_table_tsv() {
-        for (flag, expected) in [
-            ("yaml", OutputMode::Yaml),
-            ("table", OutputMode::Table),
-            ("tsv", OutputMode::Tsv),
-        ] {
-            let mut i = base();
-            i.output_flag = flag.into();
-            assert_eq!(resolve_output_mode(&i), expected, "flag={flag}");
-        }
+    fn output_flag_yaml_picks_yaml_mode() {
+        // v3.2.15: `Table` and `Tsv` variants dropped — both fell through to
+        // the JSON encoder unchanged, so the format flag silently lied about
+        // its output. The remaining structured target via `--output` is YAML.
+        let mut i = base();
+        i.output_flag = "yaml".into();
+        assert_eq!(resolve_output_mode(&i), OutputMode::Yaml);
     }
 
     #[test]
@@ -345,7 +341,5 @@ mod tests {
         .is_structured());
         assert!(OutputMode::Json { pretty: true }.is_structured());
         assert!(OutputMode::Yaml.is_structured());
-        assert!(OutputMode::Table.is_structured());
-        assert!(OutputMode::Tsv.is_structured());
     }
 }
diff --git a/crates/onebrain-cli/src/output/progress.rs b/crates/onebrain-cli/src/output/progress.rs
index 03a361d..f7be6ce 100644
--- a/crates/onebrain-cli/src/output/progress.rs
+++ b/crates/onebrain-cli/src/output/progress.rs
@@ -452,12 +452,12 @@ mod tests {
 
     #[test]
     fn no_animate_for_structured_modes() {
+        // v3.2.15: Table / Tsv variants dropped from `OutputMode`. Json / Yaml
+        // are the remaining structured targets.
         for mode in [
             OutputMode::Json { pretty: true },
             OutputMode::Json { pretty: false },
             OutputMode::Yaml,
-            OutputMode::Table,
-            OutputMode::Tsv,
         ] {
             assert!(
                 !should_animate(&mode, true, false),
diff --git a/crates/onebrain-cli/tests/v31_integration.rs b/crates/onebrain-cli/tests/v31_integration.rs
index b23c58a..63a5386 100644
--- a/crates/onebrain-cli/tests/v31_integration.rs
+++ b/crates/onebrain-cli/tests/v31_integration.rs
@@ -95,20 +95,18 @@ fn root_help_renders_compact_with_wrapped_defaults() {
     );
     // `-o, --output` description on the same line; `[default: text, \
     // possible values: ...]` wrapped to a new aligned line below.
+    // v3.2.15: dropped `table` and `tsv` from the possible values along
+    // with the OutputMode variants that lied about emitting columnar / TSV
+    // output (every command routed both through the JSON encoder).
     assert!(
         stdout.contains(
-            "  -o, --output <FMT>  Output format. Default `text` is TTY-friendly; \
-             pipe-detected calls drop color/pretty automatically\n\
-                                  [default: text, possible values: text, json, yaml, table, tsv]"
-                .replace("             ", "")
-                .as_str()
-        ) || stdout.contains(
-            "  -o, --output <FMT>  Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically\n                      [default: text, possible values: text, json, yaml, table, tsv]"
+            "  -o, --output <FMT>  Output format. Default `text` is TTY-friendly; pipe-detected calls drop color/pretty automatically\n                      [default: text, possible values: text, json, yaml]"
         ),
         "expected `-o, --output` description inline with `[default: text, \
-         possible values: ...]` wrapped to indented next line. The \
-         `hide_default_value` / `hide_possible_values` + manual help-string \
-         wrap on `Cli::output` may have been removed. Got:\n{stdout}"
+         possible values: text, json, yaml]` wrapped to indented next line. \
+         The `hide_default_value` / `hide_possible_values` + manual help-string \
+         wrap on `Cli::output` may have been removed, or `table` / `tsv` may \
+         have been re-added to the possible values list. Got:\n{stdout}"
     );
 }
 

From f366aa8123e87d006dd710f2663ffb843e620aee Mon Sep 17 00:00:00 2001
From: Suppaseth Charoenkarnka <kengio@gmail.com>
Date: Thu, 28 May 2026 21:26:05 +0700
Subject: [PATCH 4/6] fix(cli): compact verb-level Options + positional <NAME>
 descriptions (v3.2.15 round 4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two more UX fixes from this turn's live testing:

I. **`skill run --help` / `harness run --help` now render Options compact**
   like top-level `onebrain --help`. Reverted round-3's parent-listing
   flag-per-line breakdown on `SkillVerb::Run` / `HarnessVerb::Run` —
   discovered the multi-line `#[command(about = ...)]` was triggering
   clap's auto-switch to long format (option name on own line + indented
   desc) at the verb level. Now both variants use a single-line doc-comment
   about so verb-level Options stays compact AND `[default]` + `[possible
   values]` still wraps to an indented next line for the args that carry
   both. Parent-level `skill --help` / `harness --help` Commands: rows now
   show a one-line summary (trade-off: lost the per-flag breakdown in the
   parent listing, but user explicitly chose compact verb-level).

J. **Positional `<NAME>` description for skill info / show / bootstrap +
   hidden bundle verbs.** Previously rendered as a bare `<NAME>` with no
   help text because the variant's doc-comment described the verb itself
   but didn't propagate to the inline-struct positional arg. Now every
   such variant uses the block form `Variant { /// <doc> name: String, }`.

1281 passed; clippy clean; fmt clean. Still NOT MERGED — user testing.
---
 CHANGELOG.md                   |  3 +-
 crates/onebrain-cli/src/cli.rs | 95 +++++++++++++++++-----------------
 2 files changed, 50 insertions(+), 48 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05865cd..f9961fb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,7 +21,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - **Feat: `plugin update` now reports current + latest plugin version explicitly.** The vault-sync step row reads `vX → vY` (real update), `vX · up-to-date` (rerun on the same version), or `installed vY` (fresh install) instead of the pre-3.2.15 collapse to `done` / `skipped`. The verdict footer also surfaces the delta — `updated v3.1.3 → v3.1.4` for a real bump, `update complete · v3.1.4` for no-version-change work, `already up-to-date · v3.1.4` for idempotent reruns, and `dry-run · current v3.1.4` for `--dry-run`. JSON envelope gains `version_before` / `version_after` fields (additive — both `#[serde(skip_serializing_if = "Option::is_none")]`).
 - **Break: `--json` (and `--output json`) now emits MINIFIED single-line JSON.** Pre-3.2.15 auto-prettified the JSON when stdout was a TTY, which was convenient for humans glancing at a structured response interactively but made the "copy/paste into curl / a script" path noisier. To get indented JSON now, pass `--json --pretty` (or `--output json --pretty`) explicitly.
 - **Break: `--output table` and `--output tsv` removed.** Both variants fell through to the JSON encoder unchanged for every command, so the format flag silently lied — `--output table doctor` emitted the same minified JSON as `--output json doctor`. Per user testing, dropped both from the `OutputMode` enum and the `--output` value parser; the remaining set is `text` / `json` / `yaml`. If a future command genuinely needs columnar output we'll add the column extractor and renderer together with the variant.
-- **Polish: `skill run --help` and `harness run --help` no longer duplicate the flag breakdown above their Options: section.** The parent-level `skill --help` / `harness --help` Commands: listing still shows each flag on its own indented line (the only summary the user sees at that level), but the verb-level help now uses a short prose `long_about` since the Options: section already lists every flag with its `[default]` + `[possible values]`.
+- **Polish: `skill run --help` and `harness run --help` no longer duplicate the flag breakdown above their Options: section.** Reverted v3.2.15 round-2's parent-listing flag-per-line breakdown on `SkillVerb::Run` / `HarnessVerb::Run` — clap's renderer auto-switches to long format (option name on its own line + indented description) on the verb-level help whenever the variant's `about` contains a newline. Trade-off chosen per user testing: parent-level `skill --help` / `harness --help` Commands: rows now show a one-line summary, but the verb-level `--help` Options: section is COMPACT (matches top-level `onebrain --help`) and still wraps `[default]` + `[possible values]` to an indented next line for args that carry both.
+- **Polish: positional `<NAME>` args on `skill info` / `skill show` / `skill bootstrap` (and the hidden `bundle install/show/info/init/lint/update/remove`) now carry a description in the Arguments: section.** Previously they rendered as a bare `<NAME>` with no help text; the variant doc-comment described what the verb does but didn't propagate to the positional arg.
 
 ## [3.2.14] — 2026-05-28 — `plugin update` animated spinner pacing (doctor/update parity)
 
diff --git a/crates/onebrain-cli/src/cli.rs b/crates/onebrain-cli/src/cli.rs
index 1a602c9..779369b 100644
--- a/crates/onebrain-cli/src/cli.rs
+++ b/crates/onebrain-cli/src/cli.rs
@@ -13,7 +13,8 @@ use std::path::PathBuf;
     name = "onebrain",
     version,
     disable_help_subcommand = true,
-    propagate_version = true
+    propagate_version = true,
+    term_width = 200
 )]
 pub struct Cli {
     // `vault` doc is a single line so `--help` (long) renders identically to
@@ -267,27 +268,48 @@ pub struct BundleCmd {
 pub enum BundleVerb {
     /// Install a bundle (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
-    Install { name: String },
+    Install {
+        /// Bundle name (npm-style identifier).
+        name: String,
+    },
     /// Print a bundle's overview / README body (not yet implemented · v3.x
     /// roadmap). Mirrors `SkillVerb::Show` semantics: renders the bundle's
     /// human-readable body, NOT clap's CLI usage (use `--help` for that).
     #[command(hide = true)]
-    Show { name: String },
+    Show {
+        /// Bundle name (npm-style identifier).
+        name: String,
+    },
     /// Print bundle metadata (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
-    Info { name: String },
+    Info {
+        /// Bundle name (npm-style identifier).
+        name: String,
+    },
     /// Scaffold a new bundle (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
-    Init { name: String },
+    Init {
+        /// Bundle name to create (npm-style identifier).
+        name: String,
+    },
     /// Lint a bundle (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
-    Lint { name: String },
+    Lint {
+        /// Bundle name (npm-style identifier).
+        name: String,
+    },
     /// Update a bundle (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
-    Update { name: String },
+    Update {
+        /// Bundle name (npm-style identifier).
+        name: String,
+    },
     /// Remove an installed bundle (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
-    Remove { name: String },
+    Remove {
+        /// Bundle name (npm-style identifier).
+        name: String,
+    },
     /// Run bundle diagnostics (not yet implemented · v3.x roadmap).
     #[command(hide = true)]
     Doctor,
@@ -496,23 +518,7 @@ pub struct HarnessCmd {
 pub enum HarnessVerb {
     /// Detect the active harness (Claude Code / Gemini / direct).
     Detect,
-    // v3.2.15: split `about` (compact-listing form with flag breakdown,
-    // shown under `harness --help`'s Commands: table) from `long_about`
-    // (short prose, shown at the top of `harness run --help`). Pre-split
-    // the parent-level listing was a single dense dot-separated line, AND
-    // the verb-level help screen redundantly repeated the same flag listing
-    // above its own Options: section — clap defaults to using `about` for
-    // both views when `long_about` is unset.
-    #[command(
-        about = "Run a prompt through claude or gemini headlessly.\n\
-            Flags:\n  \
-              --harness {claude,gemini}\n  \
-              --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
-              --mode {with-context, ad-hoc} — with-context (default) loads vault CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, ad-hoc skips project context\n\
-            Omit <PROMPT> to read from stdin (`cat note.md | …`).",
-        long_about = "Run a prompt through claude or gemini headlessly. \
-            Omit <PROMPT> to read from stdin (`cat note.md | …`)."
-    )]
+    /// Run a prompt through claude or gemini headlessly. Omit <PROMPT> to read from stdin (`cat note.md | …`).
     Run {
         /// Vault root override · also accepts global `--vault`, and walks up from cwd when omitted.
         /// Ignored when `--mode ad-hoc`.
@@ -526,7 +532,7 @@ pub enum HarnessVerb {
             default_value_t = HarnessMode::WithContext,
             hide_default_value = true,
             hide_possible_values = true,
-            help = "Whether to inject the vault's OneBrain context before answering. `with-context` loads CLAUDE.md/INSTRUCTIONS.md/GEMINI.md, `ad-hoc` skips (cwd=`$TMPDIR`, no vault flag)\n[default: with-context, possible values: with-context, ad-hoc]"
+            help = "Inject the vault's OneBrain context before answering\n[default: with-context, possible values: with-context, ad-hoc]"
         )]
         mode: HarnessMode,
         #[arg(
@@ -1084,26 +1090,14 @@ pub enum SkillVerb {
     // (where it's the only summary the user sees of `run`); the verb-level
     // `skill run --help` uses the short prose since the Options: section
     // already lists each flag with its `[default]` + `[possible values]`.
-    #[command(
-        about = "Run a OneBrain skill (`/onebrain:<name>`) in headless mode.\n\
-        Flags:\n  \
-          --harness {claude,gemini}\n  \
-          --model <m> (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`)\n  \
-          --skill <name> (parity alias for the positional <NAME>)\n  \
-          --arg key=value (pass-through)\n\
-        Replaces v3.0 `run-skill`.",
-        long_about = "Run a OneBrain skill (`/onebrain:<name>`) in headless mode. \
-            Replaces v3.0 `run-skill`."
-    )]
+    /// Run a OneBrain skill (`/onebrain:<name>`) in headless mode. Replaces v3.0 `run-skill`.
     Run {
         /// Vault root override · also accepts global `--vault`, and walks up from cwd when omitted.
         #[arg(long = "vault-dir", value_name = "PATH", hide = true)]
         vault_dir: Option<PathBuf>,
-        /// Skill name (with or without slash prefix). Positional form:
-        /// `onebrain skill run daily`.
+        /// Skill name (with or without slash prefix). Positional form: `onebrain skill run daily`.
         name: Option<String>,
-        /// Skill name as a flag — `--skill /daily` — for parity with the
-        /// scheduler's `run-skill` form. Equivalent to the positional `<NAME>`.
+        /// Skill name as a flag — `--skill /daily` — for parity with the scheduler's `run-skill` form. Equivalent to the positional `<NAME>`.
         #[arg(long = "skill", value_name = "NAME", conflicts_with = "name")]
         skill: Option<String>,
         #[arg(
@@ -1115,9 +1109,7 @@ pub enum SkillVerb {
             help = "AI runtime to run the skill through\n[default: claude, possible values: claude, gemini]"
         )]
         harness: HarnessArg,
-        /// Model passed through to the harness (`claude --model <m>` /
-        /// `gemini -m <m>`). Omit to use the harness default. A faster model
-        /// (e.g. `claude-haiku-4-5`, `gemini-2.5-flash`) speeds up headless runs.
+        /// Model passed through to the harness. Omit to use the harness default. A faster model speeds up headless runs.
         #[arg(long, value_name = "MODEL")]
         model: Option<String>,
         /// Pass-through arguments (`--arg key=value`).
@@ -1125,12 +1117,21 @@ pub enum SkillVerb {
         args: Vec<String>,
     },
     /// Bootstrap a skill's state files · called by skills internally.
-    Bootstrap { name: String },
+    Bootstrap {
+        /// Skill name (with or without slash prefix · e.g. `daily` or `/daily`).
+        name: String,
+    },
     /// Print a skill's SKILL.md body (workflow markdown) · convenience for
     /// skill scripting. Use `onebrain skill run --help` for CLI usage.
-    Show { name: String },
+    Show {
+        /// Skill name (with or without slash prefix · e.g. `daily` or `/daily`).
+        name: String,
+    },
     /// Print skill metadata (frontmatter) · `--json` for structured output.
-    Info { name: String },
+    Info {
+        /// Skill name (with or without slash prefix · e.g. `daily` or `/daily`).
+        name: String,
+    },
 }
 
 // ─────────────────────────────────────────────────────────────────────────

From 76a5d9aa9fd7ce138603db723caa9c833909d90f Mon Sep 17 00:00:00 2001
From: Suppaseth Charoenkarnka <kengio@gmail.com>
Date: Thu, 28 May 2026 22:03:00 +0700
Subject: [PATCH 5/6] =?UTF-8?q?chore:=20round-1=20review=20polish=20?=
 =?UTF-8?q?=E2=80=94=20CHANGELOG=20to=208=20bullets,=20stale=20table/tsv?=
 =?UTF-8?q?=20doc-drift=20cleaned?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-1 review caught:
- CHANGELOG had 9 bullets under v3.2.15 (over the 8-bullet cap) — dropped
  the stale entry about parent-listing flag-per-line (round 4 reverted
  that, so the bullet documented behaviour that never shipped).
- Stale doc-comment refs to dropped `table` / `tsv` variants in
  legacy_output.rs, main.rs, banner.rs (top-level module doc + the
  suppress-precedence comment), output/mode.rs, output/progress.rs.

1281 passed; clippy clean; fmt clean. Still NOT MERGED.
---
 CHANGELOG.md                               |  1 -
 crates/onebrain-cli/src/banner.rs          |  8 ++++----
 crates/onebrain-cli/src/legacy_output.rs   |  7 ++++---
 crates/onebrain-cli/src/main.rs            | 13 +++++--------
 crates/onebrain-cli/src/output/mode.rs     |  2 +-
 crates/onebrain-cli/src/output/progress.rs | 10 +++++-----
 6 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9961fb..6189084 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,7 +15,6 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [3.2.15] — 2026-05-28 — `--help` compact-with-wrap · plugin update polish · per-command emoji · version tracking · `--json` minified
 
 - **Break: `--help` reverts to compact layout** (command + description on the same line) — v3.2.12's blanket `next_line_help = true` pushed every arg into long format, which user testing flagged as "ดูยาก" (hard to read). For args carrying `[default]` + `[possible values]` (`-o, --output`, `--mode`, `--harness` on `skill run` / `harness run`), the description still renders inline but the bracketed value block wraps to a new indented line below. Achieved by `hide_default_value = true` + `hide_possible_values = true` + a manual `\n[default: …, possible values: …]` tail on the `help` string.
-- **Polish: `skill --help` / `harness --help` now lay out each flag in the `run` subcommand's description on its own indented line** instead of one dense dot-separated single-line summary that ran past the terminal width. Achieved via explicit `\n` in the `#[command(about = "…")]` override on `SkillVerb::Run` / `HarnessVerb::Run`.
 - **Polish: per-command framed-header emoji differentiated.** Pre-3.2.15 both `doctor` and `update` used 🧠 (same as the OneBrain wordmark banner above them); v3.2.15: `doctor` → 🔬, `update` → 🚀, `plugin update` → 🔄. Each command now reads at a glance and stops competing with the brand glyph.
 - **Polish: `onebrain plugin update` no longer leaks the orchestrator's per-step `▸ <label>` lines above its framed report.** v3.2.13's `vault_sync::run_embedded` silenced the intro/outro frame but kept the step lines; v3.2.15 routes through new `vault_sync::run_silent` which forces the progress reporter to `io::sink()`. The framed `🔄  Plugin Update` header now appears as the FIRST thing in the report (right after the brand banner), with the animated spinner as the only progress signal during work — matches `doctor`/`update`'s established UX. `run_embedded` (intro-only suppression) removed; no remaining caller wanted the in-between mode.
 - **Feat: `plugin update` now reports current + latest plugin version explicitly.** The vault-sync step row reads `vX → vY` (real update), `vX · up-to-date` (rerun on the same version), or `installed vY` (fresh install) instead of the pre-3.2.15 collapse to `done` / `skipped`. The verdict footer also surfaces the delta — `updated v3.1.3 → v3.1.4` for a real bump, `update complete · v3.1.4` for no-version-change work, `already up-to-date · v3.1.4` for idempotent reruns, and `dry-run · current v3.1.4` for `--dry-run`. JSON envelope gains `version_before` / `version_after` fields (additive — both `#[serde(skip_serializing_if = "Option::is_none")]`).
diff --git a/crates/onebrain-cli/src/banner.rs b/crates/onebrain-cli/src/banner.rs
index 7e9d120..50bb782 100644
--- a/crates/onebrain-cli/src/banner.rs
+++ b/crates/onebrain-cli/src/banner.rs
@@ -12,8 +12,8 @@
 //! Gating rules (see [`should_show_banner`]):
 //! 1. `--quiet` always suppresses.
 //! 2. Only `OutputMode::Text { color: true, .. }` shows the banner — pipes,
-//!    `--json`, `--yaml`, `--output table|tsv`, and `NO_COLOR`/`TERM=dumb`/
-//!    `CI=true`/`--no-color` all drop colour and therefore drop the banner.
+//!    `--json`, `--yaml`, and `NO_COLOR`/`TERM=dumb`/`CI=true`/`--no-color`
+//!    all drop colour and therefore drop the banner.
 //! 3. Hook-protocol commands (`session init`, `checkpoint stop/reset/orphans`,
 //!    `qmd reindex`, and their hidden v3.0 aliases `session-init`/
 //!    `orphan-scan`/`qmd-reindex`) need deterministic stderr because Claude
@@ -374,10 +374,10 @@ impl HelpBannerEnv {
 /// Suppression precedence (any one disqualifies):
 /// 1. `--version` / `-V` — version-only intent, no banner.
 /// 2. `--quiet` / `-q` — explicit silence.
-/// 3. `--json` / `--yaml` / `--output <json|yaml|table|tsv>` — machine consumer.
+/// 3. `--json` / `--yaml` / `--output <json|yaml>` — machine consumer.
 /// 4. `--no-color` flag — explicit colour suppression.
 /// 5. Env says monochrome (`NO_COLOR` / `TERM=dumb` / `CI=<truthy>`).
-/// 6. Mode is not `Text { .. }` (Json/Yaml/Table/Tsv).
+/// 6. Mode is not `Text { .. }` (Json/Yaml).
 ///
 /// The colour bit on the resolved mode is NOT checked: `assert_cmd` pipes
 /// stdout in tests, which collapses the colour bit to `false`. Forcing
diff --git a/crates/onebrain-cli/src/legacy_output.rs b/crates/onebrain-cli/src/legacy_output.rs
index 8f4ea89..451db4f 100644
--- a/crates/onebrain-cli/src/legacy_output.rs
+++ b/crates/onebrain-cli/src/legacy_output.rs
@@ -26,9 +26,10 @@ pub struct SessionInitOutput {
 /// so fix the caller. `debug_assert!` catches the contract violation in
 /// debug builds.
 ///
-/// For the structured branches (`Json` / `Yaml` / `Table` / `Tsv`) this
-/// function is the single emit point; it keeps the JSON shape rules
-/// (compact vs. pretty) in one place.
+/// For the structured branches (`Json` / `Yaml`) this function is the single
+/// emit point; it keeps the JSON shape rules (compact vs. pretty) in one
+/// place. (v3.2.15: `Table` / `Tsv` variants dropped — both fell through to
+/// the JSON encoder unchanged.)
 ///
 /// **Error handling:** serialisation failures are surfaced via a stderr
 /// warning AND the function returns whatever string emerged (typically
diff --git a/crates/onebrain-cli/src/main.rs b/crates/onebrain-cli/src/main.rs
index 96a3217..0cc570e 100644
--- a/crates/onebrain-cli/src/main.rs
+++ b/crates/onebrain-cli/src/main.rs
@@ -98,18 +98,15 @@ fn main() {
 ///
 /// Text mode (default human) writes the v3.0-style `Error: <msg>` line to
 /// stderr — keeps the human-readable path unchanged. Structured modes
-/// (`--json` / `--yaml` / `--output table|tsv`) build a canonical envelope
+/// (`--json` / `--yaml`) build a canonical envelope
 /// (`ok: false`, `error: {code, message}`) and emit it on stdout so machine
 /// consumers always see one well-formed JSON document per invocation.
 ///
 /// R2-H2: structured-mode error envelopes are always rendered as JSON
-/// regardless of the requested format. Tsv and Table modes have no
-/// columnar slots for nested error fields (no `error.code` /
-/// `error.message` / `version` columns), so error envelopes are forced to
-/// Json regardless of requested mode. Forcing JSON guarantees a lossless
-/// canonical envelope on every structured invocation. `--yaml` is also
-/// forced to JSON for the error path so consumers don't need a
-/// format-switch on the error branch.
+/// regardless of the requested format. `--yaml` is forced to JSON for the
+/// error path so consumers don't need a format-switch on the error branch.
+/// (v3.2.15: `Table` / `Tsv` variants dropped from `OutputMode`; pre-3.2.15
+/// they would also have been forced to JSON here for the same reason.)
 ///
 /// R2-H3: when the error chain carries the `AlreadyReported` sentinel the
 /// envelope has been emitted already (e.g. `plugin update`'s partial
diff --git a/crates/onebrain-cli/src/output/mode.rs b/crates/onebrain-cli/src/output/mode.rs
index 4a495b5..d451a5e 100644
--- a/crates/onebrain-cli/src/output/mode.rs
+++ b/crates/onebrain-cli/src/output/mode.rs
@@ -45,7 +45,7 @@ impl OutputMode {
 /// deterministic unit tests.
 #[derive(Debug, Clone, Default)]
 pub struct TtyInputs {
-    /// `--output <fmt>` value from clap (`text|json|yaml|table|tsv`).
+    /// `--output <fmt>` value from clap (`text|json|yaml`).
     pub output_flag: String,
     /// `--json` shorthand.
     pub json_shortcut: bool,
diff --git a/crates/onebrain-cli/src/output/progress.rs b/crates/onebrain-cli/src/output/progress.rs
index f7be6ce..d412c46 100644
--- a/crates/onebrain-cli/src/output/progress.rs
+++ b/crates/onebrain-cli/src/output/progress.rs
@@ -24,11 +24,11 @@
 //!   2. [`OutputMode`] is `Text { color: true, .. }`, AND
 //!   3. not `--quiet`.
 //!
-//! In every other case — piped / non-TTY stdout, `--json` / `--yaml` /
-//! `--tsv` / `--table`, `--no-color`, `--quiet` — there is NO spinner, NO
-//! pacing, NO carriage-return redraw: the primitive just prints the final
-//! status lines (plain glyphs; ANSI colour only when the resolved mode still
-//! carries `color: true`, which it never does in any of those branches).
+//! In every other case — piped / non-TTY stdout, `--json` / `--yaml`,
+//! `--no-color`, `--quiet` — there is NO spinner, NO pacing, NO
+//! carriage-return redraw: the primitive just prints the final status lines
+//! (plain glyphs; ANSI colour only when the resolved mode still carries
+//! `color: true`, which it never does in any of those branches).
 //!
 //! The gating decision is made once by [`should_animate`] (a pure function
 //! over the same inputs `banner.rs` uses) and frozen into the renderer.

From 5566dee2c0f23c9e6c0f63658582fb6db8b3d733 Mon Sep 17 00:00:00 2001
From: Suppaseth Charoenkarnka <kengio@gmail.com>
Date: Thu, 28 May 2026 22:16:59 +0700
Subject: [PATCH 6/6] =?UTF-8?q?chore:=20v3.2.x=20final=20polish=20?=
 =?UTF-8?q?=E2=80=94=20binary=20size=20-39%,=20dedupe,=20dead=20code=20dro?=
 =?UTF-8?q?p?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round-2 cleanup pass on PR #57 before the v3.2.x final cut. Applied
high-ROI items from the three review streams (clean code / consistency /
binary footprint):

**Binary footprint (-39% release size)**

- Cargo.toml release profile: `opt-level = "z"` (was implicit 3) +
  `lto = "fat"` (was "thin"). Trimmed 5.4 MB → 3.3 MB. The CLI's hot
  paths are I/O-bound, so size-optimised codegen carries no measurable
  runtime hit for sub-second runs.

**Deduplication**

- `read_plugin_version`: hoisted from private `fn` in
  `onebrain-fs::vault_sync::orchestrate` to `pub fn` re-exported at the
  crate root. `onebrain-cli::v31::plugin_update` drops its duplicate
  helper and calls through. (Code-Simplifier finding 1.1.)
- `vault_sync::run_with(embedded, silent)` → `run_with(silent)`. The
  orchestrator only consults `embedded` on the `progress_writer = None`
  branch, and the silent path always sets the writer to a sink — the flag
  was structurally dead. (Code-Simplifier finding 1.4.)

**Dead code drop**

- `plugin_update_vault_detail`: dropped the unused `partial_failed: bool`
  parameter. Both callsites + the rustdoc decision-table updated.
  (Code-Simplifier finding 2.2.)
- `ProgressRenderer::set_step_delay`: demoted from `pub` to `pub(crate)`.
  Production paths only ever pass `None`; the seam exists for the
  cross-module animated-path tests. (Code-Simplifier finding 2.1.)

**Consistency**

- `OutputMode` enum: added rustdoc summary line naming the three
  remaining variants (Text/Json/Yaml). (Consistency finding M3.)
- `commands/vault_sync.rs`: added `use std::io;` so body uses
  `io::sink()` matching the rustdoc references. (Consistency finding M4.)

**Deferred to v3.3** (per binary-size reviewer):

- reqwest → ureq swap (kills the entire tokio/hyper/h2 async stack; ~700–900 KB
  saved but needs its own PR for review)
- serde_yaml (deprecated) → serde_yaml_ng (active fork; ~30–60 KB, drop-in)
- clap feature audit (`env` usage)

**Skipped** (per Consistency reviewer):

- M1 rename `run_silent`/`run_quiet` → `run_embedded` (cosmetic only;
  the cleanup above already shipped the semantic simplification)
- M2 naming-convention comment block (informational; defer)
- Renderer unification `render_plugin_update_inner` (~80 LOC reduction
  but cross-cuts the static/animated split — too risky for the final
  v3.2.x cut)

1281 passed; clippy clean; fmt clean. Release binary: 3.3 MB (was 5.4 MB).
---
 Cargo.toml                                    |  8 ++++-
 .../onebrain-cli/src/commands/vault_sync.rs   | 34 +++++++++++--------
 crates/onebrain-cli/src/output/mode.rs        | 10 ++++--
 crates/onebrain-cli/src/output/progress.rs    | 21 ++++++------
 crates/onebrain-cli/src/v31/dispatch.rs       | 17 ++++------
 crates/onebrain-cli/src/v31/plugin_update.rs  | 23 ++-----------
 crates/onebrain-fs/src/lib.rs                 |  4 +--
 crates/onebrain-fs/src/vault_sync/mod.rs      |  2 +-
 .../onebrain-fs/src/vault_sync/orchestrate.rs | 13 +++++--
 9 files changed, 65 insertions(+), 67 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index a895a7b..bf50fbd 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -83,7 +83,13 @@ pretty_assertions = "1"
 mockito           = "1"
 
 [profile.release]
+# v3.2.15: switched from `opt-level = 3` (implicit default) + `lto = "thin"` to
+# `opt-level = "z"` + `lto = "fat"` for the v3.2.x final cut. Trims ~20–30%
+# off the release binary (~5.4 MB → ~3.8–4.3 MB). The CLI's hot paths are
+# I/O-bound (HTTP fetches, file IO, regex scans on note-search), so size-
+# optimised codegen carries no measurable runtime hit for sub-second runs.
+opt-level   = "z"
 strip       = "symbols"
-lto         = "thin"
+lto         = "fat"
 codegen-units = 1
 panic       = "abort"
diff --git a/crates/onebrain-cli/src/commands/vault_sync.rs b/crates/onebrain-cli/src/commands/vault_sync.rs
index aae1cad..9938931 100644
--- a/crates/onebrain-cli/src/commands/vault_sync.rs
+++ b/crates/onebrain-cli/src/commands/vault_sync.rs
@@ -7,6 +7,7 @@ use anyhow::{anyhow, Context, Result};
 use onebrain_core::find_vault_root;
 use onebrain_fs::{run_vault_sync, VaultSyncOptions};
 use std::env;
+use std::io;
 use std::path::PathBuf;
 
 /// Entry point — returns `Ok(0)` on success, `Ok(1)` on any critical failure.
@@ -27,27 +28,29 @@ use std::path::PathBuf;
 /// to occasionally duplicate one line than leave the user with a silent
 /// non-zero exit.
 pub fn run(vault_root_override: Option<PathBuf>, branch: Option<String>) -> Result<i32> {
-    run_with(vault_root_override, branch, false, false)
+    run_with(vault_root_override, branch, false)
 }
 
-/// Same as [`run`] but suppresses the orchestrator's "OneBrain Vault Sync"
-/// intro/outro frame AND routes the per-step progress reporter to
-/// `io::sink()` — so neither the framed banner nor the per-step `▸ <label>`
-/// lines leak. Used by `onebrain plugin update` (v3.2.15+), which renders
-/// its own framed doctor-style report. The framed report's animated spinner
-/// is the only progress signal the user sees, matching `doctor`/`update`.
+/// Same as [`run`] but routes the per-step progress reporter to
+/// `std::io::sink()` — so neither the "OneBrain Vault Sync" intro/outro
+/// frame nor the per-step `▸ <label>` lines leak. Used by `onebrain plugin
+/// update` (v3.2.15+), which renders its own framed doctor-style report;
+/// the framed report's animated spinner is the only progress signal the
+/// user sees, matching `doctor`/`update`.
 ///
 /// (v3.2.13 introduced `run_embedded` for the intro-only suppression; v3.2.15
 /// folded that into the silent path because no remaining caller wanted the
-/// in-between "embedded but with step lines" mode.)
+/// in-between "embedded but with step lines" mode. v3.2.15 round-2 also
+/// dropped the now-dead `embedded` flag from the inner shape — the
+/// orchestrator only consults it when `progress_writer` is `None`, and the
+/// silent path always sets the writer to a sink.)
 pub fn run_silent(vault_root_override: Option<PathBuf>, branch: Option<String>) -> Result<i32> {
-    run_with(vault_root_override, branch, true, true)
+    run_with(vault_root_override, branch, true)
 }
 
 fn run_with(
     vault_root_override: Option<PathBuf>,
     branch: Option<String>,
-    embedded: bool,
     silent: bool,
 ) -> Result<i32> {
     // Bun v2.3.3 parity: optional positional `<vault_root>` lets the caller
@@ -73,10 +76,12 @@ fn run_with(
 
     // `silent` overrides any TTY-vs-non-TTY heuristic: orchestrator routes
     // `progress_writer = Some(io::sink())` through `PlainProgress`, which
-    // discards every step line. `embedded` is still threaded so the build
-    // chooses the correct progress impl when `silent = false`.
-    let progress_writer: Option<Box<dyn std::io::Write + Send>> = if silent {
-        Some(Box::new(std::io::sink()))
+    // discards every step line. The orchestrator's `embedded` flag only
+    // affects the `progress_writer = None` branch, so leaving it at default
+    // (`false`) when silent is fine — the sink doesn't care which mode
+    // claims to write to it.
+    let progress_writer: Option<Box<dyn io::Write + Send>> = if silent {
+        Some(Box::new(io::sink()))
     } else {
         None
     };
@@ -84,7 +89,6 @@ fn run_with(
         vault_root_path.as_path(),
         VaultSyncOptions {
             branch,
-            embedded,
             progress_writer,
             ..VaultSyncOptions::default()
         },
diff --git a/crates/onebrain-cli/src/output/mode.rs b/crates/onebrain-cli/src/output/mode.rs
index d451a5e..a3012ad 100644
--- a/crates/onebrain-cli/src/output/mode.rs
+++ b/crates/onebrain-cli/src/output/mode.rs
@@ -10,9 +10,13 @@
 
 use std::io::IsTerminal;
 
-/// Resolved output mode for the current invocation. Each command renders
-/// according to this; the dispatcher in [`super::dispatcher`] picks the
-/// serializer.
+/// Resolved output mode for the current invocation. Three variants: `Text`
+/// (default, TTY-friendly), `Json` (canonical envelope), `Yaml` (same
+/// envelope serialised as YAML). Each command renders according to this;
+/// the dispatcher in [`super::dispatcher`] picks the serializer.
+///
+/// v3.2.15 dropped `Table` and `Tsv` — both fell through to the JSON
+/// encoder unchanged for every command. See the inline comment below.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum OutputMode {
     /// Default — TTY-friendly text. `color` and `pretty` already reflect the
diff --git a/crates/onebrain-cli/src/output/progress.rs b/crates/onebrain-cli/src/output/progress.rs
index d412c46..121fd05 100644
--- a/crates/onebrain-cli/src/output/progress.rs
+++ b/crates/onebrain-cli/src/output/progress.rs
@@ -271,18 +271,17 @@ impl<W: Write> ProgressRenderer<W> {
         }
     }
 
-    /// Pin the per-step pacing to a fixed duration. Production callers leave
-    /// the override unset so the renderer falls back to [`random_step_delay`]
-    /// (800–2000ms jitter).
+    /// Pin the per-step pacing to a fixed duration. **Test seam only**: production
+    /// callers leave the override unset so the renderer falls back to
+    /// [`random_step_delay`] (800–2000ms jitter).
     ///
-    /// v3.2.14: tests for `plugin update`'s animated renderer pass
-    /// `Duration::ZERO` so the animated branch — spinner frame + `\r` clear +
-    /// resolved line — runs deterministically without sleeping for the
-    /// production band. Previously gated behind `#[cfg(test)]`; promoted to a
-    /// first-class crate seam now that an additional command reuses the same
-    /// animation infrastructure and needs to inject the override at the
-    /// dispatch boundary (not from inside a test mod).
-    pub fn set_step_delay(&mut self, delay: Duration) {
+    /// Exposed `pub(crate)` (not `pub`) so the cross-module animated-path tests
+    /// in `v31::dispatch::tests` can inject `Duration::ZERO` to exercise the
+    /// animated branch without sleeping. v3.2.14 promoted it from
+    /// `#[cfg(test)]` to crate-visible; v3.2.15 trimmed it back to
+    /// `pub(crate)` after the production path confirmed it always passes
+    /// `None`.
+    pub(crate) fn set_step_delay(&mut self, delay: Duration) {
         self.step_delay_override = Some(delay);
     }
 
diff --git a/crates/onebrain-cli/src/v31/dispatch.rs b/crates/onebrain-cli/src/v31/dispatch.rs
index 57fb0ef..4159d2d 100644
--- a/crates/onebrain-cli/src/v31/dispatch.rs
+++ b/crates/onebrain-cli/src/v31/dispatch.rs
@@ -638,7 +638,6 @@ pub(crate) fn render_plugin_update_animated_to<W: std::io::Write>(
     let vault_detail = plugin_update_vault_detail(
         report.vault_synced,
         report.dry_run,
-        partial_failed,
         report.version_before.as_deref(),
         report.version_after.as_deref(),
     );
@@ -733,19 +732,19 @@ pub(crate) fn render_plugin_update_animated_to<W: std::io::Write>(
 /// exactly one place.
 ///
 /// Decision table (v3.2.15):
-/// - partial-failed AND step ran  → version-aware `vX → vY` / `vX · up-to-date`
-///   / `installed vY` / fallback `done` (the plist step is what failed; the
-///   vault row tells the user what version it ended up on)
-/// - partial-failed AND step skipped → `skipped`
 /// - dry-run with known current → `current vX · skipped`
 /// - dry-run unknown → `skipped`
+/// - step didn't run → `skipped`
 /// - happy path with versions → `vX → vY` / `vX · up-to-date` / `installed vY`
 /// - happy path no version info → `done` (back-compat with pre-3.2.15)
-/// - step didn't run → `skipped`
+///
+/// Partial-failure cases aren't branched here: a later-step failure doesn't
+/// change what version landed on disk during the vault-sync step, so the row
+/// still reports the same delta. The verdict footer + per-step glyph carry
+/// the failure signal.
 fn plugin_update_vault_detail(
     vault_synced: bool,
     dry_run: bool,
-    partial_failed: bool,
     before: Option<&str>,
     after: Option<&str>,
 ) -> String {
@@ -758,9 +757,6 @@ fn plugin_update_vault_detail(
     if !vault_synced {
         return "skipped".to_string();
     }
-    // Vault step ran. Partial failure on a later step doesn't change what
-    // version landed on disk, so the row still reports the delta here.
-    let _ = partial_failed; // (kept in the signature for future per-step blame)
     match (before, after) {
         (Some(a), Some(b)) if a == b => format!("v{a} · up-to-date"),
         (Some(a), Some(b)) => format!("v{a} → v{b}"),
@@ -981,7 +977,6 @@ where
     let vault_detail = plugin_update_vault_detail(
         d.vault_synced(),
         d.dry_run(),
-        partial_failed,
         d.version_before(),
         d.version_after(),
     );
diff --git a/crates/onebrain-cli/src/v31/plugin_update.rs b/crates/onebrain-cli/src/v31/plugin_update.rs
index b2df019..bd9af15 100644
--- a/crates/onebrain-cli/src/v31/plugin_update.rs
+++ b/crates/onebrain-cli/src/v31/plugin_update.rs
@@ -8,28 +8,9 @@
 
 use crate::v31::hook_rewriter::{self, RewriteWarning};
 use anyhow::{Context, Result};
+use onebrain_fs::read_plugin_version;
 use onebrain_fs::register_hooks::settings::settings_path;
-use std::path::{Path, PathBuf};
-
-/// Read the plugin version from `<vault>/.claude/plugins/onebrain/.claude-plugin/plugin.json`.
-/// Returns `None` on the well-formed "no plugin installed yet" / "manifest
-/// missing the `version` field" paths so the framed renderer can fall back
-/// to the generic `done` / `skipped` detail strings; the orchestrator's own
-/// `read_plugin_version` in `onebrain-fs::vault_sync::orchestrate` does the
-/// same for the post-extract path inside the sync flow.
-fn read_plugin_version(vault_root: &Path) -> Option<String> {
-    let path = vault_root
-        .join(".claude")
-        .join("plugins")
-        .join("onebrain")
-        .join(".claude-plugin")
-        .join("plugin.json");
-    let text = std::fs::read_to_string(&path).ok()?;
-    let v: serde_json::Value = serde_json::from_str(&text).ok()?;
-    v.get("version")
-        .and_then(serde_json::Value::as_str)
-        .map(str::to_string)
-}
+use std::path::PathBuf;
 
 #[derive(Debug, Default)]
 pub struct PluginUpdateReport {
diff --git a/crates/onebrain-fs/src/lib.rs b/crates/onebrain-fs/src/lib.rs
index 257bf4b..efaeb7c 100644
--- a/crates/onebrain-fs/src/lib.rs
+++ b/crates/onebrain-fs/src/lib.rs
@@ -30,6 +30,6 @@ pub use run_skill::{
 };
 pub use update::{run_update, UpdateOptions, UpdateResult};
 pub use vault_sync::{
-    build_tar_spawn_overrides, normalize_path, resolve_branch, run_vault_sync, VaultSyncOptions,
-    VaultSyncResult,
+    build_tar_spawn_overrides, normalize_path, read_plugin_version, resolve_branch, run_vault_sync,
+    VaultSyncOptions, VaultSyncResult,
 };
diff --git a/crates/onebrain-fs/src/vault_sync/mod.rs b/crates/onebrain-fs/src/vault_sync/mod.rs
index bafc184..9c49c53 100644
--- a/crates/onebrain-fs/src/vault_sync/mod.rs
+++ b/crates/onebrain-fs/src/vault_sync/mod.rs
@@ -37,6 +37,6 @@ mod types;
 
 pub use branch::resolve_branch;
 pub use download::build_tar_spawn_overrides;
-pub use orchestrate::run_vault_sync;
+pub use orchestrate::{read_plugin_version, run_vault_sync};
 pub use pin::normalize_path;
 pub use types::{VaultSyncOptions, VaultSyncResult};
diff --git a/crates/onebrain-fs/src/vault_sync/orchestrate.rs b/crates/onebrain-fs/src/vault_sync/orchestrate.rs
index bb4a20f..1417d18 100644
--- a/crates/onebrain-fs/src/vault_sync/orchestrate.rs
+++ b/crates/onebrain-fs/src/vault_sync/orchestrate.rs
@@ -211,8 +211,17 @@ fn read_update_channel(vault_root: &Path) -> Option<String> {
         .map(str::to_string)
 }
 
-fn read_plugin_version(extracted_dir: &Path) -> Option<String> {
-    let path = extracted_dir.join(".claude/plugins/onebrain/.claude-plugin/plugin.json");
+/// Read the `version` field from `<base>/.claude/plugins/onebrain/.claude-plugin/plugin.json`.
+/// `base` is either the extracted-tarball directory (during a sync) or an
+/// installed vault root. Returns `None` for any well-formed "not installed /
+/// file missing / version field missing / malformed JSON" case so callers
+/// can fall back to generic detail strings without distinguishing the four.
+///
+/// v3.2.15: hoisted from a `fn` (orchestrator-private) to `pub fn` so
+/// `onebrain-cli`'s `plugin_update::run` can reuse it on the installed-vault
+/// side without duplicating the path-join + parse logic.
+pub fn read_plugin_version(base: &Path) -> Option<String> {
+    let path = base.join(".claude/plugins/onebrain/.claude-plugin/plugin.json");
     let text = fs::read_to_string(&path).ok()?;
     let v: serde_json::Value = serde_json::from_str(&text).ok()?;
     v.get("version")