@nemus-cli/nemus 0.4.0 → 0.8.0

package/src/utils/config-schema.ts

@@ -0,0 +1,112 @@
+import { UserConfig, CONFIG_DEFAULTS } from './config';
+
+/**
+ * Declarative schema for the non-interactive `nemus config get/set` command.
+ * Every writable UserConfig field is described here with its type + allowed
+ * values, so `set` can validate/coerce a string argument and `get`/`list` can
+ * enumerate keys. Kept as pure data + pure functions so it's fully unit-tested
+ * without touching disk. Keep this in sync with the UserConfig interface — the
+ * `satisfies` check below fails the build if a key is misspelled.
+ */
+export type ConfigKey = keyof UserConfig;
+
+type FieldSpec =
+  | { type: 'string'; allowEmpty?: boolean; describe: string }
+  | { type: 'boolean'; describe: string }
+  | { type: 'enum'; values: readonly string[]; describe: string };
+
+const AGENT_VALUES = ['claude', 'pi', 'opencode', 'codex', 'gemini'] as const;
+
+export const CONFIG_SCHEMA = {
+  workspacesDir: { type: 'string', describe: 'Directory where workspaces are created' },
+  githubOrg: { type: 'string', allowEmpty: true, describe: 'Default GitHub org for repo lookups' },
+  cloneProtocol: { type: 'enum', values: ['ssh', 'https'], describe: 'Protocol used to clone repos' },
+  aiAgent: {
+    type: 'enum',
+    values: [...AGENT_VALUES, 'both', 'auto'],
+    describe: 'AI agent(s) to integrate with',
+  },
+  primaryAgent: {
+    type: 'enum',
+    values: [...AGENT_VALUES, 'auto'],
+    describe: 'Agent launched when opening a workspace',
+  },
+  autoLaunchClaude: { type: 'boolean', describe: 'Auto-launch the agent after creating a workspace' },
+  generateClaudeContext: { type: 'boolean', describe: 'Generate agent context files (AGENTS.md)' },
+  installMcp: { type: 'boolean', describe: 'Install the MCP server during configure' },
+  piWorkspaceInputStatus: { type: 'boolean', describe: "Show workspace status in Pi's input area" },
+  claudeWorkspaceStatusLine: { type: 'boolean', describe: "Show workspace table in Claude's status line" },
+  autoReportBugs: { type: 'boolean', describe: 'Auto-file a GitHub issue when a command crashes' },
+} satisfies Record<ConfigKey, FieldSpec>;
+
+export const CONFIG_KEYS = Object.keys(CONFIG_SCHEMA).sort() as ConfigKey[];
+
+const TRUE_WORDS = new Set(['true', '1', 'yes', 'on', 'y']);
+const FALSE_WORDS = new Set(['false', '0', 'no', 'off', 'n']);
+
+/** True if `key` is a writable config key. */
+export function isConfigKey(key: string): key is ConfigKey {
+  return Object.prototype.hasOwnProperty.call(CONFIG_SCHEMA, key);
+}
+
+export type ParseResult =
+  | { ok: true; value: UserConfig[ConfigKey] }
+  | { ok: false; error: string };
+
+/** Validate + coerce a raw string for `key` into the field's typed value. */
+export function parseConfigValue(key: ConfigKey, raw: string): ParseResult {
+  const spec: FieldSpec = CONFIG_SCHEMA[key];
+  if (spec.type === 'boolean') {
+    const v = raw.trim().toLowerCase();
+    if (TRUE_WORDS.has(v)) return { ok: true, value: true };
+    if (FALSE_WORDS.has(v)) return { ok: true, value: false };
+    return { ok: false, error: `${key} expects a boolean (true/false); got "${raw}"` };
+  }
+  if (spec.type === 'enum') {
+    // Enum values are all lowercase, so normalize input like booleans do —
+    // `HTTPS` / ` https ` should resolve to the canonical value, not fail.
+    const v = raw.trim().toLowerCase();
+    if ((spec.values as readonly string[]).includes(v)) {
+      return { ok: true, value: v as UserConfig[ConfigKey] };
+    }
+    return { ok: false, error: `${key} must be one of: ${spec.values.join(', ')}; got "${raw}"` };
+  }
+  // string: trim surrounding whitespace (a stray space in a path/org is almost
+  // always a mistake), but preserve case.
+  const trimmed = raw.trim();
+  if (!spec.allowEmpty && trimmed === '') {
+    return { ok: false, error: `${key} cannot be empty` };
+  }
+  return { ok: true, value: trimmed };
+}
+
+/** Apply a `set` to a config object, returning a NEW config or an error. Pure. */
+export function applyConfigSet(
+  current: UserConfig,
+  key: string,
+  raw: string,
+): { ok: true; next: UserConfig; value: UserConfig[ConfigKey] } | { ok: false; error: string } {
+  if (!isConfigKey(key)) {
+    return { ok: false, error: `Unknown config key "${key}". Run "nemus config list" to see valid keys.` };
+  }
+  const parsed = parseConfigValue(key, raw);
+  if (!parsed.ok) return parsed;
+  return { ok: true, next: { ...current, [key]: parsed.value }, value: parsed.value };
+}
+
+/** Reset a key to its default value, returning a NEW config or an error. Pure. */
+export function applyConfigUnset(
+  current: UserConfig,
+  key: string,
+): { ok: true; next: UserConfig; value: UserConfig[ConfigKey] } | { ok: false; error: string } {
+  if (!isConfigKey(key)) {
+    return { ok: false, error: `Unknown config key "${key}". Run "nemus config list" to see valid keys.` };
+  }
+  const value = CONFIG_DEFAULTS[key];
+  return { ok: true, next: { ...current, [key]: value }, value };
+}
+
+/** Render a config value for plain (scriptable) stdout output. */
+export function formatConfigValue(value: unknown): string {
+  return typeof value === 'boolean' ? String(value) : String(value ?? '');
+}

package/src/utils/config.ts

@@ -67,7 +67,7 @@ export interface UserConfig {
   autoReportBugs: boolean;
 }
 
-const DEFAULTS: UserConfig = {
+export const CONFIG_DEFAULTS: UserConfig = {
   workspacesDir: path.join(HOME_DIR, 'workspaces'),
   githubOrg: '',
   autoLaunchClaude: true,
@@ -81,6 +81,9 @@ const DEFAULTS: UserConfig = {
   autoReportBugs: false,
 };
 
+// Internal alias retained for the many references below.
+const DEFAULTS = CONFIG_DEFAULTS;
+
 function loadConfigFileSync(): Partial<UserConfig> {
   try {
     const content = fs.readFileSync(CONFIG_FILE, 'utf-8');

package/src/utils/global-flags.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Command } from 'commander';
+import { applyGlobalFlags } from './global-flags';
+
+const spies = () => ({ setColorEnabled: vi.fn(), setQuiet: vi.fn() });
+
+// Mirror the real root-program global options so we test what commander actually
+// parses (esp. bundled short flags), not a hand-built opts object.
+const rootOpts = (argv: string[]) => {
+  const p = new Command();
+  p.option('-y, --yes', '').option('-q, --quiet', '').option('--no-color', '');
+  p.command('list').action(() => {});
+  p.parse(['node', 'nemus', 'list', ...argv]);
+  return p.opts();
+};
+
+describe('applyGlobalFlags', () => {
+  it('does nothing by default (color on, not quiet)', () => {
+    const d = spies();
+    applyGlobalFlags(rootOpts([]), d);
+    expect(d.setColorEnabled).not.toHaveBeenCalled();
+    expect(d.setQuiet).not.toHaveBeenCalled();
+  });
+
+  it('--no-color disables color', () => {
+    const d = spies();
+    applyGlobalFlags(rootOpts(['--no-color']), d);
+    expect(d.setColorEnabled).toHaveBeenCalledWith(false);
+  });
+
+  it('--quiet enables quiet', () => {
+    const d = spies();
+    applyGlobalFlags(rootOpts(['--quiet']), d);
+    expect(d.setQuiet).toHaveBeenCalledWith(true);
+  });
+
+  it('bundled short flags (-yq) still enable quiet', () => {
+    const d = spies();
+    const opts = rootOpts(['-yq']);
+    expect(opts.quiet).toBe(true); // commander expands the bundle
+    applyGlobalFlags(opts, d);
+    expect(d.setQuiet).toHaveBeenCalledWith(true);
+  });
+});

package/src/utils/global-flags.ts

@@ -0,0 +1,28 @@
+import { setColorEnabled } from './colors';
+import { setQuiet } from './logger';
+
+/** Global options commander parses off the root program. */
+export interface GlobalFlagOpts {
+  /** commander's negatable `--no-color` yields `color: false` when passed. */
+  color?: boolean;
+  /** `-q`/`--quiet`, including bundled short forms like `-yq`. */
+  quiet?: boolean;
+}
+
+/**
+ * Apply parsed global flags to process-wide state. Kept pure over injected
+ * setters so it's testable without commander — the `preAction` hook in
+ * program.ts is a one-line call into this. Only ever turns features OFF here:
+ * color defaults on (and env/TTY detection already ran at import), so we act
+ * solely on an explicit `--no-color` (`color === false`).
+ */
+export function applyGlobalFlags(
+  opts: GlobalFlagOpts,
+  deps: { setColorEnabled: (on: boolean) => void; setQuiet: (on: boolean) => void } = {
+    setColorEnabled,
+    setQuiet,
+  },
+): void {
+  if (opts.color === false) deps.setColorEnabled(false);
+  if (opts.quiet) deps.setQuiet(true);
+}

package/src/utils/logger.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { logInfo, logSuccess, logStep, logWarning, logError, setQuiet, isQuiet } from './logger';
+
+afterEach(() => {
+  setQuiet(false);
+  vi.restoreAllMocks();
+});
+
+describe('--quiet (setQuiet)', () => {
+  it('suppresses info/success/step but keeps warnings + errors', () => {
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    setQuiet(true);
+    expect(isQuiet()).toBe(true);
+
+    logInfo('i');
+    logSuccess('s');
+    logStep('st');
+    expect(err).not.toHaveBeenCalled(); // routine progress silenced
+
+    logWarning('w');
+    logError('e');
+    expect(err).toHaveBeenCalledTimes(2); // warnings + errors still shown
+    expect(err.mock.calls.map((c) => String(c[0])).join('\n')).toMatch(/w[\s\S]*e|e[\s\S]*w/);
+  });
+
+  it('emits everything when not quiet', () => {
+    const err = vi.spyOn(console, 'error').mockImplementation(() => {});
+    setQuiet(false);
+    logInfo('i');
+    logSuccess('s');
+    logStep('st');
+    logWarning('w');
+    logError('e');
+    expect(err).toHaveBeenCalledTimes(5);
+  });
+});

package/src/utils/logger.ts

@@ -5,6 +5,14 @@ import { colors, colorize } from './colors';
 // --json | jq …) and for non-TTY consumers. Use `outputJson`/stdout for data.
 const logStream = (line: string): void => console.error(line);
 
+// `--quiet` silences routine progress (info/success/step) while KEEPING warnings
+// and errors, which a script or human still needs to see.
+let quiet = false;
+export const setQuiet = (on: boolean): void => {
+  quiet = on;
+};
+export const isQuiet = (): boolean => quiet;
+
 const getTimestamp = (): string => {
   const now = new Date();
   return now.toLocaleTimeString('en-US', {
@@ -16,10 +24,12 @@ const getTimestamp = (): string => {
 };
 
 export const logInfo = (message: string): void => {
+  if (quiet) return;
   logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${message}`);
 };
 
 export const logSuccess = (message: string): void => {
+  if (quiet) return;
   logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('✓', 'green')} ${message}`);
 };
 
@@ -32,6 +42,7 @@ export const logWarning = (message: string): void => {
 };
 
 export const logStep = (stepOrMessage: number | string, total?: number, message?: string): void => {
+  if (quiet) return;
   if (typeof stepOrMessage === 'string') {
     // Single parameter version: just a message
     logStream(`${colors.gray}[${getTimestamp()}]${colors.reset} ${colorize('▸', 'cyan')} ${stepOrMessage}`);

package/src/utils/reflect.test.ts

@@ -1,6 +1,7 @@
-import { describe, it, expect } from 'vitest';
-import { distillTranscript, parseReflectionReport, classifyAgentsMd, isCorrectionPrompt, saveReflectionReport } from './reflect';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { distillTranscript, parseReflectionReport, classifyAgentsMd, isCorrectionPrompt, saveReflectionReport, severityCounts, severitySummary, renderReportMarkdown, groupRecommendations, listSavedReports, loadSavedReport, findSavedMatches, SavedReport, ReflectionReport, Recommendation } from './reflect';
 import * as fs from 'fs/promises';
+import * as os from 'os';
 import * as path from 'path';
 
 const J = (o: unknown) => JSON.stringify(o);
@@ -124,3 +125,129 @@ describe('parseReflectionReport', () => {
     expect(parseReflectionReport({ recommendations: 'nope' })).toEqual({ summary: '', recommendations: [] });
   });
 });
+
+describe('severityCounts / severitySummary', () => {
+  const recs = (ps: Array<'high' | 'medium' | 'low'>) =>
+    ps.map((priority) => ({ kind: 'other' as const, title: 't', detail: 'd', priority }));
+
+  it('counts by priority', () => {
+    expect(severityCounts(recs(['high', 'high', 'low']))).toEqual({ high: 2, medium: 0, low: 1 });
+  });
+  it('summary omits empty buckets and is empty for none', () => {
+    expect(severitySummary(recs(['high', 'medium', 'medium']))).toBe('1 high · 2 medium');
+    expect(severitySummary([])).toBe('');
+  });
+});
+
+describe('renderReportMarkdown', () => {
+  const report: ReflectionReport = {
+    summary: 'Overall fine.',
+    recommendations: [
+      { kind: 'skill', title: 'Add deploy skill', detail: 'manual steps', priority: 'high', target: 'acme/api', example: 'name: deploy' },
+      { kind: 'context', title: 'Doc lint', detail: 'guessed', priority: 'medium' },
+    ],
+  };
+
+  it('groups by severity with a count line and headings', () => {
+    const md = renderReportMarkdown(report, { analyzed: 5, workspaces: 3, generatedAt: '2026-09-01T12:00:00Z' });
+    expect(md).toMatch(/^# Reflection/);
+    expect(md).toContain('_5 sessions across 3 workspaces · 2026-09-01T12:00:00Z_');
+    expect(md).toContain('**1 high · 1 medium**');
+    expect(md).toContain('### High priority');
+    expect(md).toContain('### Medium priority');
+    // high appears before medium
+    expect(md.indexOf('### High priority')).toBeLessThan(md.indexOf('### Medium priority'));
+    expect(md).toContain('- **[Skill] Add deploy skill** (`acme/api`)');
+    expect(md).toContain('- **[Context/AGENTS.md] Doc lint**');
+    expect(md.endsWith('\n')).toBe(true);
+  });
+
+  it('uses a single-workspace scope line', () => {
+    const md = renderReportMarkdown(report, { analyzed: 1, workspaces: 1, workspace: 'my-ws' });
+    expect(md).toContain('_workspace **my-ws**_');
+  });
+
+  it('escapes an example that itself contains a triple-backtick fence', () => {
+    const r: ReflectionReport = {
+      summary: '',
+      recommendations: [{ kind: 'other', title: 'x', detail: '', priority: 'low', example: 'a ```b``` c' }],
+    };
+    const md = renderReportMarkdown(r, { analyzed: 1, workspaces: 1 });
+    expect(md).toContain('````'); // fence longer than the inner run
+    expect(md).toContain('a ```b``` c');
+  });
+
+  it('renders a clean empty state', () => {
+    const md = renderReportMarkdown({ summary: 'All good.', recommendations: [] }, { analyzed: 2, workspaces: 2 });
+    expect(md).toContain('_No specific recommendations — looks solid._');
+    expect(md).not.toContain('### High');
+  });
+});
+
+describe('groupRecommendations', () => {
+  const mk = (kind: Recommendation['kind'], priority: Recommendation['priority'], title = 't'): Recommendation =>
+    ({ kind, title, detail: 'd', priority });
+
+  it('groups by priority (high→low), omitting empty groups', () => {
+    const groups = groupRecommendations([mk('skill', 'low'), mk('context', 'high')], 'priority');
+    expect(groups.map((g) => g.key)).toEqual(['high', 'low']); // no 'medium'
+    expect(groups[0].heading).toBe('High priority');
+  });
+
+  it('groups by kind in a fixed order, priority-sorted within a kind', () => {
+    const groups = groupRecommendations(
+      [mk('context', 'low'), mk('skill', 'low', 'a'), mk('skill', 'high', 'b')],
+      'kind',
+    );
+    expect(groups.map((g) => g.key)).toEqual(['skill', 'context']); // skill before context
+    expect(groups[0].recs.map((r) => r.title)).toEqual(['b', 'a']); // high before low within skill
+  });
+});
+
+describe('findSavedMatches (pure)', () => {
+  const mk = (id: string): SavedReport => ({ id, file: `${id}.json`, analyzed: 0, workspaces: 0, report: { summary: '', recommendations: [] } });
+  // newest-first list, as listSavedReports returns it
+  const all = [mk('2000-03'), mk('2000-02b'), mk('2000-02a'), mk('2000-01')];
+
+  it('empty / latest / exact', () => {
+    expect(findSavedMatches([], '2000')).toEqual([]);
+    expect(findSavedMatches(all)[0].id).toBe('2000-03'); // undefined -> newest
+    expect(findSavedMatches(all, 'latest')[0].id).toBe('2000-03');
+    expect(findSavedMatches(all, '2000-02a').map((r) => r.id)).toEqual(['2000-02a']); // exact wins
+  });
+  it('an ambiguous prefix returns every match, newest-first', () => {
+    expect(findSavedMatches(all, '2000-02').map((r) => r.id)).toEqual(['2000-02b', '2000-02a']);
+    expect(findSavedMatches(all, 'nope')).toEqual([]);
+  });
+});
+
+describe('listSavedReports / loadSavedReport (isolated temp dir)', () => {
+  let dir: string;
+  const idA = '2000-01-01T00-00-00-000Z-vitestA';
+  const idB = '2000-01-02T00-00-00-000Z-vitestB';
+
+  beforeAll(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'nemus-reflect-test-'));
+    await fs.writeFile(path.join(dir, `${idA}.json`), JSON.stringify({ generatedAt: '2000-01-01T00:00:00.000Z', analyzed: 4, workspaces: 3, summary: 'old', recommendations: [{ kind: 'skill', title: 'x', detail: 'd', priority: 'high' }] }));
+    await fs.writeFile(path.join(dir, `${idB}.json`), JSON.stringify({ generatedAt: '2000-01-02T00:00:00.000Z', analyzed: 1, workspaces: 1, workspace: 'ws', summary: 'new', recommendations: [] }));
+    await fs.writeFile(path.join(dir, 'not-json.txt'), 'ignore me');
+    await fs.writeFile(path.join(dir, 'corrupt.json'), '{ not valid json');
+  });
+  afterAll(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('lists newest-first, skipping non-json and corrupt files', async () => {
+    const all = await listSavedReports(dir);
+    expect(all.map((r) => r.id)).toEqual([idB, idA]); // exactly two, newer first
+    expect(all[0].workspace).toBe('ws');
+    expect(all[0].report.recommendations).toHaveLength(0);
+  });
+
+  it('loadSavedReport resolves latest, exact id, and prefix', async () => {
+    expect((await loadSavedReport('latest', dir))?.id).toBe(idB);
+    expect((await loadSavedReport(idA, dir))?.workspaces).toBe(3);
+    expect((await loadSavedReport('2000-01-02T00-00-00', dir))?.id).toBe(idB);
+    expect(await loadSavedReport('definitely-no-such-id-xyz', dir)).toBeNull();
+  });
+});

package/src/utils/reflect.ts

@@ -63,6 +63,134 @@ export interface ReflectionReport {
   recommendations: Recommendation[];
 }
 
+// ------------------------------------------------------------ report rendering
+
+export type Priority = Recommendation['priority'];
+
+/** Count recommendations by priority. */
+export function severityCounts(recs: Recommendation[]): Record<Priority, number> {
+  const counts: Record<Priority, number> = { high: 0, medium: 0, low: 0 };
+  for (const r of recs) counts[r.priority]++;
+  return counts;
+}
+
+/** "3 high · 2 medium · 1 low", omitting zero buckets; '' when there are none. */
+export function severitySummary(recs: Recommendation[]): string {
+  const c = severityCounts(recs);
+  return (['high', 'medium', 'low'] as Priority[])
+    .filter((p) => c[p] > 0)
+    .map((p) => `${c[p]} ${p}`)
+    .join(' · ');
+}
+
+export const KIND_LABEL: Record<RecommendationKind, string> = {
+  skill: 'Skill',
+  context: 'Context/AGENTS.md',
+  test: 'Test',
+  prompt: 'Prompt',
+  connectivity: 'Connectivity',
+  workflow: 'Workflow',
+  other: 'Other',
+};
+// Back-compat alias for existing references.
+const MD_KIND_LABEL = KIND_LABEL;
+
+export const PRIORITY_HEADING: Record<Priority, string> = {
+  high: 'High priority',
+  medium: 'Medium priority',
+  low: 'Low priority',
+};
+
+export type GroupBy = 'priority' | 'kind';
+
+const KIND_ORDER: RecommendationKind[] = ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'];
+const PRIORITY_ORDER: Priority[] = ['high', 'medium', 'low'];
+const PRIORITY_RANK: Record<Priority, number> = { high: 0, medium: 1, low: 2 };
+
+export interface RecGroup {
+  key: string;
+  heading: string;
+  recs: Recommendation[];
+}
+
+/**
+ * Split recommendations into ordered, non-empty groups by either priority
+ * (high→low) or kind (a fixed, stable order). When grouping by kind, each
+ * group's recs are sorted high-priority first. Pure + unit-tested; shared by the
+ * Markdown renderer and the human printer so the two never diverge.
+ */
+export function groupRecommendations(recs: Recommendation[], groupBy: GroupBy): RecGroup[] {
+  if (groupBy === 'kind') {
+    return KIND_ORDER.map((k) => ({
+      key: k,
+      heading: KIND_LABEL[k],
+      recs: recs
+        .filter((r) => r.kind === k)
+        .sort((a, b) => PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority]),
+    })).filter((g) => g.recs.length > 0);
+  }
+  return PRIORITY_ORDER.map((p) => ({
+    key: p,
+    heading: PRIORITY_HEADING[p],
+    recs: recs.filter((r) => r.priority === p),
+  })).filter((g) => g.recs.length > 0);
+}
+
+/** A fenced code block whose fence is guaranteed longer than any backtick run
+ *  inside `body`, so the snippet can't break out of its own fence. */
+function fencedBlock(body: string): string {
+  const longest = Math.max(0, ...(body.match(/`+/g) ?? []).map((m) => m.length));
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}\n${body}\n${fence}`;
+}
+
+/**
+ * Render a reflection report as clean Markdown — for pasting into an issue/PR or
+ * saving alongside the JSON. Pure (no color, no I/O) so it's unit-tested.
+ * Recommendations are grouped by severity (high→low); each carries its kind,
+ * optional target, detail, and a fenced example.
+ */
+export function renderReportMarkdown(
+  report: ReflectionReport,
+  meta: { analyzed: number; workspaces: number; workspace?: string; generatedAt?: string },
+  groupBy: GroupBy = 'priority',
+): string {
+  const lines: string[] = ['# Reflection', ''];
+  const scope = meta.workspace
+    ? `workspace **${meta.workspace}**`
+    : `${meta.analyzed} session${meta.analyzed === 1 ? '' : 's'} across ${meta.workspaces} workspace${meta.workspaces === 1 ? '' : 's'}`;
+  const stamp = meta.generatedAt ? ` · ${meta.generatedAt}` : '';
+  lines.push(`_${scope}${stamp}_`, '');
+
+  if (report.summary.trim()) lines.push(report.summary.trim(), '');
+
+  if (report.recommendations.length === 0) {
+    lines.push('## Recommendations', '', '_No specific recommendations — looks solid._', '');
+    return lines.join('\n');
+  }
+
+  lines.push('## Recommendations', '', `**${severitySummary(report.recommendations)}**`, '');
+
+  for (const group of groupRecommendations(report.recommendations, groupBy)) {
+    lines.push(`### ${group.heading}`, '');
+    for (const r of group.recs) {
+      const target = r.target ? ` (\`${r.target}\`)` : '';
+      // Under a kind heading the [Kind] prefix is redundant; show a priority tag
+      // instead. Under a priority heading, show the kind.
+      const label = groupBy === 'kind' ? `_${r.priority}_ — ` : `[${KIND_LABEL[r.kind]}] `;
+      lines.push(`- **${label}${r.title}**${target}`);
+      if (r.detail.trim()) {
+        lines.push(...r.detail.trim().split('\n').map((l) => `  ${l}`));
+      }
+      if (r.example?.trim()) {
+        lines.push('', ...fencedBlock(r.example.trim()).split('\n').map((l) => `  ${l}`));
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
 // --------------------------------------------------------- transcript distill
 
 // Kept deliberately lean: the judge runs on the user's own (often local, slow)
@@ -455,3 +583,76 @@ export async function saveReflectionReport(
   await fs.writeFile(file, JSON.stringify({ generatedAt: new Date().toISOString(), ...meta, ...report }, null, 2));
   return file;
 }
+
+/** A saved report on disk, with its metadata and parsed report. */
+export interface SavedReport {
+  /** Basename without .json — the id used by `reflect show <id>`. */
+  id: string;
+  file: string;
+  generatedAt?: string;
+  analyzed: number;
+  workspaces: number;
+  workspace?: string;
+  report: ReflectionReport;
+}
+
+/**
+ * List saved reports under `~/.nemus/reflect/`, newest first (filenames start
+ * with an ISO timestamp, so a reverse name sort is chronological). Unreadable /
+ * unparseable files are skipped, not fatal. Returns [] if the dir is absent.
+ */
+export async function listSavedReports(dir: string = REFLECT_REPORTS_DIR): Promise<SavedReport[]> {
+  let names: string[];
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+  const jsons = names.filter((n) => n.endsWith('.json')).sort().reverse();
+  const out: SavedReport[] = [];
+  for (const name of jsons) {
+    const file = path.join(dir, name);
+    try {
+      const raw = JSON.parse(await fs.readFile(file, 'utf-8'));
+      out.push({
+        id: name.replace(/\.json$/, ''),
+        file,
+        generatedAt: typeof raw.generatedAt === 'string' ? raw.generatedAt : undefined,
+        analyzed: typeof raw.analyzed === 'number' ? raw.analyzed : 0,
+        workspaces: typeof raw.workspaces === 'number' ? raw.workspaces : 0,
+        workspace: typeof raw.workspace === 'string' ? raw.workspace : undefined,
+        report: parseReflectionReport(raw),
+      });
+    } catch {
+      /* skip a corrupt/partial file */
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve a report reference against an (already newest-first) list. Returns ALL
+ * matches so a caller can detect ambiguity: `undefined`/`'latest'` -> the newest;
+ * an exact id -> that one; otherwise every id with the prefix (newest-first). An
+ * exact id always wins over prefixes, so an id can't be ambiguous with itself.
+ * Pure + unit-tested.
+ */
+export function findSavedMatches(all: SavedReport[], ref?: string): SavedReport[] {
+  if (all.length === 0) return [];
+  if (!ref || ref === 'latest') return [all[0]];
+  const exact = all.find((r) => r.id === ref);
+  if (exact) return [exact];
+  return all.filter((r) => r.id.startsWith(ref));
+}
+
+/**
+ * Load one saved report by id. `undefined`/`'latest'` returns the newest; an id
+ * is matched exactly, then as a prefix (newest match wins). Returns null when
+ * nothing matches. For ambiguity-aware callers, use findSavedMatches directly.
+ */
+export async function loadSavedReport(
+  ref?: string,
+  dir: string = REFLECT_REPORTS_DIR,
+): Promise<SavedReport | null> {
+  return findSavedMatches(await listSavedReports(dir), ref)[0] ?? null;
+}