EPIC: Phase 7 — whole-app polish, docs, and release

[dyoung522]

Bring the whole app to a polished, releasable state before starting the next round of feature work. This is the roadmap's final phase — Phase 7 from the TUI implementation plan (docs/plans/2026-04-28-tui-implementation.md) widened, by decision, from TUI-only to a whole-app polish/docs/release pass. It also absorbs the remaining deliverables of the v1.0-era umbrellas #10 (docs) and #11 (tests), which are closed as superseded by this epic.

Guiding rule: no new features. Everything in scope is hardening, cleanup, test coverage, or documentation of behavior that already shipped. Feature work — including the two PRD Phase 7 bullets that are really features (game auto-detection, configurable keybindings) — is explicitly deferred until this epic closes.

Sub-issues

TUI polish & hardening

• TUI: short/narrow terminal hardening and deferred polish #42 — short/narrow terminal hardening (clamp-to-height pass across all views, zero-width column handling, snapshot harness for every screen). The anchor issue for the terminal-size class: Aggregate search: deferred review findings from PR #57 #58 and TUI Phase 6a: deferred polish from per-task and final reviews #68 each fold display items into it. Shipped v1.17.1 (PR fix(tui): terminal hardening — clamp/window every screen to its height budget (#42) #105).
• TUI Phase 6a: deferred polish from per-task and final reviews #68 — Phase 6a deferred polish (DRY consolidations, small UX fixes, test-coverage gaps). Shipped v1.18.0 (PR feat(tui): polish batch — no-color, updated marker, live dashboard data, Phase 6a sweep (#68 #77 #91 #106) #107).
• TUI: mark recently-updated mods in the Installed Mods list #77 — transient marker for recently-updated mods in the Installed Mods list. Shipped v1.18.0 (PR feat(tui): polish batch — no-color, updated marker, live dashboard data, Phase 6a sweep (#68 #77 #91 #106) #107).
• TUI: --no-color flag is silently ignored (NO_COLOR env already works) #91 — make the root --no-color flag actually reach the TUI; regression tests for both NO_COLOR env and flag paths. This issue is Phase 7 verification task 5, discovered failing. Shipped v1.18.0 (PR feat(tui): polish batch — no-color, updated marker, live dashboard data, Phase 6a sweep (#68 #77 #91 #106) #107).
• TUI: dashboard placeholders show no meaningful data (updates ?, conflicts, Last deploy: ?) #106 — dashboard placeholders show no meaningful data (Last deploy: ? hardcoded, conflicts count stale--1 despite GetProfileConflicts existing, updates count never refreshed after a check). User-flagged must-have (2026-07-26). Shipped v1.18.0 (PR feat(tui): polish batch — no-color, updated marker, live dashboard data, Phase 6a sweep (#68 #77 #91 #106) #107); cross-session updates-count persistence deferred by design decision (see issue).
• TUI: nav bar overflows at 80 cols — sixth screen entry truncated to an ellipsis #108 — nav bar overflows at 80 cols: sixth screen entry truncated to an ellipsis (pre-existing since Phase 6b, surfaced by the TUI: --no-color flag is silently ignored (NO_COLOR env already works) #91 marker work; needs a narrow-width nav compression strategy)
• TUI: size search fetches to the window instead of the fixed 10-per-source page #111 — size search fetches to the window instead of the fixed 10-per-source page (Tier 1: height-derived page size; Tier 2 pairs with CLI: search --limit N should page per-source until N results or exhaustion #109). User-flagged (2026-07-27).

Whole-app hygiene (partial adoptees, accepted to make this a full-app pass)

• Custom sources: deferred review findings from PR #51 #52 — custom-sources deferred findings: directory-scan symlink bug, name over-trimming, case-sensitive ModInfo.xml, swallowed resolveDependencies errors, missing tests, CLI cosmetics
• Aggregate search: deferred review findings from PR #57 #58 — aggregate-search deferred findings, polish slice (pagination overshoot, honesty notice when no source supports search, prototype warning coverage, cosmetic/test items). The --limit N multi-page fetch loop is feature-ish — do it last within Aggregate search: deferred review findings from PR #57 #58 or split it out if it drags. The "do not close until noted on TUI roadmap: CLI-parity gaps assigned to Phases 5/6 #37" gate is satisfied: capability-gated TUI mutations shipped in v1.12.0.
• lmm install --version is a dead flag (parsed, never read) #93 — interim fix only (SHIPPED v1.18.2 — guard live; issue stays open under EPIC EPIC: Version locking — pin mods to specific versions #98 for the real resolver): make the dead lmm install --version flag reject with a clear "not yet supported" error instead of silently installing latest. The real implementation belongs to EPIC EPIC: Version locking — pin mods to specific versions #98 (Version→file resolution; make ModReference.Version authoritative #96/Version lock/unlock surface (CLI + TUI) #97); coordinate there before closing lmm install --version is a dead flag (parsed, never read) #93.

Documentation (folded in from #10, re-audited against v1.17.x reality)

• Man pages for the commands that have none: lmm tui, lmm update, lmm import, lmm source (existing pages: lmm, conflicts, deploy, game, install, list, mod, profile, purge, search)
• Currency audit of the existing man pages and docs/configuration.md against current behavior (custom sources, update --json, capability gating, themes/keybindings)
• README pass: CLI reference completeness, lmm tui section (keybindings, themes, prototype mode)
• Documented exit codes; --help completeness/consistency sweep
• Document actual link_method precedence (game/global; profile-level currently ignored — see Profile-level link_method is documented but ignored during deploy/switch #81, fixed separately) so docs stop overpromising

Release hygiene (folded in from #11 + plan tasks)

• Final test-coverage audit against the layer targets (Domain 90%, Storage 85%, Core 80%, Source 75%, CLI key paths); fill the worst gaps, don't chase numbers
• -race in the test run/CI if not already present
• go fmt / go vet / go test ./... / trunk check clean
• CHANGELOG + version bump per repo convention (likely MINOR given the accumulated changes)

Explicitly out of scope (deferred, not forgotten)

Cluster	Issues	Why deferred
Version locking	#98 (+ #92–#97)	Its own epic with internal sequencing
TUI feature parity	#74, #86, #87	New screens/interactions, not polish
Source architecture	#76, #75	#76 wants a design doc; #75 is soft-blocked on it
Decision-blocked	#79, #85	Stalled on design decisions, not effort
Standalone bug	#81	Real fix spans ~15 call sites + migration decision; docs note lands here, fix lands there
Independent enhancements	#27, #28	Schedule freely after the epic
PRD "Polish" features	game auto-detection, configurable keybindings	Features wearing a polish costume; future roadmap

Suggested order

1. TUI: short/narrow terminal hardening and deferred polish #42 first done (v1.17.1)
2. TUI Phase 6a: deferred polish from per-task and final reviews #68 + TUI: mark recently-updated mods in the Installed Mods list #77 + TUI: --no-color flag is silently ignored (NO_COLOR env already works) #91 + TUI: dashboard placeholders show no meaningful data (updates ?, conflicts, Last deploy: ?) #106 (small TUI batch) done (v1.18.0)
3. Custom sources: deferred review findings from PR #51 #52 + Aggregate search: deferred review findings from PR #57 #58 (source/search hygiene batch); TUI: nav bar overflows at 80 cols — sixth screen entry truncated to an ellipsis #108 can ride along or follow
4. lmm install --version is a dead flag (parsed, never read) #93 interim guard
5. Docs pass
6. Coverage audit + release tail (fmt/vet/test/trunk, CHANGELOG, version bump)

Exit criteria: all sub-issues closed or explicitly re-deferred with reasons, docs current, tests/vet/trunk clean, version bumped — and the open-issue count substantially whittled down.