---
name: v0121-help-md
description: "v0.12.1 help-markdown render feature built+committed on branch v0.12.1-help-md, awaiting merge into v0.12.1-lifecycle before release"
metadata: 
  node_type: memory
  type: project
  originSessionId: bfe20bf0-7829-4d00-b1b1-052a9c66e85b
---

Operator (2026-06-18) noticed `spt --help` leaks literal MD markers (`**ctrl-b**`, stray backticks) — clap prints doc-comments verbatim. Asked to build the fix in the spt-core-doyle worktree + fold into v0.12.1 before release.

BUILT + COMMITTED @d4241f9 on branch **v0.12.1-help-md** (off cf5eab4, in worktree spt-core-doyle). New `crates/spt/src/helpfmt.rs` (pure `render` transform: `**bold**`→ANSI bold, `` `code` ``→cyan, `[text](url)`→text; markers stripped either way). Wired at the single chokepoint: `cli::run` switched `get_matches`→`try_get_matches` + `emit_clap_error` intercepts clap `DisplayHelp`; `bare_invocation` uses `render_help()`. Color gated: real tty AND not suppressed (NO_COLOR / CLICOLOR=0 off, CLICOLOR_FORCE on) — pipe/CI → strip-only so machine help is byte-identical. CSI escapes passed through; markers never span a newline. Mints+satisfies **REQ-CLI-HELP-MARKDOWN** [impl,unit].

FOLLOW-UP @ec162c7 (operator asked "applies to ALL help branches?"): YES — intercept at top-level try_get_matches catches every subcommand's bubbled DisplayHelp. BUT found+fixed an edge: clap `wrap_help` splits a long span mid-text (`\n`+indent) so `api`/`shell` help still leaked literal markers; `find_span` now crosses a SOFT wrap (newline+continuation indent) but refuses a hard break (`\n\n`/col-0). Verified literal=0 across all 12 branches smoked.

GATES GREEN: 11 helpfmt units + full spt bin suite (189) pass, workspace clippy -D warnings clean (fixed a sliced_string_as_bytes lint), traceable EXIT=0. Verified live: forced→`^[[1mctrl-b^[[22m`+cyan `d`; piped→clean. Branch now: d4241f9 (feature) + ec162c7 (soft-wrap).

**MERGED @a461dc4** into v0.12.1-lifecycle (2026-06-18, after all 4 waves gated, HEAD was @9b79a54). Re-dry-run vs E1 HEAD was clean (cli.rs + traceable-reqs.toml auto-merge, zero conflicts). Merged-tree verified: build clean, 14 helpfmt+cli units, all --help branches literal=0, traceable EXIT=0 (both REQs), clippy clean. CAUGHT INTERACTION: docs-drift — help-md strips MD markers from --help, so E1's pre-help-md reference.md regen went stale → `xtask gen` regen'd it (179/179 line swap, markers stripped) + committed @54f167c. reference.md embeds help in ```text fences (mdbook never rendered the markers anyway) so stripping = strict improvement, no downgrade. `xtask check: OK`. v0.12.1 BUILD COMPLETE — ready for changelog + deployah release. NOT auto-merged: primary worktree has uncommitted L1 lifecycle work + a traceable-reqs.toml mod that COLLIDES with help-md's traceable-reqs.toml addition. Merge after the lifecycle batch commits (resolve the traceable-reqs.toml union — both just append distinct [[requirements]]). See [[v0121-realharness-reopen]].