@design-ai/cli 4.55.0 → 4.57.0

package/cli/commands/learn-help.mjs

@@ -0,0 +1,149 @@
+// Help text for `design-ai learn`.
+
+import { LEARNING_FEEDBACK_OUTCOMES } from "../lib/learn.mjs";
+
+export function printHelp() {
+  console.log("Usage:  design-ai learn [--list] [--category kind] [--query text] [--explain] [--limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --recall query [--limit N] [--category kind] [--json]");
+  console.log("        design-ai learn <mode> ...  Bare-word alias for a mode flag, e.g. `learn signals --json` = `learn --signals --json`");
+  console.log("        design-ai learn --init [--yes|--dry-run] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --remember text [--category kind] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --feedback text [--outcome keep|improve|avoid] [--category kind] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --feedback --from-file notes.md [--outcome keep|improve|avoid] [--category kind] [--json] [--out file] [--force]");
+  console.log("        cat notes.md | design-ai learn --feedback --stdin [--outcome keep|improve|avoid] [--category kind] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --from-file notes.md [--category kind] [--json] [--out file] [--force]");
+  console.log("        cat notes.md | design-ai learn --stdin [--category kind] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --export [--category kind] [--query text] [--limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --backup [--json] [--out file] [--force]");
+  console.log("        design-ai learn --redact [--json] [--out file] [--force]");
+  console.log("        design-ai learn --redact --from-file learning-backup.json [--json] [--out file] [--force]");
+  console.log("        cat learning-backup.json | design-ai learn --redact --stdin [--json] [--out file] [--force]");
+  console.log("        design-ai learn --verify --from-file learning.json [--json] [--out file] [--force]");
+  console.log("        cat learning.json | design-ai learn --verify --stdin [--json] [--out file] [--force]");
+  console.log("        design-ai learn --diff --from-file learning.json [--json] [--out file] [--force]");
+  console.log("        cat learning.json | design-ai learn --diff --stdin [--json] [--out file] [--force]");
+  console.log("        design-ai learn --restore --from-file learning-backup.json [--dry-run|--yes] [--backup-file path] [--json] [--out file] [--force]");
+  console.log("        cat learning-backup.json | design-ai learn --restore --stdin [--dry-run|--yes] [--backup-file path] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --restore-backups [--limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --restore-backups --prune [--keep N] [--dry-run|--yes] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --import --from-file learning.json --dry-run [--json] [--out file] [--force]");
+  console.log("        cat learning.json | design-ai learn --import --stdin --yes [--json] [--out file] [--force]");
+  console.log("        design-ai learn --audit [--json] [--out file] [--force]");
+  console.log("        design-ai learn --audit --fix --dry-run [--json] [--out file] [--force]");
+  console.log("        design-ai learn --audit --fix --yes [--json] [--out file] [--force]");
+  console.log("        design-ai learn --curate [--dry-run|--yes] [--usage-file path] [--json|--report] [--out file] [--force]");
+  console.log("        design-ai learn --stats [--json] [--out file] [--force]");
+  console.log("        design-ai learn --usage [--limit N] [--usage-file path] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --signals [--from-file signal-file-or-dir] [--usage-file path] [--strict] [--json|--report] [--out file] [--force]");
+  console.log("        design-ai learn --agent-backlog [--from-file signal-file-or-dir] [--usage-file path] [--strict] [--json|--report] [--out file] [--force]");
+  console.log("        design-ai learn --propose-skills [--from-file signal-file-or-dir] [--usage-file path] [--review-file path] [--review-check|--apply-plan] [--min-evidence N] [--strict] [--json|--report|--patch|--review-template] [--out file] [--force]");
+  console.log("        design-ai learn --eval-template [--query text] [--category kind] [--limit N] [--json] [--out file] [--force]");
+  console.log("        design-ai learn --eval --from-file eval.json [--category kind] [--limit N] [--strict] [--json] [--out file] [--force]");
+  console.log("        cat eval.json | design-ai learn --eval --stdin [--category kind] [--limit N] [--strict] [--json]");
+  console.log("        design-ai learn --forget id-or-number --yes [--json] [--out file] [--force]");
+  console.log("        design-ai learn --clear --yes [--json] [--out file] [--force]\n");
+  console.log("Stores local design preferences for explicit prompt personalization.");
+  console.log("This is local memory, not model training or fine-tuning.\n");
+  console.log("Options:");
+  console.log("  --init               Preview or apply starter local learning entries for dogfood use");
+  console.log("  --remember text      Remember an inline preference or project constraint");
+  console.log("  --feedback text      Convert outcome feedback into a reusable local learning note");
+  console.log(`  --outcome kind       Feedback outcome: ${LEARNING_FEEDBACK_OUTCOMES.join(", ")}. Default: improve`);
+  console.log("  --from-file file     Read remember/feedback text or import/verify/diff/restore/redact JSON from a file");
+  console.log("  --stdin              Read remember/feedback text or import/verify/diff/restore/redact JSON from standard input");
+  console.log("  --category kind      preference, brand, workflow, constraint, accessibility, korean, other");
+  console.log("  --query text         Filter list/export output to entries whose category or text matches the query");
+  console.log("  --explain            With --list, include selection score, matched tokens, and reason");
+  console.log("  --limit N            Limit list/export output to the N most recent matching entries, 1-100");
+  console.log("  --recall query       Read-only combined recall: top corpus knowledge files plus local learning entries ranked for the query");
+  console.log("  --list               List saved learning entries. Default when no action is given");
+  console.log("  --export             Print the learned-context block used by --with-learning");
+  console.log("  --backup             Print a full portable learning-profile backup; use --json for importable JSON");
+  console.log("  --redact             Print a portable JSON backup with sensitive-looking text redacted");
+  console.log("  --verify             Validate a portable learning JSON payload without importing it");
+  console.log("  --diff               Compare the active profile against a portable learning JSON payload without importing it");
+  console.log("  --restore            Preview or apply replacing the active profile with a portable learning JSON payload");
+  console.log("  --restore-backups    List sibling restore rollback backups for the active learning profile");
+  console.log("  --prune              With --restore-backups, preview or delete older rollback backup files");
+  console.log("  --keep N             With --restore-backups --prune, keep the N newest backups. Default: 5");
+  console.log("  --backup-file path   With --restore, override the automatic rollback backup file path");
+  console.log("  --import             Merge entries from a JSON learning profile or learn --export --json payload");
+  console.log("  --audit              Inspect profile shape, sensitive content, and cleanup suggestions without changing it");
+  console.log("  --fix                With --audit, prepare or apply safe cleanup suggestions");
+  console.log("  --curate             Preview or apply archive-first curation for duplicate/sensitive entries, plus usage review hints");
+  console.log("  --report             With --curate, --signals, --agent-backlog, or --propose-skills, emit a Markdown review report instead of human console output");
+  console.log("  --patch              With --propose-skills, emit a preview-only unified diff handoff without editing skill files");
+  console.log("  --review-check       With --propose-skills, verify the review file against current proposals without changing files");
+  console.log("  --apply-plan         With --propose-skills, turn accepted review decisions into a read-only manual apply plan");
+  console.log("  --review-template    With --propose-skills, emit a JSON proposal review-file template without changing review decisions");
+  console.log("  --dry-run            Preview --init, --import, --restore, --curate, --restore-backups --prune, or --audit --fix without changing files");
+  console.log("  --stats              Summarize profile counts, recency, and audit status without changing it");
+  console.log("  --usage              Summarize prompt/pack --with-learning usage sidecar events without changing files");
+  console.log("  --signals            Summarize local learning, usage, eval, check-capture, agent backlog, and workspace readiness signals without changing files");
+  console.log("  --agent-backlog      Emit a focused local AI/agent development backlog from the signal registry without changing files");
+  console.log("  --propose-skills     Preview skill instruction deltas from repeated check-capture learning signals without changing files");
+  console.log("  --min-evidence N     With --propose-skills, require N related check-capture entries before emitting a proposal. Default: 2");
+  console.log("  --review-file path   With --propose-skills, read proposal review decisions without changing the review file");
+  console.log("  --eval-template      Generate a runnable learning eval checkpoint from the active profile");
+  console.log("  --eval               Run deterministic learning-selection checkpoint cases without changing files");
+  console.log("  --strict             With --eval, --signals, --agent-backlog, or --propose-skills, exit non-zero when any checkpoint, signal, backlog, or proposal gate warns or fails");
+  console.log("  --forget id-or-number Remove one entry by id or 1-based list number; requires --yes");
+  console.log("  --clear              Remove all saved learning entries; requires --yes");
+  console.log("  --yes                Confirm destructive local profile changes");
+  console.log("  --file path          Override the learning profile path");
+  console.log("  --usage-file path    Override the learning usage sidecar path used by --usage, --curate, --signals, --agent-backlog, or --propose-skills");
+  console.log("  --json               Emit machine-readable output");
+  console.log("  --out file           Write JSON output to a file, export Markdown for --export, or learning review report Markdown");
+  console.log("  --force              Overwrite an existing --out file, or an existing --backup-file during --restore");
+  console.log("");
+  console.log("Environment:");
+  console.log("  DESIGN_AI_LEARNING_FILE=/path/learning.json       Override the default profile path");
+  console.log("  DESIGN_AI_LEARNING_USAGE_FILE=/path/usage.json    Override the default usage sidecar path");
+  console.log("");
+  console.log("Examples:");
+  console.log("  design-ai learn --init");
+  console.log("  design-ai learn --init --yes --json");
+  console.log("  design-ai learn --remember \"Prefer dense Korean product UI\" --category korean");
+  console.log("  design-ai learn --feedback \"Keep audit findings short and evidence-led\" --outcome keep");
+  console.log("  design-ai learn --feedback --from-file feedback.md --outcome improve");
+  console.log("  cat feedback.md | design-ai learn --feedback --stdin --outcome avoid --category brand");
+  console.log("  design-ai learn --recall \"korean payment\" --limit 5");
+  console.log("  design-ai learn --list --category korean --limit 5");
+  console.log("  design-ai learn --list --query \"keyboard accessibility\" --explain --json");
+  console.log("  design-ai learn --export --query \"pricing page\" --limit 3");
+  console.log("  design-ai learn --backup --json --out learning-backup.json");
+  console.log("  design-ai learn --redact --json --out learning-redacted.json");
+  console.log("  design-ai learn --redact --from-file learning-backup.json --json --out learning-redacted.json --force");
+  console.log("  design-ai learn --verify --from-file learning-backup.json");
+  console.log("  design-ai learn --diff --from-file learning-backup.json --json");
+  console.log("  design-ai learn --restore --from-file learning-backup.json --dry-run");
+  console.log("  design-ai learn --restore --from-file learning-backup.json --yes --backup-file learning-before-restore.json");
+  console.log("  design-ai learn --restore-backups --json");
+  console.log("  design-ai learn --restore-backups --prune --keep 5");
+  console.log("  design-ai learn --restore-backups --prune --keep 5 --yes");
+  console.log("  design-ai learn --import --from-file learning.json --dry-run");
+  console.log("  design-ai learn --audit");
+  console.log("  design-ai learn --audit --fix --dry-run");
+  console.log("  design-ai learn --curate");
+  console.log("  design-ai learn --curate --usage-file ./learning.usage.json");
+  console.log("  design-ai learn --curate --report --out learning-curation-report.md");
+  console.log("  design-ai learn --curate --yes --json");
+  console.log("  design-ai learn --stats --json");
+  console.log("  design-ai learn --usage --json");
+  console.log("  design-ai learn --signals --from-file . --json");
+  console.log("  design-ai learn --signals --from-file . --report --out learning-signals.md");
+  console.log("  design-ai learn --agent-backlog --from-file . --report --out agent-backlog.md");
+  console.log("  design-ai learn --propose-skills --from-file . --min-evidence 3 --json");
+  console.log("  design-ai learn --propose-skills --from-file . --strict --json");
+  console.log("  design-ai learn --propose-skills --from-file . --review-file skill-proposals.review.json --strict --json");
+  console.log("  design-ai learn --propose-skills --from-file . --review-file skill-proposals.review.json --review-check --json");
+  console.log("  design-ai learn --propose-skills --from-file . --review-file skill-proposals.review.json --apply-plan --json");
+  console.log("  design-ai learn --propose-skills --from-file . --review-template --out skill-proposals.review.json");
+  console.log("  design-ai learn --propose-skills --from-file . --report --out skill-proposals.md");
+  console.log("  design-ai learn --propose-skills --from-file . --patch --out skill-proposals.patch");
+  console.log("  design-ai learn --eval-template --query \"keyboard accessibility\" --out learning-eval.json");
+  console.log("  design-ai learn --eval --from-file learning-eval.json --strict --json");
+  console.log("  design-ai learn --forget learn-abc123def0 --yes");
+  console.log("  design-ai prompt \"audit checkout UX\" --with-learning");
+  console.log("  design-ai pack \"spec a pricing page\" --with-learning");
+}

package/cli/commands/learn-print-profile.mjs

@@ -0,0 +1,373 @@
+// Human-readable output for learn profile list/audit/curation/stats/usage results.
+
+import {
+  LEARNING_CATEGORIES,
+  loadLearningProfile,
+  selectLearningEntrySet,
+} from "../lib/learn.mjs";
+import { dim, header, info } from "../lib/log.mjs";
+
+export function printLearningImportVerification(payload) {
+  header("design-ai learn", "Learning import verification");
+  info(`Source: ${payload.source}`);
+  info(`Importable: ${payload.importable ? "yes" : "no"}`);
+  info(`Entries: ${payload.count}`);
+  info(`Audit: ${payload.auditSummary.status} (${payload.auditSummary.failures} failure(s), ${payload.auditSummary.warnings} warning(s))`);
+  console.log();
+
+  if (payload.issues.length === 0) {
+    console.log("No learning import issues found. No changes made.");
+    return;
+  }
+
+  for (const issue of payload.issues) {
+    const entry = issue.entryId ? ` (${issue.entryId})` : "";
+    console.log(`${issue.level.toUpperCase()} ${issue.code}${entry}: ${issue.message}`);
+  }
+  console.log();
+  console.log("No changes made. Review warnings before importing or using learned context.");
+}
+
+export function learningFilter(parsed) {
+  return {
+    category: parsed.categorySpecified ? parsed.category : "",
+    limit: parsed.limit,
+    query: parsed.query,
+  };
+}
+
+export function listPayload(filePath, parsed) {
+  const profile = loadLearningProfile(filePath);
+  const filter = learningFilter(parsed);
+  const { entries, selection } = selectLearningEntrySet(profile, {
+    ...filter,
+    includeFallback: false,
+  });
+  const payload = {
+    file: filePath,
+    version: profile.version,
+    updatedAt: profile.updatedAt,
+    category: filter.category,
+    query: filter.query,
+    limit: filter.limit || null,
+    entries,
+    count: entries.length,
+    totalCount: profile.entries.length,
+  };
+  if (parsed.explain) {
+    payload.selection = selection;
+  }
+  return payload;
+}
+
+export function printList(payload) {
+  header("design-ai learn", "Local learning profile");
+  info(`File: ${payload.file}`);
+  info(`Entries: ${payload.count}/${payload.totalCount}`);
+  if (payload.category) info(`Category: ${payload.category}`);
+  if (payload.query) info(`Query: ${payload.query}`);
+  if (payload.limit) info(`Limit: ${payload.limit}`);
+  if (payload.selection) {
+    info("Explain: selection score, matched tokens, and reason");
+  }
+  console.log();
+
+  if (payload.entries.length === 0) {
+    console.log(payload.category || payload.query || payload.limit
+      ? "No local learning preferences match the current filters."
+      : "No local learning preferences are stored yet.");
+    return;
+  }
+
+  for (let i = 0; i < payload.entries.length; i += 1) {
+    const entry = payload.entries[i];
+    const selected = payload.selection?.selected?.[i];
+    console.log(`${i + 1}. [${entry.category}] ${entry.text}`);
+    console.log(`   ${dim(`${entry.id} · ${entry.createdAt || "unknown time"}`)}`);
+    if (selected) {
+      const matched = selected.matchedTokens.length > 0
+        ? selected.matchedTokens.join(", ")
+        : "none";
+      console.log(`   ${dim(`score ${selected.score} · matched ${matched} · reason ${selected.reason}`)}`);
+    }
+  }
+}
+
+function formatCategoryCounts(categoryCounts) {
+  return LEARNING_CATEGORIES
+    .filter((category) => categoryCounts[category])
+    .map((category) => `${category} ${categoryCounts[category]}`)
+    .join(", ");
+}
+
+function formatCounts(counts) {
+  return Object.entries(counts || {})
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([key, count]) => `${key} ${count}`)
+    .join(", ");
+}
+
+export function printAudit(payload) {
+  header("design-ai learn", "Local learning profile audit");
+  info(`File: ${payload.file}`);
+  info(`Exists: ${payload.exists ? "yes" : "no"}`);
+  info(`Entries: ${payload.count}`);
+  info(`Status: ${payload.summary.status}`);
+  info(`Issues: ${payload.summary.failures} failure(s), ${payload.summary.warnings} warning(s)`);
+
+  const categories = formatCategoryCounts(payload.categoryCounts);
+  if (categories) info(`Categories: ${categories}`);
+  console.log();
+
+  if (!payload.exists) {
+    console.log("No local learning profile file exists yet.");
+    return;
+  }
+
+  if (payload.issues.length === 0) {
+    console.log("No learning profile issues found.");
+    return;
+  }
+
+  for (const issue of payload.issues) {
+    const entry = issue.entryId ? ` (${issue.entryId})` : "";
+    console.log(`${issue.level.toUpperCase()} ${issue.code}${entry}: ${issue.message}`);
+  }
+
+  if (payload.suggestions.length > 0) {
+    console.log();
+    console.log("Suggested cleanup:");
+    for (const suggestion of payload.suggestions) {
+      const entry = suggestion.entryId ? ` (${suggestion.entryId})` : "";
+      console.log(`- ${suggestion.action}${entry}: ${suggestion.message}`);
+      if (suggestion.command) {
+        console.log(`  ${dim(suggestion.command)}`);
+      }
+    }
+  }
+}
+
+export function printAuditFix(payload) {
+  header("design-ai learn", payload.dryRun ? "Learning audit cleanup dry run" : "Learning audit cleanup applied");
+  info(`File: ${payload.file}`);
+  info(`Before: ${payload.before.status} (${payload.before.failures} failure(s), ${payload.before.warnings} warning(s))`);
+  info(`Cleanup entries: ${payload.cleanupCount}`);
+  if (payload.after) {
+    info(`After: ${payload.after.status} (${payload.after.failures} failure(s), ${payload.after.warnings} warning(s))`);
+  }
+  console.log();
+
+  if (payload.cleanup.length === 0) {
+    console.log("No safe cleanup suggestions are available.");
+  } else {
+    console.log(payload.dryRun ? "Would remove:" : "Removed:");
+    for (const fix of payload.cleanup) {
+      console.log(`- ${fix.entryId}: ${fix.actions.join(", ")} (${fix.issueCodes.join(", ")})`);
+      if (fix.command) {
+        console.log(`  ${dim(fix.command)}`);
+      }
+    }
+  }
+
+  if (payload.skipped.length > 0) {
+    console.log();
+    console.log("Skipped:");
+    for (const skipped of payload.skipped) {
+      const entry = skipped.entryId ? ` (${skipped.entryId})` : "";
+      console.log(`- ${skipped.reason}${entry}: ${skipped.message}`);
+    }
+  }
+
+  if (payload.dryRun) {
+    console.log();
+    console.log("No changes made. Re-run with `--yes` instead of `--dry-run` to apply safe cleanup.");
+  }
+}
+
+export function printCuration(payload) {
+  header("design-ai learn", payload.dryRun ? "Learning curation preview" : "Learning curation applied");
+  info(`File: ${payload.file}`);
+  info(`Archive: ${payload.archiveFile}`);
+  info(`Before: ${payload.before.status} (${payload.before.failures} failure(s), ${payload.before.warnings} warning(s))`);
+  info(`Proposals: ${payload.proposalCount}`);
+  info(`Archive candidates: ${payload.archiveCount}`);
+  info(`Manual review: ${payload.manualReviewCount}`);
+  if (payload.after) {
+    info(`After: ${payload.after.status} (${payload.after.failures} failure(s), ${payload.after.warnings} warning(s))`);
+  }
+  console.log();
+
+  if (payload.proposals.length === 0) {
+    console.log("No learning curation candidates found.");
+  } else {
+    const archiveCandidates = payload.proposals.filter((proposal) => proposal.action === "archive");
+    const manualCandidates = payload.proposals.filter((proposal) => proposal.action === "manual-review");
+    if (archiveCandidates.length > 0) {
+      console.log(payload.dryRun ? "Would archive:" : "Archived:");
+      for (const proposal of archiveCandidates) {
+        console.log(`- ${proposal.entryId}: ${proposal.reason} (${proposal.issueCodes.join(", ")})`);
+        if (proposal.textPreview) console.log(`  ${dim(proposal.textPreview)}`);
+      }
+      console.log();
+    }
+    if (manualCandidates.length > 0) {
+      console.log("Needs manual review:");
+      for (const proposal of manualCandidates) {
+        const label = proposal.entryId || "profile";
+        console.log(`- ${label}: ${proposal.reason} (${proposal.issueCodes.join(", ")})`);
+        if (proposal.textPreview) console.log(`  ${dim(proposal.textPreview)}`);
+      }
+      console.log();
+    }
+  }
+
+  if (payload.skipped.length > 0) {
+    console.log("Skipped:");
+    for (const skipped of payload.skipped) {
+      const entry = skipped.entryId ? `${skipped.entryId}: ` : "";
+      console.log(`- ${entry}${skipped.reason}`);
+    }
+    console.log();
+  }
+
+  if (payload.usage?.exists || payload.usage?.error) {
+    console.log("Usage review:");
+    console.log(`- sidecar: ${payload.usage.usageFile}`);
+    console.log(`- events: ${payload.usage.eventCount}`);
+    console.log(`- review items: ${payload.usage.reviewCount}`);
+    if (payload.usage.error) {
+      console.log(`- error: ${payload.usage.error}`);
+    } else if (payload.usage.reviews.length === 0) {
+      console.log("- no usage-based curation review items found");
+    } else {
+      for (const review of payload.usage.reviews) {
+        const label = review.entryId || "usage";
+        console.log(`- ${label}: ${review.reason} (${review.action})`);
+        if (review.textPreview) console.log(`  ${dim(review.textPreview)}`);
+      }
+    }
+    console.log(dim("Usage review is advisory; --curate only archives duplicate/sensitive audit candidates."));
+    console.log();
+  }
+
+  if (payload.dryRun) {
+    console.log("No changes made. Re-run with `--yes` to move archive candidates into the learning archive.");
+  }
+}
+
+export function printStats(payload) {
+  header("design-ai learn", "Local learning profile stats");
+  info(`File: ${payload.file}`);
+  info(`Exists: ${payload.exists ? "yes" : "no"}`);
+  info(`Entries: ${payload.count}`);
+  info(`Updated: ${payload.updatedAt || "unknown"}`);
+  info(`Audit: ${payload.auditSummary.status} (${payload.auditSummary.failures} failure(s), ${payload.auditSummary.warnings} warning(s))`);
+
+  const categories = formatCategoryCounts(payload.categoryCounts);
+  if (categories) info(`Categories: ${categories}`);
+
+  const sources = Object.entries(payload.sourceCounts)
+    .map(([source, count]) => `${source} ${count}`)
+    .join(", ");
+  if (sources) info(`Sources: ${sources}`);
+  console.log();
+
+  if (!payload.exists) {
+    console.log("No local learning profile file exists yet.");
+    return;
+  }
+
+  if (payload.auditSummary.failures > 0) {
+    console.log("Profile stats are limited because the profile has audit failures. Run `design-ai learn --audit` for details.");
+    return;
+  }
+
+  if (payload.count === 0) {
+    console.log("No local learning preferences are stored yet.");
+    return;
+  }
+
+  if (!payload.latestEntry) {
+    console.log("No parseable learning entry timestamps found. Run `design-ai learn --audit` for details.");
+    return;
+  }
+
+  if (payload.latestEntry) {
+    console.log(`Latest: [${payload.latestEntry.category}] ${payload.latestEntry.textPreview}`);
+    console.log(`        ${dim(`${payload.latestEntry.id} · ${payload.latestEntry.createdAt}`)}`);
+  }
+  if (payload.oldestEntry && payload.oldestEntry.id !== payload.latestEntry?.id) {
+    console.log(`Oldest: [${payload.oldestEntry.category}] ${payload.oldestEntry.textPreview}`);
+    console.log(`        ${dim(`${payload.oldestEntry.id} · ${payload.oldestEntry.createdAt}`)}`);
+  }
+}
+
+export function printUsage(payload) {
+  header("design-ai learn", "Local learning usage report");
+  info(`File: ${payload.file}`);
+  info(`Usage sidecar: ${payload.usageFile}`);
+  info(`Usage exists: ${payload.exists ? "yes" : "no"}`);
+  info(`Events: ${payload.eventCount}`);
+  info(`Profile entries: ${payload.profileEntryCount}`);
+  info(`Used entries: ${payload.usedEntryCount}`);
+  info(`Unused entries: ${payload.unusedEntryCount}`);
+  info(`Stale selected ids: ${payload.staleSelectedEntryCount}`);
+  info(`Updated: ${payload.updatedAt || "unknown"}`);
+
+  const commands = formatCounts(payload.commandCounts);
+  if (commands) info(`Commands: ${commands}`);
+  const routes = formatCounts(payload.routeCounts);
+  if (routes) info(`Routes: ${routes}`);
+  const categories = formatCounts(payload.categoryCounts);
+  if (categories) info(`Categories: ${categories}`);
+  console.log();
+
+  if (!payload.exists) {
+    console.log("No local learning usage sidecar exists yet.");
+    console.log("Run `design-ai prompt \"...\" --with-learning` or `design-ai pack \"...\" --with-learning` to record usage metadata.");
+    return;
+  }
+
+  if (payload.eventCount === 0) {
+    console.log("No local learning usage events are stored yet.");
+    return;
+  }
+
+  if (payload.topSelectedEntries.length > 0) {
+    console.log("Top selected entries:");
+    for (const entry of payload.topSelectedEntries) {
+      console.log(`- ${entry.id}: ${entry.usageCount} use(s) [${entry.category}] ${entry.textPreview}`);
+      if (entry.latestUsedAt) console.log(`  ${dim(`latest ${entry.latestUsedAt}`)}`);
+    }
+    console.log();
+  }
+
+  if (payload.recentEvents.length > 0) {
+    console.log("Recent events:");
+    for (const event of payload.recentEvents) {
+      const route = event.routeId || "unrouted";
+      const ids = event.selectedEntryIds.length > 0 ? event.selectedEntryIds.join(", ") : "none";
+      console.log(`- ${event.createdAt}: ${event.command} / ${route} selected ${ids}`);
+      console.log(`  ${dim(`briefHash ${event.briefHash || "none"} · matched ${event.matchedCount}/${event.candidateCount} · fallback ${event.fallbackCount}`)}`);
+    }
+    console.log();
+  }
+
+  if (payload.unusedEntryIds.length > 0) {
+    console.log(`Unused active entry ids: ${payload.unusedEntryIds.join(", ")}`);
+  }
+  if (payload.staleSelectedEntryIds.length > 0) {
+    console.log(`Stale selected entry ids: ${payload.staleSelectedEntryIds.join(", ")}`);
+  }
+
+  if (payload.recommendations.length > 0) {
+    console.log();
+    console.log("Recommendations:");
+    for (const recommendation of payload.recommendations) {
+      console.log(`- ${recommendation.level}: ${recommendation.text}`);
+    }
+  }
+
+  console.log();
+  console.log("Privacy: usage events store selected entry ids and a short brief hash, not raw brief text.");
+}