@eeshans/howiprompt 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eeshan Srivastava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+> **Disclaimer:** This is an independent personal project, **not affiliated with, endorsed by, or connected to Anthropic or Claude** in any way. This is a non-commercial, open-source tool created for personal use and educational purposes only.
+
+<div align="center">
+
+# How I Prompt
+
+**Local-first analytics for your AI coding conversations — prompts, personas, trends, and a personal wrapped view.**
+
+[![npm](https://img.shields.io/npm/v/@eeshans/howiprompt)](https://www.npmjs.com/package/@eeshans/howiprompt)
+[![license](https://img.shields.io/github/license/eeshansrivastava89/howiprompt)](LICENSE)
+[![node](https://img.shields.io/node/v/@eeshans/howiprompt)](package.json)
+[![platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-blue)]()
+[![demo](https://img.shields.io/badge/demo-live-cb9f6a)](https://howiprompt.eeshans.com)
+
+[Live Dashboard](https://howiprompt.eeshans.com) • [Live Wrapped](https://howiprompt.eeshans.com/wrapped) • [Source](https://github.com/eeshansrivastava89/howiprompt)
+
+```bash
+npx @eeshans/howiprompt
+```
+
+> **Requirements:** [Node.js 18+](https://nodejs.org/). Works with Claude Code, Codex, Copilot Chat, Cursor, and LM Studio logs. The local package ships with analytics disabled.
+
+</div>
+
+<br>
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/12c6fc86-0d08-45c1-b94b-39c3bfbff93d" alt="How I Prompt dashboard" width="900">
+</p>
+
+## Highlights
+
+| | |
+|---|---|
+| **Local-first pipeline** | Sync, parsing, embeddings, classifier scoring, and metrics run on your machine |
+| **Multi-source support** | Claude Code, Codex, Copilot Chat, Cursor, and LM Studio |
+| **Two ways to explore** | Standard dashboard plus a scroll-through wrapped experience |
+| **Metrics that feel personal** | Vibe Coder Index, Politeness, activity trends, heatmaps, and personas |
+| **Private by default** | Raw logs stay local and the npm package ships with analytics disabled |
+| **Fast repeat refreshes** | Incremental rebuilds reuse the local DB, caches, and exclusions |
+
+## What it does
+
+How I Prompt syncs local AI conversation logs, computes prompting metrics on-device, and opens a browser dashboard with both an overview page and a scroll-through wrapped experience.
+
+That starts a local server and opens the dashboard. On first run, a setup wizard detects supported backends, lets you confirm sources, and then runs the pipeline.
+
+### Options
+
+```bash
+npx @eeshans/howiprompt --no-open     # don't auto-open browser
+npx @eeshans/howiprompt --port 4000   # custom port
+npx @eeshans/howiprompt --help        # usage info
+```
+
+### What Happens
+
+1. Detects supported local backends and writes setup to `~/.howiprompt/config.json`
+2. Copies raw conversation data into `~/.howiprompt/raw/`
+3. Parses and stores messages in a local SQLite database at `~/.howiprompt/data.db`
+4. Runs embeddings and classifier scoring for dashboard metrics
+5. Writes `~/.howiprompt/metrics.json` and serves the dashboard at `localhost`
+
+Subsequent refreshes are incremental and reuse the local database, caches, and configured exclusions.
+
+---
+
+## What You Get
+
+| Dashboard | Full Experience |
+|-----------|-----------------|
+| One-page overview of your stats | Scroll-through "Wrapped" presentation |
+| [howiprompt.eeshans.com](https://howiprompt.eeshans.com) | [howiprompt.eeshans.com/wrapped](https://howiprompt.eeshans.com/wrapped) |
+
+**Metrics include:** total prompts, conversation depth, activity heatmap, model usage, Vibe Coder Index, Politeness, persona classification (2×2: Detail Level × Communication Style), and trends.
+
+---
+
+## Data Sources
+
+| Source | Location |
+|--------|----------|
+| **Claude Code** | `~/.claude/projects/*.jsonl` |
+| **Codex** | `~/.codex/history.jsonl` |
+| **Copilot Chat** | `~/Library/Application Support/Code/User/workspaceStorage` |
+| **Cursor** | `~/Library/Application Support/Cursor/User/workspaceStorage` |
+| **LM Studio** | `~/.lmstudio/conversations` |
+
+All supported sources are auto-synced into `~/.howiprompt/raw/` and reused across refreshes.
+
+### Backend Status
+
+- Supported today: `Claude Code`, `Codex`, `Copilot Chat`, `Cursor`, `LM Studio`
+
+---
+
+## Privacy
+
+- **Local by default** — Sync, parsing, embeddings, classifier scoring, and metrics run on your machine
+- **Persistent storage** — Raw copies, local DB, config, and metrics live under `~/.howiprompt/`
+- **No prompt text leaves your machine** — The app does not upload raw logs or prompt content
+- **No analytics in the local app** — The `npx @eeshans/howiprompt` package ships with analytics disabled. PostHog is only enabled on the hosted website
+- **Ancillary network requests** — The dashboard loads ApexCharts from a CDN. The CLI checks npm for version updates. These do not transmit prompt data
+
+---
+
+## The 4 Personas
+
+Your persona is derived from two independent axes: **Detail Level** (brief → detailed) and **Communication Style** (directive → collaborative). These form a 2×2 grid validated on 21k prompts.
+
+- **The Commander**: Brief + Directive — short, decisive instructions
+- **The Partner**: Brief + Collaborative — quick exchanges, conversational flow
+- **The Architect**: Detailed + Directive — specs, constraints, numbered requirements
+- **The Explorer**: Detailed + Collaborative — context-rich, question-driven investigation
+
+---
+
+## Development
+
+```bash
+# Install deps
+npm install
+
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Build frontend
+cd frontend && npm run build
+
+# Build for distribution
+npm run build:cli
+
+# Privacy gate (run before publish)
+npm run check:privacy
+```
+
+### Requirements
+
+- Node.js 18+
+
+---
+
+## License
+
+MIT License — Not affiliated with Anthropic.

package/bin/bootstrap-db.mjs

@@ -0,0 +1,166 @@
+/**
+ * Idempotent database schema bootstrap for howiprompt.
+ * Uses @libsql/client — safe to run every launch.
+ */
+
+import { createClient } from "@libsql/client";
+
+const SCHEMA_SQL = [
+  `CREATE TABLE IF NOT EXISTS messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    hash TEXT UNIQUE NOT NULL,
+    timestamp TEXT NOT NULL,
+    platform TEXT NOT NULL,
+    role TEXT NOT NULL,
+    content TEXT NOT NULL,
+    conversation_id TEXT NOT NULL,
+    word_count INTEGER NOT NULL,
+    model_id TEXT,
+    model_provider TEXT,
+    local_hour INTEGER NOT NULL,
+    local_weekday INTEGER NOT NULL,
+    local_date TEXT NOT NULL,
+    source_file TEXT,
+    synced_at TEXT NOT NULL,
+    embedding BLOB
+  )`,
+
+  `CREATE TABLE IF NOT EXISTS nlp_enrichments (
+    message_id INTEGER PRIMARY KEY REFERENCES messages(id),
+    intent TEXT,
+    intent_confidence REAL,
+    complexity_score REAL,
+    complexity_confidence REAL,
+    iteration_score REAL,
+    iteration_confidence REAL
+  )`,
+
+  `CREATE TABLE IF NOT EXISTS sync_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source TEXT NOT NULL,
+    last_file TEXT,
+    last_timestamp TEXT,
+    message_count INTEGER,
+    synced_at TEXT NOT NULL
+  )`,
+
+  `CREATE INDEX IF NOT EXISTS idx_messages_platform_role ON messages(platform, role)`,
+  `CREATE INDEX IF NOT EXISTS idx_messages_conversation ON messages(conversation_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_messages_timestamp ON messages(timestamp)`,
+  `CREATE INDEX IF NOT EXISTS idx_messages_hash ON messages(hash)`,
+  `CREATE INDEX IF NOT EXISTS idx_messages_local_date ON messages(local_date)`,
+];
+
+/**
+ * Additive migrations — safe to re-run (catch duplicate column errors).
+ */
+const MIGRATIONS = [
+  // Phase 2: semantic classifiers
+  `ALTER TABLE nlp_enrichments ADD COLUMN hitl_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN hitl_confidence REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN vibe_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN vibe_confidence REAL`,
+  // Phase 6: radar axes
+  `ALTER TABLE nlp_enrichments ADD COLUMN precision_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN precision_confidence REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN curiosity_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN curiosity_confidence REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN tenacity_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN tenacity_confidence REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN trust_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN trust_confidence REAL`,
+  // Politeness embedding classifier
+  `ALTER TABLE nlp_enrichments ADD COLUMN politeness_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN politeness_confidence REAL`,
+  // Skill invocation flagging
+  `ALTER TABLE messages ADD COLUMN is_skill_invocation INTEGER DEFAULT 0`,
+  `ALTER TABLE messages ADD COLUMN matched_skill_id INTEGER REFERENCES skills(id)`,
+  // Skill source type (discovered from disk vs config stored in DB)
+  `ALTER TABLE skills ADD COLUMN source TEXT DEFAULT 'discovered'`,
+  // Exclusion rule reference on messages
+  `ALTER TABLE messages ADD COLUMN matched_rule_id INTEGER REFERENCES exclusion_rules(id)`,
+  // Rename flag: is_skill_invocation -> is_excluded (broader meaning)
+  `ALTER TABLE messages ADD COLUMN is_excluded INTEGER DEFAULT 0`,
+  // 2×2 style scores (replaces old persona radar axes)
+  `ALTER TABLE nlp_enrichments ADD COLUMN detail_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN style_score REAL`,
+  `ALTER TABLE nlp_enrichments ADD COLUMN quadrant TEXT`,
+];
+
+/**
+ * New tables added in later phases.
+ */
+const NEW_TABLES = [
+  `CREATE TABLE IF NOT EXISTS reference_embeddings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    classifier TEXT NOT NULL,
+    cluster TEXT NOT NULL,
+    prompt TEXT NOT NULL,
+    embedding F32_BLOB(384) NOT NULL
+  )`,
+
+  `CREATE TABLE IF NOT EXISTS skills (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    platform TEXT NOT NULL,
+    skill_name TEXT NOT NULL,
+    skill_path TEXT NOT NULL,
+    invocation_pattern TEXT,
+    template_content TEXT,
+    content_hash TEXT,
+    discovered_at TEXT NOT NULL,
+    UNIQUE(platform, skill_name)
+  )`,
+
+  `CREATE TABLE IF NOT EXISTS exclusion_rules (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    platform TEXT NOT NULL DEFAULT '*',
+    rule_type TEXT NOT NULL,
+    pattern TEXT NOT NULL,
+    match_mode TEXT NOT NULL DEFAULT 'starts_with',
+    description TEXT,
+    source TEXT NOT NULL DEFAULT 'system',
+    template_content TEXT,
+    is_active INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    UNIQUE(platform, rule_type, pattern)
+  )`,
+];
+
+/**
+ * Bootstrap the database schema at the given path.
+ * @param {string} dbPath — absolute path to the SQLite file
+ */
+export async function bootstrapDb(dbPath) {
+  const client = createClient({ url: `file:${dbPath}` });
+
+  for (const sql of SCHEMA_SQL) {
+    await client.execute(sql);
+  }
+
+  // New tables
+  for (const sql of NEW_TABLES) {
+    await client.execute(sql);
+  }
+
+  // Additive migrations (ignore duplicate column errors)
+  for (const sql of MIGRATIONS) {
+    try {
+      await client.execute(sql);
+    } catch (err) {
+      if (!String(err).includes("duplicate column")) throw err;
+    }
+  }
+
+  // Migrate is_skill_invocation -> is_excluded (one-time)
+  await client.execute("UPDATE messages SET is_excluded = is_skill_invocation WHERE is_excluded = 0 AND is_skill_invocation = 1");
+
+  // Legacy cleanup: remove rows from obsolete 'agent' platform.
+  // Skill invocation flagging is now handled by src/pipeline/skills.ts
+  // at runtime — messages are kept but flagged (is_skill_invocation = 1).
+  await client.execute("DELETE FROM nlp_enrichments WHERE message_id IN (SELECT id FROM messages WHERE platform = 'agent')");
+  await client.execute("DELETE FROM messages WHERE platform = 'agent'");
+  await client.execute("DELETE FROM nlp_enrichments WHERE message_id IN (SELECT id FROM messages WHERE conversation_id LIKE 'agent-%')");
+  await client.execute("DELETE FROM messages WHERE conversation_id LIKE 'agent-%'");
+
+  client.close();
+}

package/bin/cli-helpers.mjs

@@ -0,0 +1,86 @@
+/**
+ * Pure helpers for CLI — testable without side effects.
+ */
+
+import net from "node:net";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { exec } from "node:child_process";
+
+/**
+ * Resolve the data directory: ~/.howiprompt
+ */
+export function resolveDataDir() {
+  return path.join(os.homedir(), ".howiprompt");
+}
+
+/**
+ * Find a free TCP port. Tries preferred first, falls back to OS-assigned.
+ */
+export function findFreePort(preferred) {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.listen(preferred ?? 0, "127.0.0.1", () => {
+      const addr = srv.address();
+      if (addr && typeof addr === "object") {
+        const port = addr.port;
+        srv.close(() => resolve(port));
+      } else {
+        reject(new Error("Could not determine port"));
+      }
+    });
+    srv.on("error", (err) => {
+      if (preferred && err.code === "EADDRINUSE") {
+        findFreePort(null).then(resolve, reject);
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+/**
+ * Poll a URL until it responds with status < 500 or timeout.
+ */
+export function waitForServer(url, timeoutMs = 15_000) {
+  const start = Date.now();
+  return new Promise((resolve, reject) => {
+    const check = () => {
+      if (Date.now() - start > timeoutMs) {
+        reject(new Error(`Server did not start within ${timeoutMs}ms`));
+        return;
+      }
+      const req = http.get(url, (res) => {
+        if (res.statusCode && res.statusCode < 500) {
+          resolve();
+        } else {
+          setTimeout(check, 200);
+        }
+      });
+      req.on("error", () => setTimeout(check, 200));
+      req.end();
+    };
+    check();
+  });
+}
+
+/**
+ * Parse CLI arguments.
+ */
+export function parseArgs(argv) {
+  const help = argv.includes("--help") || argv.includes("-h");
+  const version = argv.includes("--version") || argv.includes("-v");
+  const noOpen = argv.includes("--no-open");
+  const portIdx = argv.indexOf("--port");
+  const port = portIdx !== -1 ? Number(argv[portIdx + 1]) : null;
+  return { port, noOpen, help, version };
+}
+
+/**
+ * Open a URL in the default browser. Cross-platform.
+ */
+export async function openBrowser(url) {
+  const { default: open } = await import("open");
+  return open(url);
+}

package/bin/cli.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for How I Prompt.
+ * Usage: npx @eeshans/howiprompt [--port <n>] [--no-open] [--help] [--version]
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { bootstrapDb } from "./bootstrap-db.mjs";
+import { resolveDataDir, findFreePort, parseArgs, openBrowser, waitForServer } from "./cli-helpers.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = path.join(__dirname, "..", "package.json");
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+
+// ── Color helpers ──────────────────────────────────────
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+// ── Parse args ─────────────────────────────────────────
+const parsed = parseArgs(process.argv.slice(2));
+
+if (parsed.help) {
+  console.log(`
+${bold("howiprompt")} v${pkg.version}
+Local-first analytics dashboard for Claude Code + Codex prompting patterns.
+
+Usage: howiprompt [options]
+
+Options:
+  --port <n>   Use a specific port (default: auto)
+  --no-open    Don't open the browser automatically
+  --help       Show this help message
+  --version    Show version number
+`);
+  process.exit(0);
+}
+
+if (parsed.version) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+// ── Check Node version ─────────────────────────────────
+const [major] = process.versions.node.split(".").map(Number);
+if (major < 18) {
+  console.error(red(`Node >= 18.0.0 required (found ${process.versions.node})`));
+  process.exit(1);
+}
+
+// ── Resolve data directory ─────────────────────────────
+const dataDir = resolveDataDir();
+fs.mkdirSync(dataDir, { recursive: true });
+fs.mkdirSync(path.join(dataDir, "raw", "claude_code"), { recursive: true });
+fs.mkdirSync(path.join(dataDir, "raw", "codex"), { recursive: true });
+fs.mkdirSync(path.join(dataDir, "raw", "copilot_chat"), { recursive: true });
+fs.mkdirSync(path.join(dataDir, "raw", "cursor"), { recursive: true });
+fs.mkdirSync(path.join(dataDir, "raw", "lmstudio"), { recursive: true });
+
+console.log(`\n${bold("howiprompt")} v${pkg.version}\n`);
+
+// ── Bootstrap database ─────────────────────────────────
+const dbPath = path.join(dataDir, "data.db");
+process.stdout.write(`  Checking environment...        ${dim("Node " + process.versions.node)} `);
+console.log(green("ok"));
+
+process.stdout.write("  Initializing database...       ");
+await bootstrapDb(dbPath);
+console.log(green("done"));
+
+// ── Ensure wizard shows when there's no data ──────────
+const metricsPath = path.join(dataDir, "metrics.json");
+if (!fs.existsSync(metricsPath)) {
+  const configPath = path.join(dataDir, "config.json");
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    if (cfg.hasCompletedSetup) {
+      cfg.hasCompletedSetup = false;
+      fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+    }
+  } catch { /* no config yet — wizard will show by default */ }
+}
+
+// ── Auto-build if needed ──────────────────────────────
+const projectRoot = path.join(__dirname, "..");
+
+process.stdout.write("  Building backend...            ");
+try {
+  execSync("npm run build", { cwd: projectRoot, stdio: "pipe" });
+  console.log(green("done"));
+} catch (e) {
+  console.log(red("failed"));
+  console.error(e.stderr?.toString() || e.message);
+  process.exit(1);
+}
+
+process.stdout.write("  Building frontend...           ");
+try {
+  execSync("npm run build", { cwd: path.join(projectRoot, "frontend"), stdio: "pipe" });
+  console.log(green("done"));
+} catch (e) {
+  console.log(red("failed"));
+  console.error(e.stderr?.toString() || e.message);
+  process.exit(1);
+}
+
+// ── Start server ───────────────────────────────────────
+const port = await findFreePort(parsed.port);
+
+process.stdout.write("  Starting server...             ");
+
+try {
+  const { startServer } = await import("../dist/server.js");
+  const server = await startServer({ port, dataDir, dbPath });
+  const serverUrl = `http://localhost:${port}`;
+  console.log(green(serverUrl));
+
+  console.log(`\n  Dashboard ready. Press ${bold("Ctrl+C")} to stop.\n`);
+
+  // Non-blocking version check
+  let versionCheckTimeout = null;
+  (async () => {
+    try {
+      const controller = new AbortController();
+      versionCheckTimeout = setTimeout(() => controller.abort(), 3000);
+      versionCheckTimeout.unref?.();
+      const res = await fetch("https://registry.npmjs.org/howiprompt/latest", {
+        signal: controller.signal,
+      });
+      clearTimeout(versionCheckTimeout);
+      versionCheckTimeout = null;
+      if (!res.ok) return;
+      const data = await res.json();
+      const latest = data.version;
+      if (latest && latest !== pkg.version) {
+        const l = latest.split(".").map(Number);
+        const c = pkg.version.split(".").map(Number);
+        const newer =
+          l[0] > c[0] ||
+          (l[0] === c[0] && l[1] > c[1]) ||
+          (l[0] === c[0] && l[1] === c[1] && l[2] > c[2]);
+        if (newer) {
+          console.log(`  ${yellow("Update available:")} ${pkg.version} → ${green(latest)}`);
+          console.log(`  Run: ${bold("npx @eeshans/howiprompt@latest")}\n`);
+        }
+      }
+    } catch {
+      // Silent on failure
+    } finally {
+      if (versionCheckTimeout) {
+        clearTimeout(versionCheckTimeout);
+        versionCheckTimeout = null;
+      }
+    }
+  })();
+
+  if (!parsed.noOpen) {
+    openBrowser(serverUrl);
+  }
+
+  let shuttingDown = false;
+  function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log("\n  Shutting down...");
+
+    if (versionCheckTimeout) {
+      clearTimeout(versionCheckTimeout);
+      versionCheckTimeout = null;
+    }
+
+    const hardExitTimer = setTimeout(() => {
+      process.exit(0);
+    }, 2000);
+    hardExitTimer.unref?.();
+
+    server.close((closeErr) => {
+      clearTimeout(hardExitTimer);
+      if (closeErr) {
+        console.log(red(`error during shutdown: ${closeErr.message}`));
+        process.exit(1);
+        return;
+      }
+      process.exitCode = 0;
+    });
+  }
+
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+} catch (err) {
+  if (err.code === "ERR_MODULE_NOT_FOUND") {
+    console.log(yellow("server not built yet — run `npm run build` first"));
+    process.exit(1);
+  } else {
+    console.log(red(`error: ${err.message}`));
+    process.exit(1);
+  }
+}

package/config/ml.json

@@ -0,0 +1,47 @@
+{
+  "embedding": {
+    "model": "Xenova/bge-small-en-v1.5",
+    "dtype": "int8",
+    "dimensions": 384,
+    "batchSize": 64
+  },
+  "hitl": {
+    "weights": {
+      "course_correction": 20,
+      "architectural_decision": 18,
+      "constraint_spec": 15,
+      "scope_control": 15,
+      "review_qa": 12,
+      "tradeoff_nav": 12,
+      "passive_delegation": -10
+    },
+    "similarityThreshold": 0.55,
+    "confidenceFloor": 0.5,
+    "normalizationScale": 20
+  },
+  "vibe": {
+    "weights": {
+      "file_reference": 18,
+      "technical_spec": 15,
+      "code_sharing": 15,
+      "iterative_refinement": 12,
+      "high_level_delegation": -15,
+      "outcome_only": -12,
+      "acceptance": -10
+    },
+    "similarityThreshold": 0.50,
+    "centerPoint": 50,
+    "normalizationScale": 20
+  },
+  "politeness": {
+    "weights": {
+      "courteous": 20,
+      "warm_collaborative": 15,
+      "direct_neutral": -12,
+      "curt_dismissive": -20
+    },
+    "similarityThreshold": 0.50,
+    "centerPoint": 50,
+    "normalizationScale": 20
+  }
+}

package/data/claude_code/.gitkeep

@@ -0,0 +1,3 @@
+# Place your Claude Code data here
+# Copy from: ~/.claude/projects/
+# Raw Claude Code copies are written here by the Node pipeline