truecourse 0.5.0 → 0.5.1

package/cli.mjs

@@ -4062,8 +4062,11 @@ var init_registry = __esm({
 // tools/cli/src/commands/helpers.ts
 var helpers_exports = {};
 __export(helpers_exports, {
+  exitMissingNonInteractiveFlag: () => exitMissingNonInteractiveFlag,
   getConfigPath: () => getConfigPath,
   getServerUrl: () => getServerUrl,
+  hasInstalledSkills: () => hasInstalledSkills,
+  isInteractive: () => isInteractive,
   openInBrowser: () => openInBrowser,
   promptInstallSkills: () => promptInstallSkills,
   readConfig: () => readConfig,
@@ -4316,11 +4319,24 @@ function openInBrowser(url) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   exec2(`${cmd} ${url}`);
 }
-async function promptInstallSkills(repoPath) {
-  const installSkills = await ot2({
-    message: "Would you like to install Claude Code skills?"
-  });
-  if (q(installSkills) || !installSkills) return;
+function skillDestPath(repoPath) {
+  return resolve(repoPath, ".claude", "skills", "truecourse");
+}
+function hasInstalledSkills(repoPath) {
+  return existsSync(skillDestPath(repoPath));
+}
+function isInteractive() {
+  return !!process.stdin.isTTY;
+}
+function exitMissingNonInteractiveFlag(context, flagGuidance) {
+  O2.error(
+    `${context}
+
+Running non-interactively with no answer. ${flagGuidance}`
+  );
+  process.exit(1);
+}
+function copySkillsInto(repoPath) {
   const __dirname4 = dirname(fileURLToPath(import.meta.url));
   const srcPath = resolve(__dirname4, "..", "..", "skills", "truecourse");
   const distPath = resolve(__dirname4, "skills", "truecourse");
@@ -4336,6 +4352,20 @@ async function promptInstallSkills(repoPath) {
   O2.message("  - truecourse-list     (list violations)");
   O2.message("  - truecourse-fix      (apply fixes)");
 }
+async function promptInstallSkills(repoPath, { install } = {}) {
+  if (hasInstalledSkills(repoPath)) return;
+  if (install === true) {
+    copySkillsInto(repoPath);
+    return;
+  }
+  if (install === false) return;
+  if (!isInteractive()) return;
+  const answer = await ot2({
+    message: "Would you like to install Claude Code skills?"
+  });
+  if (q(answer) || !answer) return;
+  copySkillsInto(repoPath);
+}
 var DEFAULT_PORT, DEFAULT_CONFIG;
 var init_helpers = __esm({
   "tools/cli/src/commands/helpers.ts"() {
@@ -126557,7 +126587,7 @@ init_dist4();
 init_paths();
 init_registry();
 init_helpers();
-async function runAdd() {
+async function runAdd(options = {}) {
   const repoPath = resolveRepoDir(process.cwd()) ?? process.cwd();
   mt("Adding repository to TrueCourse");
   O2.step(repoPath);
@@ -126569,7 +126599,7 @@ async function runAdd() {
   } else {
     O2.success(`Repository "${entry.name}" added.`);
   }
-  await promptInstallSkills(repoPath);
+  await promptInstallSkills(repoPath, { install: options.installSkills });
   gt("Run `truecourse analyze` to generate analysis data.");
 }
 
@@ -126598,12 +126628,20 @@ init_helpers();
 
 // tools/cli/src/commands/llm-prompt.ts
 init_dist4();
-async function promptLlmEstimate(estimate) {
+init_helpers();
+async function promptLlmEstimate(estimate, { autoApprove } = {}) {
   const totalRules = estimate.uniqueRuleCount ?? estimate.tiers.reduce((s, t2) => s + t2.ruleCount, 0);
   const totalFiles = estimate.uniqueFileCount ?? estimate.tiers.reduce((s, t2) => s + t2.fileCount, 0);
   const tokens = estimate.totalEstimatedTokens;
   const tokenStr = tokens >= 1e6 ? `~${(tokens / 1e6).toFixed(1)}M tokens` : `~${Math.round(tokens / 1e3)}k tokens`;
   O2.step(`LLM will analyze ${totalFiles} files with ${totalRules} rules (${tokenStr})`);
+  if (autoApprove) return true;
+  if (!isInteractive()) {
+    O2.error(
+      "Cannot prompt for LLM-rule confirmation non-interactively. Pass --llm to approve the estimate or --no-llm to skip LLM rules."
+    );
+    return false;
+  }
   const proceed = await ot2({ message: "Run LLM-powered rules?", initialValue: true });
   if (q(proceed)) return false;
   if (!proceed) O2.info("Skipping LLM rules.");
@@ -126751,18 +126789,31 @@ function stopSpinner() {
     spinnerInterval = null;
   }
 }
-async function runAnalyze(_options = {}) {
+function resolveLlmDecision(options, configDefault) {
+  if (options.llm === true) return { enabled: true, autoApproveEstimate: true };
+  if (options.llm === false) return { enabled: false, autoApproveEstimate: false };
+  if (!isInteractive()) {
+    exitMissingNonInteractiveFlag(
+      "analyze needs a decision on LLM rules before running non-interactively.",
+      "Pass --llm to run with LLM rules (cost) or --no-llm to skip them."
+    );
+  }
+  return { enabled: configDefault, autoApproveEstimate: false };
+}
+async function runAnalyze(options = {}) {
   mt("Analyzing repository");
   ensureClaudeCli();
   showFirstRunNotice();
   const project = resolveOrInitProject();
   O2.step(`Repository: ${project.name}`);
+  await promptInstallSkills(project.path, { install: options.installSkills });
   configureLogger({
     filePath: path16.join(project.path, ".truecourse/logs/analyze.log")
   });
   const config2 = readProjectConfig(project.path);
   const enabledCategories = config2.enabledCategories ?? void 0;
-  const enableLlmRules = config2.enableLlmRules ?? true;
+  const llmDecision = resolveLlmDecision(options, config2.enableLlmRules ?? true);
+  const enableLlmRules = llmDecision.enabled;
   renderPhase = enableLlmRules ? "pre-llm" : "all";
   if (wipeLegacyPostgresData()) {
     O2.info("Legacy Postgres data wiped. Re-analyze to repopulate.");
@@ -126782,7 +126833,9 @@ async function runAnalyze(_options = {}) {
       enableLlmRulesOverride: enableLlmRules,
       onLlmEstimate: async (estimate) => {
         stopSpinner();
-        const proceed = await promptLlmEstimate(estimate);
+        const proceed = await promptLlmEstimate(estimate, {
+          autoApprove: llmDecision.autoApproveEstimate
+        });
         renderPhase = "post-llm";
         return proceed;
       }
@@ -126804,7 +126857,7 @@ async function runAnalyze(_options = {}) {
     await closeLogger();
   }
 }
-async function runAnalyzeDiff(_options = {}) {
+async function runAnalyzeDiff(options = {}) {
   const { diffInProcess: diffInProcess2 } = await Promise.resolve().then(() => (init_diff_in_process(), diff_in_process_exports));
   const { renderDiffResultsSummary: renderDiffResultsSummary2 } = await Promise.resolve().then(() => (init_helpers(), helpers_exports));
   mt("Running diff check");
@@ -126812,12 +126865,14 @@ async function runAnalyzeDiff(_options = {}) {
   showFirstRunNotice();
   const project = resolveOrInitProject();
   O2.step(`Repository: ${project.name}`);
+  await promptInstallSkills(project.path, { install: options.installSkills });
   configureLogger({
     filePath: path16.join(project.path, ".truecourse/logs/analyze.log")
   });
   const config2 = readProjectConfig(project.path);
   const enabledCategories = config2.enabledCategories ?? void 0;
-  const enableLlmRules = config2.enableLlmRules ?? true;
+  const llmDecision = resolveLlmDecision(options, config2.enableLlmRules ?? true);
+  const enableLlmRules = llmDecision.enabled;
   renderPhase = enableLlmRules ? "pre-llm" : "all";
   const stepDefs = buildAnalysisSteps(enabledCategories, enableLlmRules);
   const tracker = new StepTracker((payload) => {
@@ -126834,7 +126889,9 @@ async function runAnalyzeDiff(_options = {}) {
       enableLlmRulesOverride: enableLlmRules,
       onLlmEstimate: async (estimate) => {
         stopSpinner();
-        const proceed = await promptLlmEstimate(estimate);
+        const proceed = await promptLlmEstimate(estimate, {
+          autoApprove: llmDecision.autoApproveEstimate
+        });
         renderPhase = "post-llm";
         return proceed;
       }
@@ -127370,6 +127427,27 @@ async function runServiceMode(serverEntry) {
   O2.success(`Dashboard open at ${target}`);
   O2.info("Stop the dashboard with: truecourse dashboard stop");
 }
+async function probeHealth(url) {
+  try {
+    const res = await fetch(`${url}/api/health`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function detectRunningState() {
+  const platform = getPlatform();
+  const url = getServerUrl();
+  const healthy = await probeHealth(url);
+  if (await platform.isInstalled()) {
+    const { running, pid } = await platform.status();
+    if (running) return { mode: "service", pid, healthy };
+    if (healthy) return { mode: "console", healthy: true };
+    return { mode: "none" };
+  }
+  if (healthy) return { mode: "console", healthy: true };
+  return { mode: "none" };
+}
 async function runDashboard(options = {}) {
   mt("Opening TrueCourse dashboard");
   const serverEntry = resolveServerEntry();
@@ -127380,9 +127458,34 @@ async function runDashboard(options = {}) {
     process.exit(1);
   }
   const configured = fs15.existsSync(getConfigPath());
-  const shouldPrompt = !configured || options.reconfigure;
-  const runMode = shouldPrompt ? await promptRunMode() : readConfig().runMode;
-  if (shouldPrompt) writeConfig({ runMode });
+  const needsDecision = !configured || options.reconfigure;
+  let runMode;
+  if (options.mode) {
+    runMode = options.mode;
+  } else if (needsDecision) {
+    if (!isInteractive()) {
+      exitMissingNonInteractiveFlag(
+        "Dashboard run mode is not configured.",
+        "Pass --service for the background service or --console to run in this terminal."
+      );
+    }
+    runMode = await promptRunMode();
+  } else {
+    runMode = readConfig().runMode;
+  }
+  const shouldPersist = needsDecision || options.mode !== void 0;
+  if (runMode !== "service") {
+    const platform = getPlatform();
+    if (await platform.isInstalled()) {
+      const { running } = await platform.status();
+      if (running) {
+        O2.error(
+          "A dashboard service is already installed and running. Stop and remove it first: `truecourse dashboard uninstall`, then rerun `truecourse dashboard`."
+        );
+        process.exit(1);
+      }
+    }
+  }
   if (runMode === "service") {
     try {
       await runServiceMode(serverEntry);
@@ -127390,70 +127493,68 @@ async function runDashboard(options = {}) {
       O2.error(`Service mode failed: ${err.message}`);
       O2.info("Falling back to console mode.");
       await runConsoleMode(serverEntry);
+      if (shouldPersist) writeConfig({ runMode: "console" });
+      return;
     }
+    if (shouldPersist) writeConfig({ runMode: "service" });
   } else {
     await runConsoleMode(serverEntry);
+    if (shouldPersist) writeConfig({ runMode: "console" });
   }
 }
 async function runDashboardStop() {
-  const config2 = readConfig();
-  if (config2.runMode !== "service") {
-    O2.info("Dashboard is running in console mode. Press Ctrl+C in its terminal to stop.");
-    return;
-  }
-  const platform = getPlatform();
-  const { running } = await platform.status();
-  if (!running) {
-    O2.info("Dashboard is not running.");
-    return;
+  const state = await detectRunningState();
+  switch (state.mode) {
+    case "service": {
+      O2.step("Stopping dashboard service...");
+      await getPlatform().stop();
+      O2.success("Dashboard service stopped.");
+      return;
+    }
+    case "console": {
+      O2.info(
+        "A dashboard is running in console mode (not managed by the service). Press Ctrl+C in its terminal to stop it."
+      );
+      return;
+    }
+    case "none": {
+      O2.info("Dashboard is not running.");
+      return;
+    }
   }
-  O2.step("Stopping dashboard...");
-  await platform.stop();
-  O2.success("Dashboard stopped.");
 }
 async function runDashboardStatus() {
-  const config2 = readConfig();
+  const state = await detectRunningState();
   const url = getServerUrl();
-  if (config2.runMode !== "service") {
-    try {
-      const res = await fetch(`${url}/api/health`);
-      if (res.ok) {
-        O2.success(`Dashboard is running in console mode at ${url}`);
+  switch (state.mode) {
+    case "service": {
+      const pidInfo = state.pid ? ` (PID: ${state.pid})` : "";
+      O2.success(`Dashboard service is running${pidInfo}`);
+      if (state.healthy) {
+        O2.info(`Server is healthy at ${url}`);
       } else {
-        O2.info("Dashboard is not running.");
+        O2.warn(`Service process is running but server is not responding at ${url}.`);
       }
-    } catch {
-      O2.info("Dashboard is not running.");
+      return;
     }
-    return;
-  }
-  const platform = getPlatform();
-  const installed = await platform.isInstalled();
-  if (!installed) {
-    O2.info("Dashboard service is not installed. Run `truecourse dashboard` to set it up.");
-    return;
-  }
-  const { running, pid } = await platform.status();
-  if (!running) {
-    O2.info("Dashboard service is installed but not running.");
-    return;
-  }
-  const pidInfo = pid ? ` (PID: ${pid})` : "";
-  O2.success(`Dashboard service is running${pidInfo}`);
-  try {
-    const res = await fetch(`${url}/api/health`);
-    if (res.ok) {
-      O2.info(`Server is healthy at ${url}`);
-    } else {
-      O2.warn(`Server returned status ${res.status}`);
+    case "console": {
+      O2.success(`Dashboard is running in console mode at ${url}`);
+      return;
+    }
+    case "none": {
+      const platform = getPlatform();
+      if (await platform.isInstalled()) {
+        O2.info("Dashboard service is installed but not running.");
+      } else {
+        O2.info("Dashboard is not running.");
+      }
+      return;
     }
-  } catch {
-    O2.warn("Service process is running but server is not responding.");
   }
 }
-function runDashboardLogs() {
-  const config2 = readConfig();
-  if (config2.runMode !== "service") {
+async function runDashboardLogs() {
+  const state = await detectRunningState();
+  if (state.mode === "console") {
     O2.info("Dashboard is running in console mode \u2014 logs print to its terminal.");
     return;
   }
@@ -127490,6 +127591,7 @@ var SEVERITY_ORDER = {
   low: 3,
   info: 4
 };
+var SEVERITIES = ["critical", "high", "medium", "low", "info"];
 function listViolations(repoPath, options = {}) {
   const latest = readLatest(repoPath);
   if (!latest)
@@ -127517,6 +127619,10 @@ function listViolations(repoPath, options = {}) {
     const absPath = options.filePath.startsWith("/") ? options.filePath : `${repoPath}/${options.filePath}`;
     filtered = filtered.filter((v) => v.type === "code" && (v.filePath === absPath || v.filePath === options.filePath));
   }
+  if (options.severity !== void 0) {
+    const allowed = (Array.isArray(options.severity) ? options.severity : [options.severity]).map((s) => s.toLowerCase());
+    filtered = filtered.filter((v) => allowed.includes(v.severity.toLowerCase()));
+  }
   filtered.sort((a, b) => {
     const sa = SEVERITY_ORDER[a.severity] ?? 5;
     const sb = SEVERITY_ORDER[b.severity] ?? 5;
@@ -127577,19 +127683,37 @@ function getDiffResult(repoPath) {
 
 // tools/cli/src/commands/list.ts
 init_helpers();
-async function runList({ limit = 20, offset = 0 } = {}) {
+async function runList({ limit = 20, offset = 0, severity } = {}) {
   mt("Violations");
   const repo = requireRegisteredRepo();
   const { violations, total } = listViolations(repo.path, {
     limit: isFinite(limit) ? limit : 0,
-    offset
+    offset,
+    severity
   });
   if (total === 0 && violations.length === 0) {
-    O2.info("No violations. Run `truecourse analyze` if you haven't yet.");
+    if (severity && severity.length > 0) {
+      O2.info(`No violations match severity filter: ${severity.join(", ")}.`);
+    } else {
+      O2.info("No violations. Run `truecourse analyze` if you haven't yet.");
+    }
     return;
   }
   renderViolations(violations, { total, offset });
 }
+function parseSeverityFlag(raw) {
+  if (!raw) return void 0;
+  const parts = raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (parts.length === 0) return void 0;
+  const invalid = parts.filter((s) => !SEVERITIES.includes(s));
+  if (invalid.length > 0) {
+    console.error(
+      `error: unknown severity value(s): ${invalid.join(", ")}. Valid: ${SEVERITIES.join(", ")}`
+    );
+    process.exit(1);
+  }
+  return parts;
+}
 async function runListDiff() {
   mt("Diff check results");
   const repo = requireRegisteredRepo();
@@ -130571,9 +130695,14 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.5.0").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
-var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").action(async (options) => {
-  await runDashboard({ reconfigure: options.reconfigure });
+program2.name("truecourse").version("0.5.1").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").option("--service", "Run as a background service (skips mode prompt)").option("--console", "Run in this terminal (skips mode prompt)").action(async (options) => {
+  if (options.service && options.console) {
+    console.error("error: --service and --console are mutually exclusive");
+    process.exit(1);
+  }
+  const mode = options.service ? "service" : options.console ? "console" : void 0;
+  await runDashboard({ reconfigure: options.reconfigure, mode });
 });
 dashboardCmd.command("stop").description("Stop the dashboard").action(async () => {
   await runDashboardStop();
@@ -130581,29 +130710,40 @@ dashboardCmd.command("stop").description("Stop the dashboard").action(async () =
 dashboardCmd.command("status").description("Show dashboard status").action(async () => {
   await runDashboardStatus();
 });
-dashboardCmd.command("logs").description("Tail dashboard logs (service mode only)").action(() => {
-  runDashboardLogs();
+dashboardCmd.command("logs").description("Tail dashboard logs (service mode only)").action(async () => {
+  await runDashboardLogs();
 });
 dashboardCmd.command("uninstall").description("Remove the background service and revert to console mode").action(async () => {
   await runDashboardUninstall();
 });
-program2.command("analyze").description("Analyze the current repository").option("--diff", "Run diff check against latest analysis").action(async (options) => {
+function resolveInstallSkills(options) {
+  if (options.installSkills === true) return true;
+  if (options.skills === false) return false;
+  return void 0;
+}
+program2.command("analyze").description("Analyze the current repository").option("--diff", "Run diff check against latest analysis").option("--llm", "Run LLM-powered rules (pre-approves the cost estimate)").option("--no-llm", "Skip LLM-powered rules for this run").option("--install-skills", "Install Claude Code skills without prompting").option("--no-skills", "Skip the Claude Code skills prompt").action(async (options) => {
+  const llm = typeof options.llm === "boolean" ? options.llm : void 0;
+  const installSkills = resolveInstallSkills(options);
   if (options.diff) {
-    await runAnalyzeDiff();
+    await runAnalyzeDiff({ llm, installSkills });
   } else {
-    await runAnalyze();
+    await runAnalyze({ llm, installSkills });
   }
 });
-program2.command("add").description("Register the current directory with TrueCourse").action(async () => {
-  await runAdd();
+program2.command("add").description("Register the current directory with TrueCourse").option("--install-skills", "Install Claude Code skills without prompting").option("--no-skills", "Skip the Claude Code skills prompt").action(async (options) => {
+  await runAdd({ installSkills: resolveInstallSkills(options) });
 });
-program2.command("list").description("List violations from the latest analysis").option("--diff", "Show diff check results (new and resolved)").option("--limit <n>", "Number of violations to show (default: 20)", parseInt).option("--offset <n>", "Skip first N violations", parseInt).option("--all", "Show all violations").action(async (options) => {
+program2.command("list").description("List violations from the latest analysis").option("--diff", "Show diff check results (new and resolved)").option("--limit <n>", "Number of violations to show (default: 20)", parseInt).option("--offset <n>", "Skip first N violations", parseInt).option("--all", "Show all violations").option(
+  "--severity <list>",
+  "Comma-separated severities to include (critical,high,medium,low,info)"
+).action(async (options) => {
   if (options.diff) {
     await runListDiff();
   } else {
     await runList({
       limit: options.all ? Infinity : options.limit ?? 20,
-      offset: options.offset ?? 0
+      offset: options.offset ?? 0,
+      severity: parseSeverityFlag(options.severity)
     });
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truecourse",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {

package/server.mjs

@@ -152216,6 +152216,10 @@ function listViolations(repoPath, options = {}) {
       (v) => v.type === "code" && (v.filePath === absPath || v.filePath === options.filePath)
     );
   }
+  if (options.severity !== void 0) {
+    const allowed = (Array.isArray(options.severity) ? options.severity : [options.severity]).map((s) => s.toLowerCase());
+    filtered = filtered.filter((v) => allowed.includes(v.severity.toLowerCase()));
+  }
   filtered.sort((a, b) => {
     const sa = SEVERITY_ORDER2[a.severity] ?? 5;
     const sb = SEVERITY_ORDER2[b.severity] ?? 5;
@@ -153596,10 +153600,15 @@ router5.get(
       const offsetParam = parseInt(req.query.offset) || 0;
       const statusParam = req.query.status;
       const status = statusParam === "resolved" ? "resolved" : statusParam === "all" ? "all" : "active";
+      const severityParam = req.query.severity;
+      const severity = severityParam ? severityParam.split(",").map((s) => s.trim().toLowerCase()).filter(
+        (s) => ["critical", "high", "medium", "low", "info"].includes(s)
+      ) : void 0;
       const { violations, total } = listViolations(repo.path, {
         analysisId: req.query.analysisId,
         filePath: req.query.file,
         status,
+        severity: severity && severity.length > 0 ? severity : void 0,
         limit: limitParam,
         offset: offsetParam
       });

package/skills/truecourse/truecourse-analyze/SKILL.md

@@ -15,25 +15,42 @@ Run architecture analysis on the current repository using TrueCourse.
 
 ## Important
 
-- The TrueCourse server must be running before using this skill. If it's not running, tell the user to start it with `npx truecourse start` and try again.
-- Full analysis stashes any uncommitted changes, analyzes the clean working tree, then unstashes. The user's uncommitted work is preserved.
-- Diff check analyzes only files changed since the last analysis — it does NOT stash.
+- **Full analysis** stashes any uncommitted changes, analyzes the clean working tree, then unstashes. The user's uncommitted work is preserved.
+- **Diff check** analyzes the full working tree (including uncommitted changes — it does NOT stash) and compares the result against the last full analysis baseline. The report lists violations newly introduced and violations resolved since that baseline. Prefer diff for in-progress work where the user is iterating on changes.
+- **Always invoke via `npx -y`** — without `-y`, npx will hang on the "Ok to proceed?" prompt whenever the user hasn't cached the latest `truecourse` version (which happens every time we publish a new release).
+- **LLM rules cost real money.** Never pass `--llm` without first relaying the cost estimate to the user and getting approval. See the LLM flow below.
 
 ## Instructions
 
-1. Ask the user whether they want a **full analysis** or a **diff check** (changes only). If they mentioned "diff" in their request, default to diff mode.
+### 1. Pick mode
+Ask the user whether they want a **full analysis** or a **diff check**. If they said "diff" in their request, default to diff.
 
-2. Run the appropriate command using the Bash tool:
-   - **Full analysis:** `npx truecourse analyze --no-autostart`
-   - **Diff check:** `npx truecourse analyze --diff --no-autostart`
+- Full: `npx -y truecourse analyze`
+- Diff: `npx -y truecourse analyze --diff`
 
-3. This is a long-running command (can take several minutes). Let it run to completion — do NOT set a short timeout. Use a timeout of at least 600000ms (10 minutes).
+### 2. Decide on LLM rules
 
-4. If the command fails with "Could not connect to TrueCourse server", tell the user to run `npx truecourse start` first.
+LLM rules add higher-value insights but cost money per run. Ask the user one question: **"Run LLM-powered rules this time?"** If the user is unsure, offer to run deterministic-only first (free, fast) and add LLM later.
 
-5. When the command finishes, summarize the output for the user:
-   - Number of violations found (by severity)
-   - Number of changed files (for diff mode)
-   - Any errors that occurred
+- If **user approves LLM**: append `--llm` to the command.
+- If **user declines LLM or wants a free run**: append `--no-llm`.
 
-6. After summarizing, tell the user they can run `/truecourse-list` to see the full violation details, or `/truecourse-fix` to apply suggested fixes.
+You MUST pass either `--llm` or `--no-llm` — running without either in a non-interactive shell will exit with an error naming the flags.
+
+### 3. Run the command
+
+Use the Bash tool. This is long-running (minutes, especially with `--llm`) — use a timeout of at least 600000ms (10 minutes).
+
+### 4. Summarize
+
+When the command finishes, read the printed summary and relay the key numbers:
+
+- **Full analyze**: one line with the total violation count and per-severity breakdown, e.g. `15 violations (2 critical, 5 high, 8 medium)`.
+- **Diff analyze**: `Changed files: N (X modified, Y new, Z deleted)` and `Summary: N new issues, N resolved`. If you see `⚠ Results may be stale — baseline analysis has changed.`, surface that warning to the user and suggest running a full `npx -y truecourse analyze` to refresh the baseline.
+- If the command errored, relay the error message.
+
+### 5. Next steps
+
+Tell the user they can:
+- Run `/truecourse-list` to see the full violation list.
+- Run `/truecourse-fix` to apply suggested fixes.

package/skills/truecourse/truecourse-fix/SKILL.md

@@ -6,29 +6,55 @@ triggers:
   - fix violations
   - apply fixes
   - fix my code
+  - fix diff violations
 ---
 
 # TrueCourse Fix
 
 Apply fixes for TrueCourse violations that have fix suggestions.
 
+## Important
+
+- **Always invoke via `npx -y`** — without `-y`, npx will hang on the "Ok to proceed?" prompt whenever the user hasn't cached the latest `truecourse` version.
+- **Default to the diff flow.** Users usually want to fix the violations introduced by the changes they're currently iterating on — not the whole repo. Start by asking which set to fix.
+- **Only violations with a `Fix:` block can be auto-fixed.** Violations without one require human design decisions; mention them but don't attempt them.
+
 ## Instructions
 
-1. First, fetch the current violations by running:
-   ```
-   npx truecourse list
-   ```
+### 1. Pick the violation set
+
+Ask: *"Do you want to fix violations from the latest full analysis, or just the changes you're working on right now (diff)?"*
+
+- **Diff mode** (recommended default): `npx -y truecourse list --diff` — small set, usually fine to load in one call.
+- **Full mode**: start with a paged view, `npx -y truecourse list` (first 20). If the summary line shows a large total and the user hasn't narrowed scope, ask them to narrow before pulling more pages:
+  - by severity — use `--severity <list>`, e.g. `npx -y truecourse list --severity critical,high`. Valid values: `critical,high,medium,low,info`.
+  - by a specific file / module / service they care about — no server-side filter yet, so page through and keep only matches.
+
+  Avoid `--all` on large repos — it dumps every violation into context even though most won't be fixable.
+
+If `list --diff` returns "no diff results yet" or "stale diff", suggest the user first run `/truecourse-analyze` in diff mode.
+
+### 2. Identify fixable violations
+
+From the output in hand, keep only violations that contain a `Fix:` block — those are the ones with actionable fix suggestions. If you loaded only one page in full mode, tell the user how many were fixable on this page and offer to continue to the next page (`--offset 20`, `--offset 40`, …) if they want more.
+
+If none on the loaded page(s) are fixable, tell the user and stop (or offer to page further).
+
+### 3. Present and select
+
+Show the fixable violations as a numbered list with title, severity, and target location. Ask which ones to fix (they can pick numbers or say "all").
 
-2. Parse the output to identify violations that have a **Fix:** suggestion. These are the only violations that can be automatically fixed.
+### 4. Apply
 
-3. If no violations have fix suggestions, tell the user and stop.
+For each selected violation:
+- Read the `Fix:` text.
+- Use the Read tool to load the relevant source file(s).
+- Use the Edit tool to apply the change.
+- Briefly describe what you changed.
 
-4. Present the fixable violations to the user as a numbered list with their title, severity, and target location. Ask which ones they'd like to fix (they can pick specific numbers or say "all").
+### 5. Re-verify
 
-5. For each selected violation, read the fix suggestion and apply it to the codebase:
-   - The fix suggestion describes what code change to make
-   - Use the Read tool to read the relevant source file(s)
-   - Use the Edit tool to apply the fix
-   - Explain what you changed
+After fixes, suggest the user re-run the appropriate analysis to confirm the violations are resolved:
 
-6. After applying fixes, suggest the user run `/truecourse-analyze` again to verify the fixes resolved the violations.
+- If you worked in **diff mode**: run `npx -y truecourse analyze --diff --no-llm` (fast, free). If they want LLM rules re-checked too, use `--llm` and relay the cost estimate first.
+- If you worked in **full mode**: suggest `/truecourse-analyze` so the user picks the LLM/no-LLM decision fresh.

package/skills/truecourse/truecourse-list/SKILL.md

@@ -13,14 +13,29 @@ triggers:
 
 Show violations and analysis results from TrueCourse.
 
+## Important
+
+- **Always invoke via `npx -y`** — without `-y`, npx will hang on the "Ok to proceed?" prompt whenever the user hasn't cached the latest `truecourse` version.
+- **Don't dump everything at once.** Plain `list` shows the first 20 violations — use that by default. Large repos can have hundreds; pasting them all wastes context and the user can't read that much in one go. Page or filter instead.
+
 ## Instructions
 
-1. Determine whether to show **full violations** or **diff results**. If the user mentioned "diff" in their request, use diff mode.
+### 1. Pick mode
+Determine whether the user wants **full violations** (from the last full analysis) or **diff results** (changes since the last full analysis). If they said "diff" in their request, use diff mode.
+
+- Full: `npx -y truecourse list`
+- Diff: `npx -y truecourse list --diff`
+
+### 2. Run and present
+
+Use the Bash tool. The output is already formatted — show it as-is.
 
-2. Run the appropriate command using the Bash tool:
-   - **Full violations:** `npx truecourse list`
-   - **Diff results:** `npx truecourse list --diff`
+The final line summarises totals, e.g. `Showing 1–20 of 287 violations (12 critical, 45 high, ...)`. Lead your reply with that total + severity breakdown so the user knows the scope before scanning the first page.
 
-3. Present the output to the user. The command output is already formatted — show it as-is.
+### 3. Offer the next step
 
-4. If violations with fix suggestions are found, tell the user they can run `/truecourse-fix` to apply fixes.
+After showing the first page, ask the user what they want:
+- **Filter by severity** — `--severity <list>`, e.g. `--severity critical,high`. Valid values: `critical,high,medium,low,info`.
+- **Page further** — use `--offset <n>` (next page is `--offset 20`, then `--offset 40`, …) or widen with `--limit <n>`.
+- **Everything in one view** — `--all` (only when the user explicitly asks for the full dump, e.g. "show all of them", "give me the whole list"). Avoid by default.
+- **Start fixing** — `/truecourse-fix` (only for violations with a `Fix:` block attached).