continuous-improvement 2.2.0 → 3.1.0

package/bin/install.mjs

@@ -4,12 +4,15 @@
  * continuous-improvement installer
  *
  * Usage:
- *   npx continuous-improvement install                # auto-detect & install
- *   npx continuous-improvement install --target claude # install to ~/.claude/skills/ + Mulahazah
- *   npx continuous-improvement install --target openclaw # install to ~/.openclaw/skills/
- *   npx continuous-improvement install --target cursor # install to ~/.cursor/skills/
- *   npx continuous-improvement install --target all    # install to all detected targets
- *   npx continuous-improvement install --uninstall     # remove from all targets
+ *   npx continuous-improvement install                          # auto-detect & install (beginner)
+ *   npx continuous-improvement install --target claude          # install to ~/.claude/skills/ + Mulahazah
+ *   npx continuous-improvement install --target openclaw        # install to ~/.openclaw/skills/
+ *   npx continuous-improvement install --target cursor          # install to ~/.cursor/skills/
+ *   npx continuous-improvement install --target all             # install to all detected targets
+ *   npx continuous-improvement install --mode beginner          # hooks only (default)
+ *   npx continuous-improvement install --mode expert            # hooks + MCP server + session hooks
+ *   npx continuous-improvement install --mode mcp               # MCP server only (any editor)
+ *   npx continuous-improvement install --uninstall              # remove from all targets
  */
 
 import {
@@ -20,10 +23,12 @@ import {
   writeFileSync,
   rmSync,
   chmodSync,
+  readdirSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -31,6 +36,11 @@ const SKILL_SOURCE = join(__dirname, "..", "SKILL.md");
 const SKILL_NAME = "continuous-improvement";
 const REPO_ROOT = join(__dirname, "..");
 
+// Parse --mode flag
+const _args = process.argv.slice(2);
+const _modeIdx = _args.indexOf("--mode");
+const INSTALL_MODE = _modeIdx !== -1 && _args[_modeIdx + 1] ? _args[_modeIdx + 1] : "beginner";
+
 const TARGETS = {
   claude: {
     label: "Claude Code",
@@ -70,6 +80,17 @@ function installTo(key) {
   }
 
   try {
+    // MCP-only mode: skip skill file copy, just register MCP server
+    if (INSTALL_MODE === "mcp") {
+      if (key === "claude") {
+        setupMulahazah();
+        console.log(`  ✓ ${target.label} → MCP server only`);
+      } else {
+        console.log(`  ⊘ ${target.label} — MCP mode only applies to Claude Code`);
+      }
+      return true;
+    }
+
     mkdirSync(target.dir, { recursive: true });
     copyFileSync(SKILL_SOURCE, join(target.dir, "SKILL.md"));
     console.log(`  ✓ ${target.label} → ${target.dir}/SKILL.md`);
@@ -103,18 +124,88 @@ function setupMulahazah() {
     console.log(`  ✓ observe.sh → ${observeDest}`);
   }
 
-  // 3. Copy /continuous-improvement command
+  // 3. Copy session.sh for expert mode
+  if (INSTALL_MODE === "expert") {
+    const sessionSrc = join(REPO_ROOT, "hooks", "session.sh");
+    const sessionDest = join(instinctsDir, "session.sh");
+    if (existsSync(sessionSrc)) {
+      copyFileSync(sessionSrc, sessionDest);
+      chmodSync(sessionDest, 0o755);
+      console.log(`  ✓ session.sh → ${sessionDest}`);
+    }
+  }
+
+  // 4. Copy all commands
   const commandsDir = join(home, ".claude", "commands");
   mkdirSync(commandsDir, { recursive: true });
-  const cmdSrc = join(REPO_ROOT, "commands", "continuous-improvement.md");
-  const cmdDest = join(commandsDir, "continuous-improvement.md");
-  if (existsSync(cmdSrc)) {
-    copyFileSync(cmdSrc, cmdDest);
-    console.log(`  ✓ /continuous-improvement command → ${cmdDest}`);
+  const commandFiles = ["continuous-improvement.md", "discipline.md", "dashboard.md"];
+  for (const cmdFile of commandFiles) {
+    const cmdSrc = join(REPO_ROOT, "commands", cmdFile);
+    const cmdDest = join(commandsDir, cmdFile);
+    if (existsSync(cmdSrc)) {
+      copyFileSync(cmdSrc, cmdDest);
+      console.log(`  ✓ /${cmdFile.replace(".md", "")} command → ${cmdDest}`);
+    }
   }
 
-  // 4. Patch ~/.claude/settings.json with hooks
+  // 5. Patch ~/.claude/settings.json with hooks
   patchClaudeSettings(observeDest);
+
+  // 6. Setup MCP server for expert or mcp mode
+  if (INSTALL_MODE === "expert" || INSTALL_MODE === "mcp") {
+    setupMcpServer();
+  }
+}
+
+function setupMcpServer() {
+  const home = homedir();
+  const mcpServerPath = join(REPO_ROOT, "bin", "mcp-server.mjs");
+  const mcpMode = INSTALL_MODE === "mcp" ? "beginner" : "expert";
+
+  // Patch Claude Code settings.json with MCP server config
+  const settingsPath = join(home, ".claude", "settings.json");
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch {
+      console.warn(`  ! Could not parse settings.json — skipping MCP setup`);
+      return;
+    }
+  }
+
+  if (!settings.mcpServers) settings.mcpServers = {};
+
+  const alreadySetup = settings.mcpServers["continuous-improvement"];
+  if (!alreadySetup) {
+    settings.mcpServers["continuous-improvement"] = {
+      command: "node",
+      args: [mcpServerPath, "--mode", mcpMode],
+    };
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`  ✓ MCP server registered (mode: ${mcpMode})`);
+  } else {
+    console.log(`  ✓ MCP server already registered — no change`);
+  }
+
+  // Also write claude_desktop_config.json if it exists
+  const desktopConfig = join(home, ".claude", "claude_desktop_config.json");
+  if (existsSync(desktopConfig)) {
+    try {
+      const config = JSON.parse(readFileSync(desktopConfig, "utf8"));
+      if (!config.mcpServers) config.mcpServers = {};
+      if (!config.mcpServers["continuous-improvement"]) {
+        config.mcpServers["continuous-improvement"] = {
+          command: "node",
+          args: [mcpServerPath, "--mode", mcpMode],
+        };
+        writeFileSync(desktopConfig, JSON.stringify(config, null, 2) + "\n");
+        console.log(`  ✓ Claude Desktop MCP config updated`);
+      }
+    } catch {
+      // skip
+    }
+  }
 }
 
 function patchClaudeSettings(observePath) {
@@ -159,11 +250,40 @@ function patchClaudeSettings(observePath) {
     }
   }
 
+  // Expert mode: add session hooks
+  if (INSTALL_MODE === "expert") {
+    const sessionPath = join(homedir(), ".claude", "instincts", "session.sh");
+    const sessionHook = {
+      matcher: "",
+      hooks: [{ type: "command", command: `bash "${sessionPath}"` }],
+    };
+
+    // Note: SessionStart/SessionEnd hooks may not be supported in all versions.
+    // We register them — they'll be silently ignored if unsupported.
+    for (const hookType of ["SessionStart", "SessionEnd"]) {
+      if (!Array.isArray(settings.hooks[hookType])) {
+        settings.hooks[hookType] = [];
+      }
+      const alreadyPatched = settings.hooks[hookType].some(
+        (h) =>
+          Array.isArray(h.hooks) &&
+          h.hooks.some((hh) => hh.command && hh.command.includes("session.sh"))
+      );
+      if (!alreadyPatched) {
+        settings.hooks[hookType].push(sessionHook);
+        changed = true;
+      }
+    }
+  }
+
   if (changed) {
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    console.log(`  ✓ Patched ~/.claude/settings.json with PreToolUse/PostToolUse hooks`);
+    const hookTypes = INSTALL_MODE === "expert"
+      ? "PreToolUse/PostToolUse/SessionStart/SessionEnd"
+      : "PreToolUse/PostToolUse";
+    console.log(`  ✓ Patched ~/.claude/settings.json with ${hookTypes} hooks`);
   } else {
-    console.log(`  ✓ settings.json already has observe.sh hooks — no change needed`);
+    console.log(`  ✓ settings.json already has hooks — no change needed`);
   }
 }
 
@@ -186,35 +306,41 @@ function uninstallAll() {
     }
   }
 
-  // 2. Remove /continuous-improvement command
-  const cmdFile = join(home, ".claude", "commands", "continuous-improvement.md");
-  if (existsSync(cmdFile)) {
-    try {
-      rmSync(cmdFile);
-      console.log(`  ✓ Removed /continuous-improvement command`);
-    } catch (err) {
-      console.error(`  ✗ Command file: ${err.message}`);
+  // 2. Remove all commands
+  for (const cmdName of ["continuous-improvement.md", "discipline.md", "dashboard.md"]) {
+    const cmdFile = join(home, ".claude", "commands", cmdName);
+    if (existsSync(cmdFile)) {
+      try {
+        rmSync(cmdFile);
+        console.log(`  ✓ Removed /${cmdName.replace(".md", "")} command`);
+      } catch (err) {
+        console.error(`  ✗ ${cmdName}: ${err.message}`);
+      }
     }
   }
 
-  // 3. Remove observe.sh from instincts dir
-  const observeFile = join(home, ".claude", "instincts", "observe.sh");
-  if (existsSync(observeFile)) {
-    try {
-      rmSync(observeFile);
-      console.log(`  ✓ Removed observe.sh`);
-    } catch (err) {
-      console.error(`  ✗ observe.sh: ${err.message}`);
+  // 3. Remove observe.sh and session.sh from instincts dir
+  for (const hookFile of ["observe.sh", "session.sh"]) {
+    const filePath = join(home, ".claude", "instincts", hookFile);
+    if (existsSync(filePath)) {
+      try {
+        rmSync(filePath);
+        console.log(`  ✓ Removed ${hookFile}`);
+      } catch (err) {
+        console.error(`  ✗ ${hookFile}: ${err.message}`);
+      }
     }
   }
 
-  // 4. Remove hooks from settings.json
+  // 4. Remove hooks and MCP server from settings.json
   const settingsPath = join(home, ".claude", "settings.json");
   if (existsSync(settingsPath)) {
     try {
       const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
       let changed = false;
-      for (const hookType of ["PreToolUse", "PostToolUse"]) {
+
+      // Remove all hook types
+      for (const hookType of ["PreToolUse", "PostToolUse", "SessionStart", "SessionEnd"]) {
         if (Array.isArray(settings.hooks?.[hookType])) {
           const before = settings.hooks[hookType].length;
           settings.hooks[hookType] = settings.hooks[hookType].filter(
@@ -222,22 +348,44 @@ function uninstallAll() {
               !(
                 Array.isArray(h.hooks) &&
                 h.hooks.some(
-                  (hh) => hh.command && hh.command.includes("observe.sh")
+                  (hh) => hh.command && (hh.command.includes("observe.sh") || hh.command.includes("session.sh"))
                 )
               )
           );
           if (settings.hooks[hookType].length < before) changed = true;
         }
       }
+
+      // Remove MCP server
+      if (settings.mcpServers?.["continuous-improvement"]) {
+        delete settings.mcpServers["continuous-improvement"];
+        changed = true;
+      }
+
       if (changed) {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-        console.log(`  ✓ Removed hooks from settings.json`);
+        console.log(`  ✓ Removed hooks and MCP server from settings.json`);
       }
     } catch {
       console.warn(`  ! Could not clean settings.json — remove hooks manually`);
     }
   }
 
+  // 5. Clean claude_desktop_config.json MCP entry
+  const desktopConfig = join(home, ".claude", "claude_desktop_config.json");
+  if (existsSync(desktopConfig)) {
+    try {
+      const config = JSON.parse(readFileSync(desktopConfig, "utf8"));
+      if (config.mcpServers?.["continuous-improvement"]) {
+        delete config.mcpServers["continuous-improvement"];
+        writeFileSync(desktopConfig, JSON.stringify(config, null, 2) + "\n");
+        console.log(`  ✓ Removed MCP server from Claude Desktop config`);
+      }
+    } catch {
+      // skip
+    }
+  }
+
   if (removed === 0) {
     console.log("  No skill installations found.");
   }
@@ -253,13 +401,30 @@ Usage: npx continuous-improvement install [options]
 
 Options:
   --target <name>   Install to specific target (claude, openclaw, cursor, codex, all)
+  --mode <mode>     Installation mode:
+                      beginner  — hooks only, no MCP server (default)
+                      expert    — hooks + MCP server + session hooks + all tools
+                      mcp       — MCP server only (works with any MCP client)
   --uninstall       Remove from all targets
   --help            Show this help
 
+Modes explained:
+  BEGINNER (default)   Just works. Hooks capture silently, instincts grow over time.
+                       3 tools via /continuous-improvement command.
+
+  EXPERT               Everything in beginner + MCP server with 8 tools:
+                       import/export, manual instinct creation, observation viewer,
+                       confidence tuning. Plus session start/end hooks.
+
+  MCP                  MCP server only — for editors that support MCP but not
+                       Claude Code hooks (Cursor, Zed, Windsurf, VS Code).
+
 Examples:
-  npx continuous-improvement install              # auto-detect & install
-  npx continuous-improvement install --target all  # install everywhere
-  npx continuous-improvement install --uninstall   # remove all
+  npx continuous-improvement install                        # beginner (default)
+  npx continuous-improvement install --mode expert          # full power
+  npx continuous-improvement install --mode mcp             # MCP server only
+  npx continuous-improvement install --target all            # install everywhere
+  npx continuous-improvement install --uninstall             # remove all
 `);
 }
 
@@ -284,7 +449,7 @@ if (args.includes("--uninstall")) {
 }
 
 console.log(`
-continuous-improvement v2.1
+continuous-improvement v3.1 (mode: ${INSTALL_MODE})
 Research → Plan → Execute → Verify → Reflect → Learn → Iterate
 `);
 
@@ -321,11 +486,73 @@ for (const t of targets) {
 
 const hasClaude = targets.includes("claude");
 
+const modeInfo = {
+  beginner: "Hooks are capturing silently. System auto-levels as you use it.",
+  expert: "Full plugin active: hooks + MCP server + session hooks. 8 tools available.",
+  mcp: "MCP server registered. Connect from any MCP-compatible editor.",
+};
+
+// Handle --pack flag
+const packIdx = _args.indexOf("--pack");
+if (packIdx !== -1 && _args[packIdx + 1]) {
+  const packName = _args[packIdx + 1];
+  const packPath = join(REPO_ROOT, "instinct-packs", `${packName}.json`);
+  if (existsSync(packPath)) {
+    const project = getProjectHashSync();
+    const targetDir = join(homedir(), ".claude", "instincts", project.hash);
+    mkdirSync(targetDir, { recursive: true });
+
+    const instincts = JSON.parse(readFileSync(packPath, "utf8"));
+    let loaded = 0;
+    for (const inst of instincts) {
+      const instPath = join(targetDir, `${inst.id}.yaml`);
+      if (!existsSync(instPath)) {
+        const yaml = [
+          `id: ${inst.id}`,
+          `trigger: "${inst.trigger}"`,
+          `confidence: ${inst.confidence}`,
+          `domain: ${inst.domain || "workflow"}`,
+          `source: pack-${packName}`,
+          `scope: project`,
+          `project_id: ${project.hash}`,
+          `created: "${new Date().toISOString().split("T")[0]}"`,
+          `last_seen: "${new Date().toISOString().split("T")[0]}"`,
+          `observation_count: 0`,
+          "---",
+          inst.body,
+        ].join("\n");
+        writeFileSync(instPath, yaml + "\n");
+        loaded++;
+      }
+    }
+    console.log(`  ✓ Loaded ${loaded}/${instincts.length} instincts from ${packName} pack`);
+  } else {
+    const available = readdirSync(join(REPO_ROOT, "instinct-packs"))
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => f.replace(".json", ""));
+    console.error(`  ✗ Unknown pack: ${packName}. Available: ${available.join(", ")}`);
+  }
+}
+
+function getProjectHashSync() {
+  try {
+    const root = execSync("git rev-parse --show-toplevel 2>/dev/null", { encoding: "utf8" }).trim();
+    const hash = execSync(`printf '%s' "${root}" | sha256sum | cut -c1-12`, { encoding: "utf8", shell: "/bin/bash" }).trim();
+    return { root, hash };
+  } catch {
+    return { root: "global", hash: "global" };
+  }
+}
+
 console.log(`
 ${installed > 0 ? "Done." : "Failed."} Installed to ${installed}/${targets.length} target(s).
-${hasClaude ? "\nHooks are capturing. System auto-levels as you use it." : ""}
+${hasClaude ? `\n${modeInfo[INSTALL_MODE] || modeInfo.beginner}` : ""}
 Next steps:
   1. Start a new Claude Code session
   2. Say: "Use the continuous-improvement framework to [your task]"
   3. After your first task, run: /continuous-improvement
+  4. Try: /discipline for quick reference, /dashboard for instinct health
+${INSTALL_MODE === "expert" ? "\nMCP tools available: ci_status, ci_instincts, ci_reflect, ci_reinforce,\n  ci_create_instinct, ci_observations, ci_export, ci_import, ci_dashboard, ci_load_pack" : ""}
+${INSTALL_MODE === "mcp" ? "\nMCP tools available: ci_status, ci_instincts, ci_reflect" : ""}
+Available instinct packs: npx continuous-improvement install --pack react|python|go
 `);

package/bin/lint-transcript.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Transcript Linter
+ *
+ * Analyzes AI agent transcripts/observations for compliance with
+ * the 7 Laws of AI Agent Discipline.
+ *
+ * Usage:
+ *   node bin/lint-transcript.mjs <file.jsonl>         # Lint a transcript file
+ *   cat observations.jsonl | node bin/lint-transcript.mjs --stdin  # Pipe input
+ *   node bin/lint-transcript.mjs --help
+ *
+ * Exit codes:
+ *   0 — no violations (or --strict not set)
+ *   1 — violations found (with --strict)
+ */
+
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+
+const LAWS = {
+  1: { name: "Research Before Executing", patterns: [] },
+  2: { name: "Plan Is Sacred", patterns: [] },
+  3: { name: "One Thing at a Time", patterns: [] },
+  4: { name: "Verify Before Reporting", patterns: [] },
+  5: { name: "Reflect After Sessions", patterns: [] },
+  6: { name: "Iterate One Change", patterns: [] },
+  7: { name: "Learn From Every Session", patterns: [] },
+};
+
+function analyzeTranscript(events) {
+  const violations = [];
+  const stats = {
+    totalEvents: events.length,
+    toolCalls: 0,
+    researchTools: 0, // Grep, Glob, Read
+    writeTools: 0, // Write, Edit, Bash
+    verifyTools: 0, // Bash (test/build commands)
+    sessions: new Set(),
+  };
+
+  // Classify events
+  for (const event of events) {
+    stats.toolCalls++;
+    if (event.session_id) stats.sessions.add(event.session_id);
+
+    const tool = event.tool || event.tool_name || "";
+    const input = event.tool_input || event.input || {};
+    const command = input.command || "";
+
+    if (["Grep", "Glob", "Read"].includes(tool)) {
+      stats.researchTools++;
+    }
+    if (["Write", "Edit"].includes(tool)) {
+      stats.writeTools++;
+    }
+    if (tool === "Bash" && /\b(test|build|npm run|jest|pytest|go test|cargo test)\b/.test(command)) {
+      stats.verifyTools++;
+    }
+  }
+
+  // Law 1: Research Before Executing
+  // Check if writes happen without prior reads/greps
+  let lastResearchIdx = -1;
+  for (let i = 0; i < events.length; i++) {
+    const tool = events[i].tool || events[i].tool_name || "";
+    if (["Grep", "Glob", "Read"].includes(tool)) {
+      lastResearchIdx = i;
+    }
+    if (["Write", "Edit"].includes(tool) && lastResearchIdx === -1) {
+      violations.push({
+        law: 1,
+        severity: "high",
+        message: `Write/Edit at event ${i} without any prior research (Grep/Glob/Read)`,
+        event: i,
+      });
+      break; // Only report first occurrence
+    }
+  }
+
+  // Law 1 ratio check
+  if (stats.writeTools > 0 && stats.researchTools === 0) {
+    violations.push({
+      law: 1,
+      severity: "high",
+      message: `${stats.writeTools} writes with 0 research operations. Agent likely skipped research.`,
+    });
+  } else if (stats.writeTools > stats.researchTools * 3) {
+    violations.push({
+      law: 1,
+      severity: "medium",
+      message: `Write-to-research ratio is ${stats.writeTools}:${stats.researchTools}. Consider more research.`,
+    });
+  }
+
+  // Law 3: One Thing at a Time
+  // Detect rapid context switching (different files edited in quick succession without verification)
+  let consecutiveEdits = 0;
+  const editedFiles = new Set();
+  for (const event of events) {
+    const tool = event.tool || event.tool_name || "";
+    const input = event.tool_input || event.input || {};
+
+    if (["Write", "Edit"].includes(tool)) {
+      consecutiveEdits++;
+      if (input.file_path) editedFiles.add(input.file_path);
+    } else if (tool === "Bash") {
+      consecutiveEdits = 0; // Reset on verification
+    }
+
+    if (consecutiveEdits > 5) {
+      violations.push({
+        law: 3,
+        severity: "medium",
+        message: `${consecutiveEdits} consecutive edits without verification. Editing multiple files at once.`,
+      });
+      consecutiveEdits = 0;
+    }
+  }
+
+  // Law 4: Verify Before Reporting
+  if (stats.writeTools > 0 && stats.verifyTools === 0) {
+    violations.push({
+      law: 4,
+      severity: "high",
+      message: `${stats.writeTools} code changes with 0 verification commands (test/build). Agent may have declared done without verifying.`,
+    });
+  }
+
+  // Law 6: Iterate One Change
+  if (editedFiles.size > 8) {
+    violations.push({
+      law: 6,
+      severity: "medium",
+      message: `${editedFiles.size} different files modified. Consider smaller, focused iterations.`,
+    });
+  }
+
+  // Calculate discipline score
+  const maxViolations = 7; // One per law
+  const violationWeight = violations.reduce((sum, v) => {
+    return sum + (v.severity === "high" ? 2 : 1);
+  }, 0);
+  const score = Math.max(0, Math.round(100 - (violationWeight / maxViolations) * 100));
+
+  return { violations, stats, score };
+}
+
+function formatReport(result) {
+  const { violations, stats, score } = result;
+  const lines = [];
+
+  lines.push("## Agent Discipline Report");
+  lines.push("");
+  lines.push(`**Score:** ${score}/100`);
+  lines.push(`**Events analyzed:** ${stats.totalEvents}`);
+  lines.push(`**Tool calls:** ${stats.toolCalls}`);
+  lines.push(`**Research ops:** ${stats.researchTools} | **Write ops:** ${stats.writeTools} | **Verify ops:** ${stats.verifyTools}`);
+  lines.push("");
+
+  if (violations.length === 0) {
+    lines.push("No law violations detected. Good discipline!");
+  } else {
+    lines.push(`### Violations (${violations.length})`);
+    lines.push("");
+    for (const v of violations) {
+      const severity = v.severity === "high" ? "HIGH" : "MEDIUM";
+      lines.push(`- **[${severity}] Law ${v.law}: ${LAWS[v.law].name}**`);
+      lines.push(`  ${v.message}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("---");
+  lines.push("*Generated by [continuous-improvement](https://github.com/naimkatiman/continuous-improvement) transcript linter*");
+
+  return lines.join("\n");
+}
+
+// --- Main ---
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+Agent Transcript Linter — The 7 Laws of AI Agent Discipline
+
+Usage:
+  node bin/lint-transcript.mjs <file.jsonl>         Lint a transcript file
+  cat obs.jsonl | node bin/lint-transcript.mjs --stdin  Pipe input
+  node bin/lint-transcript.mjs --help               Show help
+
+Options:
+  --stdin     Read from stdin
+  --strict    Exit 1 if violations found
+  --json      Output as JSON instead of markdown
+`);
+  process.exit(0);
+}
+
+const isStrict = args.includes("--strict");
+const isJson = args.includes("--json");
+const isStdin = args.includes("--stdin");
+
+async function main() {
+  let lines;
+
+  if (isStdin) {
+    const rl = createInterface({ input: process.stdin, terminal: false });
+    lines = [];
+    for await (const line of rl) {
+      if (line.trim()) lines.push(line.trim());
+    }
+  } else {
+    const filePath = args.find((a) => !a.startsWith("--"));
+    if (!filePath) {
+      console.error("Error: provide a file path or use --stdin");
+      process.exit(1);
+    }
+    const content = readFileSync(filePath, "utf8");
+    lines = content.split("\n").filter((l) => l.trim());
+  }
+
+  const events = [];
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // skip non-JSON lines
+    }
+  }
+
+  if (events.length === 0) {
+    console.log("No events found to analyze.");
+    process.exit(0);
+  }
+
+  const result = analyzeTranscript(events);
+
+  if (isJson) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(formatReport(result));
+  }
+
+  // GitHub Actions output
+  if (process.env.GITHUB_OUTPUT) {
+    const outputLines = [
+      `violations=${result.violations.length}`,
+      `score=${result.score}`,
+    ];
+    const { appendFileSync } = await import("node:fs");
+    for (const line of outputLines) {
+      appendFileSync(process.env.GITHUB_OUTPUT, line + "\n");
+    }
+  }
+
+  if (isStrict && result.violations.length > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});