eklavya 1.7.0

package/dist/hooks/session-start.js

@@ -0,0 +1,128 @@
+/**
+ * SessionStart: stamp the session id and print a one-line learner profile.
+ *
+ * Hard rule (PRD §9.1): this must never break a session. Every failure path
+ * exits 0 with no output — `run()` enforces it.
+ */
+import { levelStanding } from '../store.js';
+import { run, openExisting, config, cwdOf, sessionId } from './lib.js';
+/**
+ * The whole tutoring loop starts at log_session_concepts: it is the only writer
+ * of session_concepts, and the Stop hook quizzes from nothing else. An unlogged
+ * session is a silent no-op no matter how much was taught in it, and the Stop
+ * hook exits 0 without a word, so the failure looks like "Eklavya is broken".
+ *
+ * The tutor skill already says to log, but it is model-invoked — it competes
+ * with every other skill on the machine and may never load. So the instruction
+ * is stated here, where every session sees it before any skill is chosen.
+ */
+const DIRECTIVE = `[Eklavya] Standing instruction for this session, on every task — not only when asked to teach:
+  - Once you know what a task involves, call log_session_concepts with the 3-8 concepts it
+    genuinely exercises. Omit session_id. Log while implementing, not at the end.
+  - Log what the code is *about* (jwt-verification, react-effect-cleanup, sql-index-selectivity),
+    not what you did. Give each one a context line naming the real code you wrote.
+  - Guessed slugs are fine: unknown ones are fuzzy-matched or created.
+  - Skip this and there is nothing to quiz on, so nothing is ever learned. Load the tutor skill
+    for how to ask and grade.
+  - Logging may come straight back with an [Eklavya checkpoint]: ONE multiple-choice question to
+    ask right then, before the next line of code, then back to the task in the same turn. That
+    interruption is the product -- learning while the work happens, not a pile of questions after
+    it. One question, no summary, no re-plan, no second question.`;
+/**
+ * "seen" is a mastery row, which only exists once a concept has been attempted.
+ * Gated on that rather than on anything being mastered yet, or a learner three
+ * attempts in is told they have no history.
+ */
+function domainSummary(db) {
+    const rows = db
+        .prepare(`SELECT c.domain AS domain,
+              sum(CASE WHEN m.score >= 0.7 AND m.reps >= 2 THEN 1 ELSE 0 END) AS known,
+              count(*) AS total,
+              sum(CASE WHEN m.concept_id IS NOT NULL THEN 1 ELSE 0 END) AS seen
+         FROM concepts c LEFT JOIN mastery m ON m.concept_id = c.id
+        GROUP BY c.domain
+       HAVING seen > 0
+        ORDER BY known DESC, seen DESC
+        LIMIT 3`)
+        .all();
+    return rows.map((r) => `${r.domain} ${r.known}/${r.total} known`).join(', ');
+}
+/**
+ * Not "reps > 0": a failing grade resets reps to 0, so that filter would hide
+ * precisely the concepts the learner is struggling with. A mastery row at all
+ * means it has been attempted.
+ */
+function weakest(db) {
+    const rows = db
+        .prepare(`SELECT c.slug AS slug FROM concepts c
+         JOIN mastery m ON m.concept_id = c.id
+        WHERE m.score < 0.5
+        ORDER BY m.score ASC
+        LIMIT 3`)
+        .all();
+    return rows.map((r) => r.slug).join(', ');
+}
+function dueCount(db) {
+    const row = db
+        .prepare(`SELECT count(*) AS n FROM mastery
+        WHERE next_review IS NOT NULL
+          AND next_review <= strftime('%Y-%m-%dT%H:%M:%fZ','now')`)
+        .get();
+    return row?.n ?? 0;
+}
+await run(async (input) => {
+    const db = openExisting();
+    if (!db)
+        return 0;
+    const cwd = cwdOf(input);
+    const sid = sessionId(input, db);
+    // Stamp the session so MCP tools resolve the same id the hooks will use later
+    // (decision G1). This happens even when the banner is suppressed.
+    if (sid) {
+        db.prepare(`INSERT INTO meta (key, value) VALUES ('current_session', ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(sid);
+    }
+    const resolved = config(cwd);
+    const { mode, focus, focus_topic, cadence, difficulty, quiet } = resolved.config;
+    if (mode === 'off')
+        return 0;
+    const focusLabel = focus === 'learn' && focus_topic ? `learn (${focus_topic})` : focus;
+    // The level, and how far into it they are. This is the one number that makes
+    // the runway visible: without it, week one and week ten look identical from
+    // the outside, and a learner on `easy` reads tier-2 questions as Eklavya being
+    // shallow rather than as a band they are working through.
+    //
+    // `levelStanding` is the server's own function, so the banner cannot drift
+    // from what the quiz planner actually does — the shell version reimplemented
+    // this query and had to keep it in step by hand.
+    let levelLabel = `${difficulty} (pinned)`;
+    if (difficulty === 'auto') {
+        const standing = levelStanding(db, resolved.config, resolved.repoRoot);
+        levelLabel = `${standing.level} (${standing.counts.passed}/${standing.needed.answers} on this project)`;
+    }
+    if (quiet)
+        return 0;
+    const domains = domainSummary(db);
+    const out = [];
+    if (!domains) {
+        // Nothing learned yet — say the useful thing instead of an empty scoreboard.
+        out.push(`[Eklavya] No learning history yet. Mode: ${mode}. Focus: ${focusLabel}. Cadence: ${cadence}. Level: ${levelLabel}.`);
+    }
+    else {
+        let line = `[Eklavya] Learner profile: ${domains}.`;
+        const weak = weakest(db);
+        if (weak)
+            line += ` Weak: ${weak}.`;
+        const due = dueCount(db);
+        if (due > 0)
+            line += ` ${due} concept(s) due for review.`;
+        out.push(`${line} Mode: ${mode}. Focus: ${focusLabel}. Cadence: ${cadence}. Level: ${levelLabel}.`);
+    }
+    if (resolved.overrides.length > 0) {
+        out.push(`[Eklavya] This repo overrides your global setting for: ${resolved.overrides.join(' ')} (.eklavya.json wins).`);
+    }
+    out.push(DIRECTIVE);
+    process.stdout.write(`${out.join('\n')}\n`);
+    return 0;
+});
+//# sourceMappingURL=session-start.js.map

package/dist/hooks/session-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-start.js","sourceRoot":"","sources":["../../src/hooks/session-start.ts"],"names":[],"mappings":"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"}

package/dist/hooks/stop-quiz-check.js

@@ -0,0 +1,147 @@
+/**
+ * Stop: turn a finished task into a quiz, at most once per batch of work.
+ *
+ * Blocking is exit 2 with the reason on stderr (deviation D1) — the current hooks
+ * reference documents no Stop-specific JSON envelope, but does document that
+ * exit 2 prevents stopping and uses stderr as the message.
+ *
+ * THE LOOP GUARD IS THE POINT OF THIS FILE.
+ * `stop_hook_active` is no longer a documented input (deviation D2), so nothing
+ * here may depend on the harness noticing we already blocked. The rule that keeps
+ * this finite:
+ *
+ *   block only when the number of concepts logged for this session has GROWN
+ *   since the last block.
+ *
+ * Blocking stamps the current count. A Stop that follows with the same count does
+ * not block, whatever happened in between — quiz answered, quiz skipped, model
+ * ignored us entirely. Only genuinely new logged work re-arms it, and
+ * `block_count` caps even that.
+ */
+import { run, openExisting, config, cwdOf, sessionId, minutesSince, framingFor } from './lib.js';
+await run(async (input) => {
+    const db = openExisting();
+    if (!db)
+        return 0;
+    // Belt and braces: honor it if the harness still sends it, depend on it never.
+    if (input.stop_hook_active === true)
+        return 0;
+    const cwd = cwdOf(input);
+    const sid = sessionId(input, db);
+    if (!sid)
+        return 0;
+    const { mode, focus, focus_topic, max_questions_per_task, max_stop_blocks_per_session, min_minutes_between_quizzes, } = config(cwd).config;
+    if (mode === 'off')
+        return 0;
+    const stats = db
+        .prepare(`SELECT
+         (SELECT count(*) FROM session_concepts sc
+            JOIN concepts c ON c.id = sc.concept_id
+            LEFT JOIN mastery m ON m.concept_id = c.id
+           WHERE sc.session_id = @sid
+             AND COALESCE(sc.origin,'work') = 'work'
+             AND NOT (COALESCE(m.score,0) >= 0.7 AND COALESCE(m.reps,0) >= 2)
+             AND sc.concept_id NOT IN
+                 (SELECT concept_id FROM attempts WHERE session_id = @sid)) AS unmastered,
+         -- 'work' only, and the loop guard depends on it: record_attempt inserts a
+         -- session_concepts row for anything it is quizzed on, so counting review
+         -- rows here would let answering a question re-arm the block that asked it.
+         (SELECT count(*) FROM session_concepts
+           WHERE session_id = @sid AND COALESCE(origin,'work') = 'work') AS logged,
+         COALESCE((SELECT last_logged_count FROM stop_markers WHERE session_id = @sid), -1) AS last_logged,
+         COALESCE((SELECT block_count FROM stop_markers WHERE session_id = @sid), 0) AS blocks,
+         (SELECT last_blocked_at FROM stop_markers WHERE session_id = @sid) AS last_blocked,
+         (SELECT ts FROM attempts WHERE session_id = @sid ORDER BY id DESC LIMIT 1) AS last_answer,
+         -- Budget already spent, wherever it was spent. Since 1.4 the mid-work
+         -- checkpoint hook asks from the same allowance, so this is what turns the
+         -- Stop quiz from a fixed batch of four into a sweep of whatever is left.
+         (SELECT count(*) FROM attempts WHERE session_id = @sid) AS spent`)
+        .get({ sid });
+    if (!stats)
+        return 0;
+    // Nothing worth asking about. Concepts already answered in this session are
+    // excluded above: they have had their turn, and re-offering them is exactly the
+    // "asked me the same thing twice" failure this tool exists to avoid.
+    if (stats.unmastered <= 0)
+        return 0;
+    // --- the loop guard --------------------------------------------------------
+    if (!(stats.logged > stats.last_logged))
+        return 0;
+    if (stats.blocks >= max_stop_blocks_per_session)
+        return 0;
+    // Ambient mode respects the quiz cadence. Enforced mode must not, or a cooldown
+    // could make a commit gate unpassable (decision G5).
+    //
+    // Both clocks matter, and for the same reason. get_session_quiz_plan applies its
+    // cooldown from the last *answer*; this hook stamps the last *block*. Checking
+    // only the block would let us block a turn that the quiz plan then refuses as
+    // too soon, which reads to the model as being told to teach and given nothing to
+    // teach. Whichever happened more recently wins.
+    if (mode === 'ambient') {
+        if (minutesSince(stats.last_blocked) < min_minutes_between_quizzes)
+            return 0;
+        if (minutesSince(stats.last_answer) < min_minutes_between_quizzes)
+            return 0;
+    }
+    // ---------------------------------------------------------------------------
+    // --- what is left of the session budget ------------------------------------
+    // `max_questions_per_task` is a SESSION allowance, not an end-of-session batch
+    // size. Every question answered while the agent was working is one this hook
+    // must not ask again -- that is the whole trade the interleaved cadence makes,
+    // and without this subtraction it would be a lie: four questions mid-task and
+    // then four more at the end is worse than what it replaced.
+    //
+    // Answer the whole budget during the work and the Stop hook says nothing at all.
+    const remaining = max_questions_per_task - stats.spent;
+    if (remaining <= 0)
+        return 0;
+    // ---------------------------------------------------------------------------
+    const rows = db
+        .prepare(`SELECT c.slug || COALESCE(' (' || sc.context || ')', '') AS line
+         FROM session_concepts sc
+         JOIN concepts c ON c.id = sc.concept_id
+         LEFT JOIN mastery m ON m.concept_id = c.id
+        WHERE sc.session_id = @sid
+          AND COALESCE(sc.origin,'work') = 'work'
+          AND NOT (COALESCE(m.score,0) >= 0.7 AND COALESCE(m.reps,0) >= 2)
+          AND sc.concept_id NOT IN
+              (SELECT concept_id FROM attempts WHERE session_id = @sid)
+        ORDER BY sc.ts ASC
+        LIMIT @remaining`)
+        .all({ sid, remaining });
+    const concepts = rows.map((r) => r.line).join('; ');
+    // Stamp the guard BEFORE blocking. If anything below fails, the worst case is a
+    // missed quiz — never a loop.
+    db.prepare(`INSERT INTO stop_markers (session_id, last_blocked_at, last_logged_count, block_count)
+     VALUES (@sid, strftime('%Y-%m-%dT%H:%M:%fZ','now'), @logged, 1)
+     ON CONFLICT(session_id) DO UPDATE SET
+       last_blocked_at   = excluded.last_blocked_at,
+       last_logged_count = excluded.last_logged_count,
+       block_count       = stop_markers.block_count + 1`).run({ sid, logged: stats.logged });
+    const framing = framingFor(focus, focus_topic, 'stop');
+    const tone = mode === 'enforced'
+        ? 'This session is in enforced mode: the commit gate needs this quiz.'
+        : 'If they say skip, record it as grade 0 and let them go — do not ask twice.';
+    process.stderr.write(`Eklavya: before finishing, quiz the developer on what this task just taught.
+
+Concepts: ${concepts}
+
+Use the eklavya MCP server and the tutor skill: call get_session_quiz_plan, ask
+ONE question at a time at each concept's tier_to_ask, and grade each answer with
+record_attempt. The plan returns a "framing" field. Follow it.
+
+Ask each question as MULTIPLE CHOICE via the AskUserQuestion tool: four options,
+one correct and three plausible, header "Eklavya" so it is clear who is asking.
+The tool's own "Other" choice is the escape hatch for "I don't know". They are
+mid-task -- a blank prompt gets skipped whether or not they knew the answer.
+End each question's text with a blank line and then that plan item's ask_footer,
+verbatim: the mode, focus, level, tier and how many questions are coming. It is
+the only thing on screen saying why a question is pitched where it is.
+Record with format "mcq", the labels in "options", and only the stem in
+"question" -- never the footer.
+${framing}
+${tone}
+`);
+    return 2;
+});
+//# sourceMappingURL=stop-quiz-check.js.map

package/dist/hooks/stop-quiz-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-quiz-check.js","sourceRoot":"","sources":["../../src/hooks/stop-quiz-check.ts"],"names":[],"mappings":"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"}

package/dist/install.js

@@ -0,0 +1,313 @@
+/**
+ * `eklavya install` — the whole setup, from a terminal, on macOS or Windows.
+ *
+ * Claude Code's own route is `/plugin marketplace add` + `/plugin install`, and
+ * that still works. This is the other door: it needs no Claude Code session, and
+ * it is the one that can install what Eklavya depends on, because a slash
+ * command cannot run npm.
+ *
+ * What it has to get right, in order:
+ *
+ *   1. Node 22+. Below that, better-sqlite3 has no prebuilt binary and npm falls
+ *      through to node-gyp, which needs a C++ toolchain nobody has on Windows.
+ *      This is a hard refusal with per-platform instructions, not a warning:
+ *      continuing produces a half-install that fails later and mystifies.
+ *   2. The runtime. `npm install eklavya@<version> --prefix ~/.eklavya/runtime`
+ *      puts the compiled server, the hooks and that one native dependency
+ *      somewhere both install routes can find them.
+ *   3. The plugin payload, copied into the Claude Code marketplace directory.
+ *   4. Claude Code's three registry files, written directly. There is no public
+ *      API for "install this plugin" from outside a session, so this reproduces
+ *      what `/plugin install` does. See the comment on `register()`.
+ *   5. The database, created and seeded.
+ *
+ * Every step is idempotent: running it twice is how you upgrade.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { openDb } from './db.js';
+import { dbPath, eklavyaHome } from './paths.js';
+const MIN_NODE_MAJOR = 22;
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+/** The npm package root — `dist/` under a build, so one level up. */
+function packageRoot() {
+    return path.dirname(moduleDir);
+}
+/** The plugin payload the build copies into the package (see copy-assets.mjs). */
+function payloadDir() {
+    return path.join(moduleDir, 'plugin');
+}
+function packageVersion() {
+    const manifest = path.join(packageRoot(), 'package.json');
+    return JSON.parse(fs.readFileSync(manifest, 'utf8')).version;
+}
+/**
+ * Claude Code's config root. `CLAUDE_CONFIG_DIR` is the documented override and
+ * people with several profiles do set it — writing to `~/.claude` regardless
+ * would install into a directory their Claude Code never reads.
+ */
+export function claudeHome() {
+    return process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), '.claude');
+}
+export function marketplaceDir() {
+    return path.join(claudeHome(), 'plugins', 'marketplaces', 'eklavya');
+}
+export function runtimeHome() {
+    return process.env.EKLAVYA_RUNTIME ?? path.join(eklavyaHome(), 'runtime');
+}
+const say = (line) => process.stdout.write(`${line}\n`);
+// --- 1. prerequisites -------------------------------------------------------
+/** How to get a modern Node, on the platform actually in front of them. */
+function nodeAdvice() {
+    if (process.platform === 'win32') {
+        return [
+            '  winget install OpenJS.NodeJS.LTS',
+            '  …or download the installer from https://nodejs.org',
+        ].join('\n');
+    }
+    if (process.platform === 'darwin') {
+        return ['  brew install node', '  …or download the installer from https://nodejs.org'].join('\n');
+    }
+    return [
+        '  Use your distribution package, nvm, or https://nodejs.org',
+        '  e.g. nvm install 22 && nvm use 22',
+    ].join('\n');
+}
+function checkNode() {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major >= MIN_NODE_MAJOR)
+        return;
+    process.stderr.write(`Eklavya needs Node ${MIN_NODE_MAJOR} or newer — this is Node ${process.versions.node}.\n\n` +
+        'Below Node 22, the SQLite driver has no prebuilt binary for your platform and npm\n' +
+        'tries to compile it, which needs a full C++ toolchain. Upgrading Node is the fix:\n\n' +
+        `${nodeAdvice()}\n\nThen run \`npx eklavya install\` again.\n`);
+    process.exit(1);
+}
+/**
+ * git is optional, and saying so matters. Eklavya keys a project's difficulty
+ * level on the repository root, and the commit gate is a git hook — without git
+ * both degrade to the shared bucket rather than failing.
+ */
+function checkGit() {
+    const probe = spawnSync('git', ['--version'], { stdio: 'ignore', shell: process.platform === 'win32' });
+    return probe.status === 0;
+}
+// --- 2. the runtime ---------------------------------------------------------
+function installRuntime(version) {
+    const home = runtimeHome();
+    fs.mkdirSync(home, { recursive: true });
+    // A stamp file so the plugin's background self-heal does not race a manual
+    // install. Removed in the finally, whatever happens.
+    const stamp = path.join(home, '.installing');
+    fs.writeFileSync(stamp, String(process.pid), 'utf8');
+    try {
+        const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+        const result = spawnSync(npm, [
+            'install',
+            `eklavya@${version}`,
+            '--prefix',
+            home,
+            '--omit=dev',
+            '--no-audit',
+            '--no-fund',
+            '--loglevel=error',
+        ], { stdio: ['ignore', 'inherit', 'inherit'], shell: process.platform === 'win32' });
+        if (result.status !== 0) {
+            process.stderr.write('\nInstalling the Eklavya runtime failed. The output above says why — the usual\n' +
+                'causes are no network, or a registry proxy that blocks the download.\n' +
+                `You can retry with: npm install eklavya@${version} --prefix ${home}\n`);
+            process.exit(1);
+        }
+    }
+    finally {
+        try {
+            fs.rmSync(stamp, { force: true });
+        }
+        catch {
+            /* nothing depends on the stamp being gone */
+        }
+    }
+}
+/**
+ * Proves the native dependency actually loads, rather than trusting that npm
+ * exiting 0 means a working binary. A prebuilt binary for the wrong ABI installs
+ * cleanly and throws on first require — which would otherwise surface as a dead
+ * MCP server three commands later.
+ */
+function verifyRuntime() {
+    const entry = path.join(runtimeHome(), 'node_modules', 'eklavya', 'dist', 'server.js');
+    if (!fs.existsSync(entry)) {
+        process.stderr.write(`The runtime installed but ${entry} is missing.\n`);
+        process.exit(1);
+    }
+    const probe = spawnSync(process.execPath, ['-e', 'require(process.argv[1]); console.log("ok")', path.join(runtimeHome(), 'node_modules', 'better-sqlite3')], { encoding: 'utf8' });
+    if (probe.status !== 0) {
+        process.stderr.write('\nThe SQLite driver installed but will not load:\n' +
+            `${(probe.stderr ?? '').trim()}\n\n` +
+            'This usually means the prebuilt binary does not match this Node version.\n' +
+            `Try removing ${runtimeHome()} and running \`npx eklavya install\` again.\n`);
+        process.exit(1);
+    }
+}
+// --- 3. the plugin payload --------------------------------------------------
+function copyPayload() {
+    const from = payloadDir();
+    if (!fs.existsSync(from)) {
+        process.stderr.write(`The plugin payload is missing from this package (expected ${from}).\n` +
+            'This is a packaging bug — please report it.\n');
+        process.exit(1);
+    }
+    const to = marketplaceDir();
+    // Replace rather than merge: a stale hook or skill left behind by an older
+    // version is worse than a slow copy, and this directory is ours entirely.
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.cpSync(from, to, { recursive: true });
+}
+// --- 4. Claude Code's registries --------------------------------------------
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Write via temp file + rename: Claude Code may be reading this mid-write. */
+function writeJson(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, file);
+}
+/**
+ * Registers the plugin the way `/plugin install` would.
+ *
+ * There is no supported CLI for this, so these three files are written directly.
+ * That is a real cost and worth naming: their shape is Claude Code's private
+ * business and can change — `installed_plugins.json` already carries a
+ * `"version": 2`. The mitigation is that every write is additive and keyed, so a
+ * shape change loses the registration rather than corrupting anyone's config,
+ * and `eklavya doctor` reports it.
+ *
+ * The marketplace is registered with its GitHub source even though the files
+ * came from npm, and deliberately: that is what lets Claude Code's own
+ * `/plugin update` take over afterwards. npm is the on-ramp, not the channel.
+ *
+ * ponytail: three private files, no public API. If Claude Code ever ships
+ * `claude plugin install --local`, delete this and shell out to it.
+ */
+function register(version) {
+    const pluginsDir = path.join(claudeHome(), 'plugins');
+    const marketplaces = path.join(pluginsDir, 'known_marketplaces.json');
+    const known = readJson(marketplaces);
+    known.eklavya = {
+        source: { source: 'github', repo: 'ProjectAJ14/eklavya' },
+        installLocation: marketplaceDir(),
+        lastUpdated: new Date().toISOString(),
+        autoUpdate: true,
+    };
+    writeJson(marketplaces, known);
+    const installedPath = path.join(pluginsDir, 'installed_plugins.json');
+    const installed = readJson(installedPath);
+    if (typeof installed.version !== 'number')
+        installed.version = 2;
+    const plugins = (installed.plugins ?? {});
+    plugins['eklavya@eklavya'] = [
+        {
+            scope: 'user',
+            installPath: marketplaceDir(),
+            version,
+            installedAt: new Date().toISOString(),
+            lastUpdated: new Date().toISOString(),
+        },
+    ];
+    installed.plugins = plugins;
+    writeJson(installedPath, installed);
+    const settingsPath = path.join(claudeHome(), 'settings.json');
+    const settings = readJson(settingsPath);
+    const enabled = (settings.enabledPlugins ?? {});
+    enabled['eklavya@eklavya'] = true;
+    settings.enabledPlugins = enabled;
+    writeJson(settingsPath, settings);
+}
+function deregister() {
+    const pluginsDir = path.join(claudeHome(), 'plugins');
+    const marketplaces = path.join(pluginsDir, 'known_marketplaces.json');
+    const known = readJson(marketplaces);
+    if ('eklavya' in known) {
+        delete known.eklavya;
+        writeJson(marketplaces, known);
+    }
+    const installedPath = path.join(pluginsDir, 'installed_plugins.json');
+    const installed = readJson(installedPath);
+    const plugins = (installed.plugins ?? {});
+    if ('eklavya@eklavya' in plugins) {
+        delete plugins['eklavya@eklavya'];
+        installed.plugins = plugins;
+        writeJson(installedPath, installed);
+    }
+    const settingsPath = path.join(claudeHome(), 'settings.json');
+    const settings = readJson(settingsPath);
+    const enabled = (settings.enabledPlugins ?? {});
+    if ('eklavya@eklavya' in enabled) {
+        delete enabled['eklavya@eklavya'];
+        settings.enabledPlugins = enabled;
+        writeJson(settingsPath, settings);
+    }
+}
+// --- commands ---------------------------------------------------------------
+export function install(args) {
+    const version = packageVersion();
+    say(`Installing Eklavya ${version}`);
+    checkNode();
+    say(`  node        ${process.versions.node}`);
+    if (!args.includes('--skip-runtime')) {
+        say('  runtime     installing (first run downloads the SQLite driver)…');
+        installRuntime(version);
+        verifyRuntime();
+        say(`  runtime     ${runtimeHome()}`);
+    }
+    copyPayload();
+    say(`  plugin      ${marketplaceDir()}`);
+    register(version);
+    say('  registered  eklavya@eklavya, enabled for Claude Code');
+    // Creating the DB here rather than on first server start means `eklavya
+    // doctor` and the dashboard work before Claude Code has ever been opened.
+    const db = openDb();
+    db.close();
+    say(`  database    ${dbPath()}`);
+    if (!checkGit()) {
+        say('');
+        say('  note: git was not found. Eklavya still works — the per-project difficulty');
+        say('        level falls back to a shared bucket, and the commit gate needs git.');
+    }
+    say('');
+    say('Done. Restart Claude Code (or start a session) and Eklavya loads with it.');
+    say('Next: run /eklavya:setup in Claude Code to choose a mode, or `eklavya doctor` here.');
+}
+export function uninstall(args) {
+    const purge = args.includes('--purge');
+    deregister();
+    say('  registered  removed from Claude Code');
+    fs.rmSync(marketplaceDir(), { recursive: true, force: true });
+    say('  plugin      removed');
+    fs.rmSync(runtimeHome(), { recursive: true, force: true });
+    say('  runtime     removed');
+    if (purge) {
+        // Only ever on an explicit flag. This is everything the learner has done —
+        // months of spaced repetition — and an uninstall that silently deletes it is
+        // not an uninstall, it is data loss.
+        fs.rmSync(eklavyaHome(), { recursive: true, force: true });
+        say(`  data        removed (${eklavyaHome()})`);
+    }
+    else {
+        say(`  data        kept (${dbPath()}) — pass --purge to delete your learning history`);
+    }
+    say('');
+    say('Eklavya is uninstalled. Restart Claude Code to unload it.');
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/mcq.js

@@ -0,0 +1,34 @@
+/**
+ * Where the correct option goes in a multiple-choice question.
+ *
+ * This is decided server-side, for the same reason `tier_to_ask` and
+ * `format_to_use` are: left to the model, it is not decided at all. An LLM asked
+ * to "vary the position" reliably puts the right answer first — it writes the
+ * answer it is thinking of, then invents distractors after it — so learners
+ * discover within a handful of questions that A is always correct and stop
+ * reading the options. The quiz keeps working and stops measuring anything.
+ *
+ * Deterministic rather than random: the same question asked twice in a session
+ * must not move under the learner, tests need a fixed answer, and a plan is
+ * rebuilt on every call. Varying by attempt count is what makes a re-ask of the
+ * same concept land somewhere new.
+ */
+/** FNV-1a, 32-bit. Small, dependency-free, and well spread over short strings. */
+function hash(seed) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i += 1) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h >>> 0;
+}
+export const MCQ_OPTION_COUNT = 4;
+/**
+ * 1-based position for the correct option. `askedCount` is how many questions
+ * this learner has already been asked about the concept, so a concept that comes
+ * back for review does not come back in the same shape.
+ */
+export function answerPosition(slug, askedCount = 0, optionCount = MCQ_OPTION_COUNT) {
+    return (hash(`${slug}:${askedCount}`) % optionCount) + 1;
+}
+//# sourceMappingURL=mcq.js.map

package/dist/mcq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcq.js","sourceRoot":"","sources":["../src/mcq.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kFAAkF;AAClF,SAAS,IAAI,CAAC,IAAY;IACxB,IAAI,CAAC,GAAG,UAAU,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,UAAU,GAAG,CAAC,EAAE,WAAW,GAAG,gBAAgB;IACzF,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,UAAU,EAAE,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;AAC3D,CAAC"}