truecourse 0.5.0 → 0.5.2

package/README.md

@@ -90,12 +90,26 @@ truecourse rules llm --disable                 # Disable LLM rules
 
 ### Git Hooks
 
-TrueCourse can install a pre-commit hook that blocks commits with critical violations:
+TrueCourse can install a pre-commit hook that blocks commits introducing new violations at or above a configured severity:
 
 ```bash
 truecourse hooks install              # Install pre-commit hook
 truecourse hooks uninstall            # Remove pre-commit hook
-truecourse hooks status               # Show hook installation status
+truecourse hooks status               # Show hook status + config
+```
+
+On every commit the hook runs `truecourse analyze --diff` against the repo's last full analysis and blocks if any newly-introduced violation matches the configured block severities. **Commits will take as long as a full diff analysis** — on large repos that can be tens of seconds per commit. `truecourse hooks install` warns you and requires confirmation before writing the hook.
+
+**First-time setup:** run `truecourse analyze` once to establish a baseline. Without it the hook can't diff.
+
+**Bypass:** `git commit --no-verify` (standard git).
+
+**Configuration** — `hooks install` seeds `<repo>/.truecourse/hooks.yaml` with starter defaults; commit the file so your team shares one policy. The hook reads only from this file — if you delete it, the hook warns and passes every commit (no hidden code-level defaults). Current shape:
+
+```yaml
+pre-commit:
+  block-on: [critical, high]   # severities. Valid: info|low|medium|high|critical
+  llm: false                   # run LLM rules on every commit (tokens per commit)
 ```
 
 ### Telemetry
@@ -131,13 +145,14 @@ TrueCourse ships with **1,200+ deterministic rules** and **100 LLM rules** acros
 
 TrueCourse includes [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) for conversational analysis from within Claude Code.
 
-Run `truecourse add` to install skills to `.claude/skills/truecourse/` in your project.
+The first `truecourse analyze` (or `truecourse add`) in a fresh repo asks whether to install skills into `.claude/skills/truecourse/`. Re-runs skip the prompt if skills are already present. Pass `--install-skills` / `--no-skills` to bypass the prompt explicitly.
 
 | Skill | What it does |
 |---|---|
 | `/truecourse-analyze` | Runs analysis or diff check, summarizes results |
 | `/truecourse-list` | Shows full violation details |
 | `/truecourse-fix` | Lists fixable violations, applies changes |
+| `/truecourse-hooks` | Installs, configures, or removes the pre-commit hook |
 
 ## Language Support
 
@@ -172,6 +187,10 @@ pnpm build              # Build all packages
 
 TrueCourse collects anonymous usage data (event type, language, file count range, OS). No source code, file paths, or violation details are collected. Opt out with `truecourse telemetry disable` or `TRUECOURSE_TELEMETRY=0`.
 
+## Contact
+
+Questions, feedback, or security reports: **Mushegh Gevorgyan** — [mushegh@truecourse.dev](mailto:mushegh@truecourse.dev).
+
 ## License
 
 MIT

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();
@@ -130310,6 +130434,11 @@ var jsYaml = {
 };
 
 // tools/cli/src/commands/hooks.ts
+init_dist4();
+init_paths();
+init_registry();
+init_analysis_store();
+init_diff_in_process();
 init_helpers();
 var HOOK_IDENTIFIER = "# TrueCourse pre-commit hook";
 var HOOK_SCRIPT = `#!/bin/sh
@@ -130317,29 +130446,35 @@ ${HOOK_IDENTIFIER}
 # Installed by: truecourse hooks install
 # Bypass with: git commit --no-verify
 
-exec truecourse hooks run
+exec npx -y truecourse hooks run
+`;
+var SEVERITIES2 = ["info", "low", "medium", "high", "critical"];
+var HOOKS_YAML_TEMPLATE = `# TrueCourse pre-commit hook config.
+# Commit this file \u2014 it's the team-shared policy for what blocks a commit.
+# Check the live values with \`truecourse hooks status\`.
+pre-commit:
+  # Severities that block a commit when the diff surfaces NEW violations
+  # at that level. Valid: info, low, medium, high, critical.
+  block-on:
+    - critical
+    - high
+
+  # Run LLM-powered rules on every commit? Off by default (no tokens per
+  # commit). Set to true for deeper semantic checks at the commit gate \u2014
+  # each commit will then cost tokens.
+  llm: false
 `;
-var DEFAULT_BLOCK_ON = [
-  "security/deterministic/hardcoded-secret",
-  { severity: "critical" }
-];
-var DEFAULT_TIMEOUT_MS = 3e4;
 function findGitDir(from) {
   let dir = from;
   while (true) {
     const gitPath = path21.join(dir, ".git");
     if (fs16.existsSync(gitPath)) {
       const stat = fs16.statSync(gitPath);
-      if (stat.isDirectory()) {
-        return gitPath;
-      }
+      if (stat.isDirectory()) return gitPath;
       if (stat.isFile()) {
         const content = fs16.readFileSync(gitPath, "utf-8").trim();
         const match2 = content.match(/^gitdir:\s*(.+)$/);
-        if (match2) {
-          const resolved = path21.resolve(dir, match2[1]);
-          return resolved;
-        }
+        if (match2) return path21.resolve(dir, match2[1]);
       }
     }
     const parent = path21.dirname(dir);
@@ -130350,46 +130485,68 @@ function findGitDir(from) {
 function findProjectRoot(from) {
   let dir = from;
   while (true) {
-    if (fs16.existsSync(path21.join(dir, ".git"))) {
-      return dir;
-    }
+    if (fs16.existsSync(path21.join(dir, ".git"))) return dir;
     const parent = path21.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
 }
-function parseTimeout(value) {
-  const match2 = value.match(/^(\d+)\s*(s|ms|m)?$/);
-  if (!match2) return DEFAULT_TIMEOUT_MS;
-  const num = parseInt(match2[1], 10);
-  const unit = match2[2] || "s";
-  if (unit === "ms") return num;
-  if (unit === "m") return num * 6e4;
-  return num * 1e3;
-}
 function loadConfig(projectRoot) {
   const configPath = path21.join(projectRoot, ".truecourse", "hooks.yaml");
-  if (!fs16.existsSync(configPath)) return {};
+  if (!fs16.existsSync(configPath)) return null;
+  let parsed;
   try {
     const raw = fs16.readFileSync(configPath, "utf-8");
-    return jsYaml.load(raw) || {};
-  } catch {
-    return {};
+    parsed = jsYaml.load(raw) || {};
+  } catch (err) {
+    console.error(`Error parsing ${configPath}: ${err.message}`);
+    process.exit(1);
   }
+  const preCommit = parsed["pre-commit"] ?? {};
+  const rawBlockOn = preCommit["block-on"];
+  if (!Array.isArray(rawBlockOn)) {
+    console.error(
+      `Invalid ${configPath}: \`pre-commit.block-on\` must be an array of severity names.`
+    );
+    console.error(`  Valid severities: ${SEVERITIES2.join(", ")}`);
+    process.exit(1);
+  }
+  const invalid = rawBlockOn.filter(
+    (s) => typeof s !== "string" || !SEVERITIES2.includes(s)
+  );
+  if (invalid.length > 0) {
+    console.error(
+      `Invalid ${configPath}: unknown value(s) in \`pre-commit.block-on\`: ${invalid.map((v) => JSON.stringify(v)).join(", ")}`
+    );
+    console.error(`  Valid severities: ${SEVERITIES2.join(", ")}`);
+    process.exit(1);
+  }
+  return {
+    blockOn: rawBlockOn,
+    llm: preCommit.llm === true,
+    configPath
+  };
 }
-function getBlockRules(config2) {
-  return config2["pre-commit"]?.["block-on"] ?? DEFAULT_BLOCK_ON;
-}
-function getTimeoutMs(config2) {
-  const raw = config2["pre-commit"]?.timeout;
-  return raw ? parseTimeout(raw) : DEFAULT_TIMEOUT_MS;
-}
-function runHooksInstall() {
+var INSTALL_WARNING = "The pre-commit hook runs `truecourse analyze --diff` on every commit.\nCommits will take as long as a full diff analysis of this repo \u2014\non large repos that can be tens of seconds per commit.";
+async function runHooksInstall() {
   const gitDir = findGitDir(process.cwd());
   if (!gitDir) {
     console.error("Error: Not a git repository.");
     process.exit(1);
   }
+  if (isInteractive()) {
+    O2.warn(INSTALL_WARNING);
+    const proceed = await ot2({
+      message: "Install the pre-commit hook?",
+      initialValue: false
+    });
+    if (q(proceed) || !proceed) {
+      pt("Install cancelled.");
+      process.exit(0);
+    }
+  } else {
+    console.log(INSTALL_WARNING);
+  }
   const hooksDir = path21.join(gitDir, "hooks");
   fs16.mkdirSync(hooksDir, { recursive: true });
   const hookPath = path21.join(hooksDir, "pre-commit");
@@ -130407,6 +130564,16 @@ function runHooksInstall() {
   fs16.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 493 });
   console.log("TrueCourse pre-commit hook installed.");
   console.log(`  ${hookPath}`);
+  const projectRoot = findProjectRoot(process.cwd());
+  if (projectRoot) {
+    const cfgDir = path21.join(projectRoot, ".truecourse");
+    const cfgPath = path21.join(cfgDir, "hooks.yaml");
+    if (!fs16.existsSync(cfgPath)) {
+      fs16.mkdirSync(cfgDir, { recursive: true });
+      fs16.writeFileSync(cfgPath, HOOKS_YAML_TEMPLATE);
+      console.log(`  ${cfgPath} (starter config \u2014 edit to customize, commit to share with the team)`);
+    }
+  }
 }
 function runHooksUninstall() {
   const gitDir = findGitDir(process.cwd());
@@ -130444,125 +130611,97 @@ function runHooksStatus() {
   }
   const projectRoot = findProjectRoot(process.cwd());
   if (projectRoot) {
-    const configPath = path21.join(projectRoot, ".truecourse", "hooks.yaml");
-    if (fs16.existsSync(configPath)) {
-      console.log(`
-Config: ${configPath}`);
-      const config2 = loadConfig(projectRoot);
-      const blockRules = getBlockRules(config2);
-      console.log("Block on:");
-      for (const rule of blockRules) {
-        if (typeof rule === "string") {
-          console.log(`  - ${rule}`);
-        } else {
-          console.log(`  - severity: ${rule.severity}`);
-        }
-      }
-      const timeoutMs = getTimeoutMs(config2);
-      console.log(`Timeout: ${timeoutMs / 1e3}s`);
+    const cfg = loadConfig(projectRoot);
+    if (!cfg) {
+      console.log(
+        "\nNo `.truecourse/hooks.yaml` \u2014 hook has no policy. Run `truecourse hooks install` to generate one."
+      );
     } else {
-      console.log("\nNo config file. Using defaults (block on: security/deterministic/hardcoded-secret, severity: critical).");
-    }
-  }
-}
-function shouldBlock(violation, blockRules) {
-  for (const rule of blockRules) {
-    if (typeof rule === "string") {
-      if (violation.ruleKey === rule || violation.ruleKey.endsWith(`/${rule}`)) {
-        return true;
-      }
-    } else if (rule.severity) {
-      if (violation.severity.toLowerCase() === rule.severity.toLowerCase()) {
-        return true;
-      }
+      console.log(`
+Config: ${cfg.configPath}`);
+      console.log(`Block on severities: ${cfg.blockOn.join(", ")}`);
+      console.log(`LLM rules on commit: ${cfg.llm ? "enabled (tokens per commit)" : "disabled"}`);
     }
   }
-  return false;
 }
 async function runHooksRun() {
-  const startTime = Date.now();
   process.stdout.write("TrueCourse pre-commit check...");
   const projectRoot = findProjectRoot(process.cwd());
   if (!projectRoot) {
     console.log(" skipped (not a git repository)");
     process.exit(0);
   }
-  const config2 = loadConfig(projectRoot);
-  const blockRules = getBlockRules(config2);
-  const timeoutMs = getTimeoutMs(config2);
-  let stagedFiles;
+  let hasStaged = false;
   try {
     const output = execSync5("git diff --cached --name-only --diff-filter=ACM", {
       encoding: "utf-8",
       cwd: projectRoot
     }).trim();
-    stagedFiles = output ? output.split("\n") : [];
+    hasStaged = output.length > 0;
   } catch {
     console.log(" skipped (git error)");
     process.exit(0);
   }
-  if (stagedFiles.length === 0) {
+  if (!hasStaged) {
     console.log(" \u2714 passed (no staged files)");
     process.exit(0);
   }
-  let parseCode2;
-  let detectLanguage2;
-  let checkCodeRules2;
-  let CODE_RULES2;
-  try {
-    const analyzer = await Promise.resolve().then(() => (init_dist6(), dist_exports2));
-    parseCode2 = analyzer.parseCode;
-    detectLanguage2 = analyzer.detectLanguage;
-    checkCodeRules2 = analyzer.checkCodeRules;
-    CODE_RULES2 = analyzer.CODE_RULES;
-    await analyzer.initParsers();
-  } catch {
-    console.log(" skipped (analyzer not available)");
+  const cfg = loadConfig(projectRoot);
+  if (!cfg) {
+    console.log(" skipped");
+    console.error(
+      "No `.truecourse/hooks.yaml` found. The pre-commit hook has no policy to\nenforce \u2014 run `truecourse hooks install` to generate one."
+    );
     process.exit(0);
   }
-  const supportedFiles = stagedFiles.filter((f) => detectLanguage2(f) !== null);
-  if (supportedFiles.length === 0) {
-    console.log(" \u2714 passed");
-    process.exit(0);
+  const repoDir = resolveRepoDir(process.cwd());
+  const project = repoDir ? getProjectByPath(repoDir) ?? registerProject(repoDir) : null;
+  if (!project || !readLatest(project.path)) {
+    console.log("");
+    console.error(
+      "No baseline analysis yet. Run `truecourse analyze` once in this repo before\nthe pre-commit hook can block new violations. Or bypass this commit with\n`git commit --no-verify`."
+    );
+    process.exit(1);
   }
-  const allViolations = [];
-  for (const filePath of supportedFiles) {
-    if (Date.now() - startTime > timeoutMs) {
-      console.log("\n  Warning: timeout reached, skipping remaining files.");
-      break;
-    }
-    const language = detectLanguage2(filePath);
-    if (!language) continue;
-    let content;
-    try {
-      content = execSync5(`git show ":${filePath}"`, {
-        encoding: "utf-8",
-        cwd: projectRoot,
-        maxBuffer: 5 * 1024 * 1024
-        // 5MB
-      });
-    } catch {
-      continue;
-    }
-    try {
-      const tree = parseCode2(content, language);
-      const violations = checkCodeRules2(tree, filePath, content, CODE_RULES2, language);
-      allViolations.push(...violations);
-    } catch {
-      continue;
+  const abortController = new AbortController();
+  const onSigint = () => abortController.abort();
+  process.on("SIGINT", onSigint);
+  process.stdout.write(" running analysis...");
+  let newViolations;
+  try {
+    const { diff } = await diffInProcess(project, {
+      signal: abortController.signal,
+      enableLlmRulesOverride: cfg.llm,
+      // Pre-approved: the user opted into LLM-in-hook by setting llm: true
+      // in hooks.yaml, so we don't re-prompt for the token cost estimate.
+      onLlmEstimate: async () => true
+    });
+    newViolations = diff.newViolations;
+  } catch (err) {
+    console.log("");
+    if (err instanceof DOMException && err.name === "AbortError") {
+      console.error("Pre-commit check cancelled.");
+      process.exit(130);
     }
+    console.error(`Pre-commit check failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  } finally {
+    process.removeListener("SIGINT", onSigint);
   }
-  const blocking = allViolations.filter((v) => shouldBlock(v, blockRules));
+  const blockSet = new Set(cfg.blockOn);
+  const blocking = newViolations.filter((v) => blockSet.has(v.severity.toLowerCase()));
   if (blocking.length === 0) {
-    console.log(" \u2714 passed");
+    console.log(` \u2714 passed (${newViolations.length} new violations, none at or above ${cfg.blockOn.join("/")})`);
     process.exit(0);
   }
   console.log("\n");
   for (const v of blocking) {
     const icon = severityIcon(v.severity);
     const color = severityColor(v.severity);
+    const location = v.filePath ? `${v.filePath}${v.lineStart ? `:${v.lineStart}` : ""}` : "(no file)";
     console.log(` ${color(`${icon} BLOCKED`)}: ${v.title}`);
-    console.log(`   ${v.filePath}:${v.lineStart} \u2014 ${v.content}`);
+    console.log(`   ${location} \u2014 ${v.content}`);
+    if (v.fixPrompt) console.log(`   Fix: ${v.fixPrompt}`);
     console.log("");
   }
   console.log("Commit blocked. Fix the issue or bypass with --no-verify.");
@@ -130571,9 +130710,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.2").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 +130725,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)
     });
   }
 });
@@ -130634,8 +130789,8 @@ telemetryCmd.command("status").description("Show current telemetry status").acti
   }
 });
 var hooksCmd = program2.command("hooks").description("Manage git hooks");
-hooksCmd.command("install").description("Install pre-commit hook").action(() => {
-  runHooksInstall();
+hooksCmd.command("install").description("Install pre-commit hook").action(async () => {
+  await runHooksInstall();
 });
 hooksCmd.command("uninstall").description("Remove pre-commit hook").action(() => {
   runHooksUninstall();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truecourse",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {
@@ -21,6 +21,10 @@
     "node-windows": "^1.0.0-beta.8"
   },
   "license": "MIT",
+  "author": {
+    "name": "Mushegh Gevorgyan",
+    "email": "mushegh@truecourse.dev"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/truecourse-ai/truecourse"

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 tokens.** Never pass `--llm` without first relaying the token 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 tokens per run. Ask the user one question: **"Run LLM-powered rules this time?"** If the user is unsure, offer to run deterministic-only first (no tokens, 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-hooks/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: truecourse-hooks
+description: Install, configure, or remove the TrueCourse pre-commit hook
+user_invocable: true
+triggers:
+  - install the pre-commit hook
+  - set up truecourse hooks
+  - enable truecourse hook
+  - check hook status
+  - remove pre-commit hook
+  - change what the hook blocks
+  - edit hook config
+---
+
+# TrueCourse Hooks
+
+Install, configure, and manage the pre-commit hook that blocks new violations before they land in git.
+
+## 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.
+- **The hook makes commits slower.** Every commit runs `truecourse analyze --diff`. On large repos that can be tens of seconds per commit. Make sure the user knows before you install.
+- **Baseline required.** The hook needs a `truecourse analyze` to have run at least once in the repo — otherwise every commit is blocked with "run analyze first". If the user hasn't, suggest running `/truecourse-analyze` first (or `npx -y truecourse analyze`).
+- **`hooks.yaml` is the single source of truth.** Installation creates `<repo>/.truecourse/hooks.yaml` with defaults; edit it to change policy. The file is meant to be committed so the whole team shares one hook config.
+
+## Instructions
+
+### 1. Figure out what the user wants
+
+- "install", "set up", "enable" → **Install flow**
+- "status", "is the hook active", "what does it block" → **Status flow**
+- "uninstall", "remove", "disable" → **Uninstall flow**
+- "change what blocks", "make it stricter/looser", "add/remove severities", "enable LLM" → **Configure flow**
+
+### 2. Install flow
+
+1. Tell the user the tradeoff upfront: commits will be slower; this repo needs a `truecourse analyze` baseline; policy lives in `.truecourse/hooks.yaml` which they should commit.
+2. Run:
+   ```
+   npx -y truecourse hooks install
+   ```
+3. Relay the output. Two files get created:
+   - `.git/hooks/pre-commit` (the script git invokes)
+   - `.truecourse/hooks.yaml` (starter policy, blocks `critical` and `high` by default, LLM off)
+4. If the user hasn't run a full analysis in this repo, suggest `/truecourse-analyze` — without it, every commit will be blocked with "no baseline" until they do.
+
+### 3. Status flow
+
+Run:
+```
+npx -y truecourse hooks status
+```
+Relay the output. It reports whether the hook is installed, the config path, the block severities, and whether LLM is on.
+
+### 4. Uninstall flow
+
+Run:
+```
+npx -y truecourse hooks uninstall
+```
+Only removes the git hook script. `hooks.yaml` is preserved (it's team policy, not install state).
+
+### 5. Configure flow
+
+The config lives at `<repo>/.truecourse/hooks.yaml`. Use the Read and Edit tools — do not shell out through `truecourse` for edits.
+
+Schema:
+```yaml
+pre-commit:
+  block-on: [critical, high]   # valid: info, low, medium, high, critical
+  llm: false                   # true = LLM rules on every commit (tokens per commit)
+```
+
+Common edits the user might ask for:
+- **Stricter** ("block medium too"): `block-on: [critical, high, medium]`
+- **Permissive** ("only block criticals"): `block-on: [critical]`
+- **Enable LLM** ("run full checks on commit"): set `llm: true`. Warn the user this spends tokens on every commit — confirm before flipping it.
+
+After editing, run `npx -y truecourse hooks status` so they can verify the parsed values match their intent.
+
+### 6. When the user hits a blocked commit
+
+If a user comes to you saying "my commit got blocked" or similar:
+- The hook's stdout already listed the blocking violations (file, line, title, severity).
+- Offer to run `/truecourse-fix` to apply fix suggestions to those violations.
+- If they want to ship anyway, remind them of `git commit --no-verify` (standard git bypass).

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).