eklavya 1.7.0

package/dist/migrate.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { migrationsDir } from './paths.js';
+const VERSION_KEY = 'schema_version';
+function readVersion(db) {
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(VERSION_KEY);
+    return row ? Number(row.value) : 0;
+}
+function writeVersion(db, version) {
+    db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(VERSION_KEY, String(version));
+}
+/**
+ * Applies numbered SQL migrations in order, recording progress in `meta`.
+ * Idempotent: re-running applies nothing. Returns the filenames applied.
+ */
+export function runMigrations(db, dir = migrationsDir()) {
+    // Bootstrap `meta` itself so the version read below has somewhere to look.
+    db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+    const current = readVersion(db);
+    const files = fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort();
+    const applied = [];
+    for (const file of files) {
+        const n = Number(file.slice(0, 3));
+        if (!Number.isFinite(n) || n === 0) {
+            throw new Error(`Migration filename must start with a number: ${file}`);
+        }
+        if (n <= current)
+            continue;
+        const sql = fs.readFileSync(path.join(dir, file), 'utf8');
+        db.transaction(() => {
+            db.exec(sql);
+            writeVersion(db, n);
+        })();
+        applied.push(file);
+    }
+    return applied;
+}
+export function schemaVersion(db) {
+    return readVersion(db);
+}
+//# sourceMappingURL=migrate.js.map

package/dist/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAErC,SAAS,WAAW,CAAC,EAAY;IAC/B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,WAAW,CAEjE,CAAC;IACd,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,YAAY,CAAC,EAAY,EAAE,OAAe;IACjD,EAAE,CAAC,OAAO,CACR;2DACuD,CACxD,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAY,EAAE,GAAG,GAAG,aAAa,EAAE;IAC/D,2EAA2E;IAC3E,EAAE,CAAC,IAAI,CAAC,6EAA6E,CAAC,CAAC;IAEvF,MAAM,OAAO,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,EAAE;SACb,WAAW,CAAC,GAAG,CAAC;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;SACjC,IAAI,EAAE,CAAC;IAEV,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,gDAAgD,IAAI,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,IAAI,OAAO;YAAE,SAAS;QAE3B,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1D,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE;YAClB,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACb,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC,CAAC,EAAE,CAAC;QACL,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAY;IACxC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}

package/dist/migrations/001_init.sql

@@ -0,0 +1,71 @@
+-- Eklavya schema v1 (PRD §7).
+-- Every statement is IF NOT EXISTS so the runner is safe to re-apply.
+
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS concepts (
+  id          INTEGER PRIMARY KEY,
+  slug        TEXT NOT NULL UNIQUE,        -- 'jwt-structure', 'httponly-cookies'
+  name        TEXT NOT NULL,
+  domain      TEXT NOT NULL,               -- 'web-auth', 'react', 'node-backend', ...
+  description TEXT,
+  tier        INTEGER NOT NULL DEFAULT 1,  -- 1 fundamentals … 5 expert
+  source      TEXT NOT NULL DEFAULT 'seed' -- 'seed' | 'llm'
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  from_concept INTEGER NOT NULL REFERENCES concepts(id),
+  to_concept   INTEGER NOT NULL REFERENCES concepts(id),
+  relation     TEXT NOT NULL CHECK (relation IN ('prerequisite_of','related_to','part_of')),
+  PRIMARY KEY (from_concept, to_concept, relation)
+);
+
+CREATE TABLE IF NOT EXISTS mastery (
+  concept_id   INTEGER PRIMARY KEY REFERENCES concepts(id),
+  score        REAL NOT NULL DEFAULT 0,    -- 0..1
+  ease         REAL NOT NULL DEFAULT 2.5,  -- SM-2 ease factor
+  interval_d   REAL NOT NULL DEFAULT 0,    -- current review interval, days
+  reps         INTEGER NOT NULL DEFAULT 0,
+  last_seen    TEXT,                       -- ISO timestamp
+  next_review  TEXT                        -- ISO timestamp
+);
+
+CREATE TABLE IF NOT EXISTS attempts (
+  id          INTEGER PRIMARY KEY,
+  concept_id  INTEGER NOT NULL REFERENCES concepts(id),
+  session_id  TEXT,
+  question    TEXT NOT NULL,
+  answer      TEXT,
+  grade       INTEGER NOT NULL,            -- 0..5 (SM-2 quality)
+  difficulty  INTEGER NOT NULL,            -- tier the question was asked at
+  feedback    TEXT,                        -- tutor's explanation
+  ts          TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS session_concepts (
+  session_id  TEXT NOT NULL,
+  concept_id  INTEGER NOT NULL REFERENCES concepts(id),
+  context     TEXT,                        -- e.g. 'set httpOnly on refresh cookie in auth.ts'
+  ts          TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (session_id, concept_id)
+);
+
+CREATE TABLE IF NOT EXISTS gates (
+  session_id   TEXT PRIMARY KEY,
+  mode         TEXT NOT NULL,              -- 'ambient' | 'enforced'
+  required     INTEGER NOT NULL DEFAULT 0,
+  answered     INTEGER NOT NULL DEFAULT 0,
+  passed       INTEGER NOT NULL DEFAULT 0, -- boolean
+  updated_at   TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Read paths that must stay fast: the SessionStart hook and the PreToolUse gate
+-- both run on the critical path of a user action (PRD §9).
+CREATE INDEX IF NOT EXISTS idx_concepts_domain       ON concepts(domain);
+CREATE INDEX IF NOT EXISTS idx_session_concepts_sid  ON session_concepts(session_id);
+CREATE INDEX IF NOT EXISTS idx_attempts_concept_ts   ON attempts(concept_id, ts DESC);
+CREATE INDEX IF NOT EXISTS idx_attempts_session      ON attempts(session_id);
+CREATE INDEX IF NOT EXISTS idx_mastery_next_review   ON mastery(next_review);

package/dist/migrations/002_stop_markers.sql

@@ -0,0 +1,14 @@
+-- Loop guard for the Stop hook (phase-2, P0).
+--
+-- `stop_hook_active` is no longer a documented hook input (deviation D2), so the
+-- guard cannot lean on the harness at all. The rule is: block at most once per
+-- set of logged concepts. Blocking stamps the count of concepts logged for the
+-- session; the next Stop only blocks again if that count has grown, which means
+-- genuinely new work happened. `block_count` is a hard backstop on top.
+
+CREATE TABLE IF NOT EXISTS stop_markers (
+  session_id        TEXT PRIMARY KEY,
+  last_blocked_at   TEXT,
+  last_logged_count INTEGER NOT NULL DEFAULT 0,
+  block_count       INTEGER NOT NULL DEFAULT 0
+);

package/dist/migrations/003_gate_repo.sql

@@ -0,0 +1,5 @@
+-- Phase 3: the git pre-commit hook enforces the gate from outside Claude Code,
+-- so a gate row has to say which repository it belongs to (PRD §9.4).
+ALTER TABLE gates ADD COLUMN repo TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_gates_repo ON gates(repo, updated_at DESC);

package/dist/migrations/004_attempt_outcome.sql

@@ -0,0 +1,15 @@
+-- Grade 0 was carrying two opposite meanings: "I don't know, teach me" and
+-- "not now, leave me alone". The tutor skill collapsed them into one row of its
+-- grading table, so a learner asking to be taught was dropped exactly like one
+-- asking to be left alone (observed: four blanks in one session, nothing
+-- taught). SM-2 wants both at 0 -- neither is a recall success -- so the
+-- distinction cannot live in `grade`.
+--
+-- It has to be recorded rather than inferred, because the useful question comes
+-- a day later: "did I already teach this, or has it never been explained?"
+-- `feedback` text cannot answer that reliably.
+--
+-- NULL means "recorded before this column existed"; readers must treat it as
+-- unknown, not as any particular outcome.
+ALTER TABLE attempts ADD COLUMN outcome TEXT
+  CHECK (outcome IN ('answered','dont_know','declined'));

package/dist/migrations/005_session_concept_origin.sql

@@ -0,0 +1,24 @@
+-- `required` is derived from the concepts the session's *work* touched, but
+-- `passed` was satisfiable by any concept in `session_concepts` -- and
+-- `record_attempt` inserts a row there for anything it is asked about, so that
+-- review debt is not free. The two ends never matched: answering concepts the
+-- planner pulled in from elsewhere raised `passedCount` while leaving `required`
+-- frozen, so a gate whose bar was set by today's diff could be cleared without
+-- answering a single question about today's diff.
+--
+-- Focus modes make that the main path rather than a trickle. `concept` focus
+-- widens selection to domain siblings and prerequisites on purpose, and `learn`
+-- focus selects from a topic that may have nothing to do with the session at
+-- all.
+--
+-- So the origin has to be recorded. 'work' is a concept the implementer logged
+-- as part of the task; 'review' is one the tutor pulled in. Both still record
+-- attempts, update mastery and count as `answered` -- review debt stays real --
+-- but only 'work' can satisfy the bar the work itself set.
+--
+-- NULL means "recorded before this column existed". Those rows are read as
+-- 'work', which is what they were in every case that mattered: before focus
+-- modes there was nothing to widen with except same-domain review, and treating
+-- them as 'review' would retroactively unpass gates that have already passed.
+ALTER TABLE session_concepts ADD COLUMN origin TEXT
+  CHECK (origin IN ('work','review'));

package/dist/migrations/006_attempt_format.sql

@@ -0,0 +1,31 @@
+-- A blank prompt is a bad interface for a quiz you did not ask for. Mid-task,
+-- the honest answer to "walk me through what the browser does with this" is
+-- often nothing at all -- not because the learner does not know, but because
+-- typing a paragraph costs more than the question is worth right then.
+-- Recognition is cheap to answer and still teaches, so the default question
+-- shape becomes multiple choice.
+--
+-- Two columns, because the two facts are needed for different reasons:
+--
+-- `format` is what makes the grade readable later. A correct multiple-choice
+-- answer is weaker evidence than a correct free answer -- one in four is a
+-- coin -- so `record_attempt` caps it, and any future rebalancing of mastery
+-- needs to know which attempts were recognition and which were recall. Inferring
+-- it from whether `options` is NULL would work today and break the moment a
+-- format arrives that has no options.
+--
+-- `options` exists so the question text does not have to carry them. Question
+-- fingerprinting (PRD goal 2) hashes `question`, so baking four shuffled options
+-- into that string would make every reshuffle look like a brand-new question and
+-- silently undo "never ask the same question twice". The stem goes in
+-- `question`; the options live here as a JSON array.
+--
+-- NULL `format` means "recorded before this column existed" -- unknown, and in
+-- particular not an assertion that it was free-form.
+--
+-- fill_blank and open are accepted now though nothing writes them yet: the CHECK
+-- is the expensive part to change later, and the next phase adds both.
+ALTER TABLE attempts ADD COLUMN format TEXT
+  CHECK (format IN ('mcq','fill_blank','open'));
+
+ALTER TABLE attempts ADD COLUMN options TEXT;

package/dist/migrations/007_checkpoints.sql

@@ -0,0 +1,23 @@
+-- Interleaved quizzing (phase-8).
+--
+-- Until now the only trigger was the Stop hook, so every question landed after
+-- the work was finished -- four of them, in a row, at the exact moment the
+-- developer wanted to be done. That is a tax on shipping, not learning while the
+-- agent works. `PostToolUse` fires mid-turn and the model sees its output
+-- immediately, so a question can now land at the seam where a concept was
+-- logged, while the code that taught it is still on screen.
+--
+-- This table is the pacing state for that. It is deliberately separate from
+-- `stop_markers`: the two guards protect against different failures.
+-- `stop_markers` stops an end-of-turn loop; this stops a mid-turn burst -- ten
+-- concepts logged in one call must not become ten questions in a row.
+--
+-- `count` is the session's spend against `max_questions_per_task`, which becomes
+-- a SESSION budget rather than an end-of-session batch size. The Stop hook reads
+-- attempts, not this column, so a question answered here is one the Stop hook
+-- will not ask again.
+CREATE TABLE IF NOT EXISTS checkpoints (
+  session_id           TEXT PRIMARY KEY,
+  last_checkpoint_at   TEXT,
+  count                INTEGER NOT NULL DEFAULT 0
+);

package/dist/migrations/008_difficulty_levels.sql

@@ -0,0 +1,57 @@
+-- Difficulty levels, earned per project (phase-9).
+--
+-- Tier already varies per question: `nextTierToAsk` walks a concept from recall
+-- to design as the learner gets it right. What that cannot express is where the
+-- learner stands *on this codebase*, and the gap shows up at both ends. A cold
+-- start takes the median tier of everything they have ever mastered, so someone
+-- with a solid web-auth history opens an unfamiliar React repo on judgement
+-- questions about code they met four minutes ago -- and the honest answer to
+-- those is "no idea", which is the answer that gets a plugin uninstalled.
+--
+-- So a coarse band sits above the tier ladder: easy (tiers 1-2), medium (2-4),
+-- hard (3-5). Everyone starts at easy, and a level is earned by evidence rather
+-- than chosen.
+--
+-- `repo` on attempts, because the band is per project. "How hard should this be"
+-- is a question about a codebase, not about a person: the same developer is a
+-- different learner on their fourth Node service and their first Rust one, and
+-- one global level would have to be wrong for one of them.
+--
+-- `level` on attempts, because progress has to be attributable to the band it
+-- was earned in. Deriving it from `difficulty` afterwards would be wrong in both
+-- directions: the bands overlap, so tier 2 belongs to easy and medium alike.
+--
+-- Both are NULL for every attempt recorded before this migration, and that is
+-- deliberate rather than a gap to backfill later. `repo` is unrecoverable -- the
+-- session's cwd was never stored -- and reading a level out of an old tier-3
+-- answer would hand out promotions nobody earned, on install day, to everyone.
+-- NULL here means unknown, the same as in migrations 004, 005 and 006.
+ALTER TABLE attempts ADD COLUMN repo TEXT;
+
+ALTER TABLE attempts ADD COLUMN level TEXT
+  CHECK (level IN ('easy','medium','hard'));
+
+-- One row per project, created lazily on the first promotion.
+--
+-- `promoted_at` is when this level was entered, and it is what makes progress
+-- countable: the passing answers that count toward the next promotion are the
+-- ones recorded after it. There is deliberately no `passed_at_level` counter --
+-- see `levelProgress` in store.ts. A counter can drift from the attempt rows
+-- that justify it, and it would freeze `level_up_after` at whatever it was when
+-- each attempt landed, so lowering the threshold would not release the learners
+-- already past it.
+--
+-- `repo` is the git root as `findRepoConfig` resolves it (symlinks resolved, so
+-- the server and the git hook agree on the string). A directory outside any
+-- repository falls into the shared '*' bucket rather than minting a row per cwd.
+CREATE TABLE IF NOT EXISTS project_levels (
+  repo        TEXT PRIMARY KEY,
+  level       TEXT NOT NULL DEFAULT 'easy'
+              CHECK (level IN ('easy','medium','hard')),
+  promoted_at TEXT,
+  updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- The progress count runs on the SessionStart critical path (PRD §9.1), so it
+-- gets its own index rather than scanning a growing attempts table.
+CREATE INDEX IF NOT EXISTS idx_attempts_repo_level ON attempts(repo, level, ts DESC);

package/dist/paths.js

@@ -0,0 +1,25 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Eklavya keeps all state in one directory so it is trivially inspectable and
+ * deletable. `EKLAVYA_HOME` exists so tests never touch the real learner's data.
+ */
+export function eklavyaHome() {
+    return process.env.EKLAVYA_HOME ?? path.join(os.homedir(), '.eklavya');
+}
+export function dbPath() {
+    return process.env.EKLAVYA_DB ?? path.join(eklavyaHome(), 'knowledge.db');
+}
+export function globalConfigPath() {
+    return path.join(eklavyaHome(), 'config.json');
+}
+/** Directory of this module — `src/` under tsx, `dist/` after a build. */
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+export function migrationsDir() {
+    return path.join(moduleDir, 'migrations');
+}
+export function seedDir() {
+    return path.join(moduleDir, 'seed');
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,MAAM;IACpB,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED,0EAA0E;AAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/D,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC"}

package/dist/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "eklavya",
+  "description": "Local, privacy-preserving learning tools for agent-assisted development.",
+  "owner": {
+    "name": "Ajay Kumar"
+  },
+  "plugins": [
+    {
+      "name": "eklavya",
+      "source": "./",
+      "description": "Learn while your agent works. Turns coding-agent generation time into adaptive, Socratic learning grounded in the code being written."
+    }
+  ]
+}

package/dist/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "eklavya",
+  "displayName": "Eklavya",
+  "version": "1.7.0",
+  "description": "Learn while your agent works. Turns coding-agent generation time into adaptive, Socratic learning grounded in the code being written.",
+  "author": {
+    "name": "Ajay Kumar"
+  },
+  "license": "MIT",
+  "keywords": [
+    "learning",
+    "spaced-repetition",
+    "tutor",
+    "knowledge-graph",
+    "mentorship"
+  ]
+}

package/dist/plugin/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "eklavya": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs",
+        "server"
+      ]
+    }
+  }
+}

package/dist/plugin/agents/tutor.md

@@ -0,0 +1,63 @@
+---
+name: eklavya-tutor
+description: Teaches the developer the concepts behind work being done, using the Eklavya knowledge graph. Use when you want tutoring to run alongside implementation rather than after it, or when the main thread is busy building and someone should be explaining.
+tools: Read, Grep, Glob, mcp__plugin_eklavya_eklavya__get_learner_profile, mcp__plugin_eklavya_eklavya__get_session_quiz_plan, mcp__plugin_eklavya_eklavya__record_attempt, mcp__plugin_eklavya_eklavya__get_concept_graph, mcp__plugin_eklavya_eklavya__upsert_concepts, mcp__plugin_eklavya_eklavya__get_gate_status, mcp__eklavya__get_learner_profile, mcp__eklavya__get_session_quiz_plan, mcp__eklavya__record_attempt, mcp__eklavya__get_concept_graph, mcp__eklavya__upsert_concepts, mcp__eklavya__get_gate_status
+---
+
+You are Eklavya's tutor, running as a separate agent while implementation happens elsewhere.
+
+Follow the `tutor` skill for all pedagogy — profile first, one question at a time, honest grading, and the `framing` the plan returns. This file only covers what is different about running in parallel.
+
+Note that "grounded in real code" is `project` focus, not a universal rule: in `concept` focus the plan hands you `context: null` deliberately, and quoting the diff back defeats the point. Read `framing` before writing a question.
+
+## Why the tool list is spelled twice
+
+An MCP server provided by a plugin is namespaced: its tools resolve as
+`mcp__plugin_<plugin>_<server>__<tool>`, so Eklavya's are
+`mcp__plugin_eklavya_eklavya__*`. A matcher or allowlist written against the bare
+server key never fires. The bare `mcp__eklavya__*` names are listed as well
+because that *is* the right name when the server is registered from a
+project-level `.mcp.json` — which is how Eklavya's own repo and a Cursor setup
+run it. Whichever install you are in, one set resolves and the other is inert.
+
+If none of them resolve, you have no memory of this learner and must say so
+rather than quizzing blind.
+
+## You cannot use AskUserQuestion
+
+The main session asks quiz questions as multiple choice through the `AskUserQuestion` tool. You do not have it — your tool list is read-only graph access — so render the four options as text instead:
+
+```
+Which of these does `httpOnly` actually prevent?
+
+  A) JavaScript reading the cookie via document.cookie
+  B) The cookie being sent to a different origin
+  C) The cookie surviving a browser restart
+  D) The cookie being read over plain HTTP
+
+Reply with a letter, or "teach me" if you'd rather I explain it.
+```
+
+Same rules as the skill's *Multiple choice* section: four options, three plausible distractors, the stem alone in `record_attempt`'s `question`, the labels in `options`, `format: "mcq"`, and the grade capped at 4. The only thing that changes is who draws the box.
+
+## You do not write code
+
+You have read-only access on purpose. You read what the other agent is building and you teach it. If the developer asks you to change something, tell them to take it back to the main session.
+
+## Reading the work
+
+The implementation is happening in files you can read. Use `Read` and `Grep` to look at what was just written, then ground your questions in it. You are at your most useful when you can say "in the middle of `auth.ts` there's a decision you'd have missed" — because you actually looked.
+
+Do not guess at code you have not read. A question about a line that does not exist destroys trust faster than no question at all.
+
+## Session
+
+You share the knowledge database with the session that spawned you. Omit `session_id` on every call and the server resolves the same session, so what you teach counts toward the same gate and the same mastery history.
+
+## Pacing
+
+You are competing for attention with an agent that is producing code. Ask one question, then wait. If the developer does not answer, do not chase them — they are reading a diff. Silence is a legitimate answer and costs nothing.
+
+Never record a grade for a question that was not answered. Record a decline (`outcome: "declined"`) only when they actually say so.
+
+"I don't know" is not silence and not a decline — it is a request. Teach it: the mechanism, the real lines from the diff, what it generalises to, one takeaway. Then record grade 0 with `outcome: "dont_know"` and move on. See the `tutor` skill for the full shape.

package/dist/plugin/cli/eklavya-gate

@@ -0,0 +1,67 @@
+#!/bin/sh
+# Exit 0 if committing is allowed, 1 if Eklavya's gate is holding it.
+#
+# This is what makes enforcement editor-agnostic (PRD §9.4): the same check runs
+# from a bare terminal, VS Code, or Cursor via the git pre-commit hook.
+#
+# It fails OPEN. A missing jq, a missing database or an unreadable config lets
+# the commit through with a warning. A learning tool that bricks commits when a
+# dependency is absent gets uninstalled, and an unpassable gate teaches nothing.
+
+set -u
+
+eklavya_home() { printf '%s' "${EKLAVYA_HOME:-$HOME/.eklavya}"; }
+eklavya_db()   { printf '%s' "${EKLAVYA_DB:-$(eklavya_home)/knowledge.db}"; }
+
+REPO=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+[ -n "$REPO" ] || exit 0
+
+# Only repos that explicitly opt in are gated.
+CONFIG="$REPO/.eklavya.json"
+[ -f "$CONFIG" ] || exit 0
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf 'eklavya: jq not found, skipping the commit gate.\n' >&2
+  exit 0
+fi
+if ! command -v sqlite3 >/dev/null 2>&1; then
+  printf 'eklavya: sqlite3 not found, skipping the commit gate.\n' >&2
+  exit 0
+fi
+
+MODE=$(jq -r '.mode // "ambient"' "$CONFIG" 2>/dev/null) || exit 0
+[ "$MODE" = "enforced" ] || exit 0
+
+DB=$(eklavya_db)
+[ -f "$DB" ] || exit 0
+
+ESCAPED=$(printf '%s' "$REPO" | sed "s/'/''/g")
+GATE=$(sqlite3 -noheader -batch -cmd ".timeout 2000" "$DB" "
+  SELECT passed || '|' || required || '|' || answered
+    FROM gates
+   WHERE repo = '$ESCAPED'
+   ORDER BY updated_at DESC
+   LIMIT 1;" 2>/dev/null) || exit 0
+
+# No gate for this repo means Eklavya never taught anything here, so there is
+# nothing to have passed.
+[ -n "$GATE" ] || exit 0
+
+PASSED=$(printf '%s' "$GATE" | cut -d'|' -f1)
+REQUIRED=$(printf '%s' "$GATE" | cut -d'|' -f2)
+ANSWERED=$(printf '%s' "$GATE" | cut -d'|' -f3)
+
+[ "$PASSED" = "1" ] && exit 0
+
+cat >&2 <<EOF
+
+  Eklavya is holding this commit.
+
+  You have answered $ANSWERED of $REQUIRED concepts from this session's work.
+  Open Claude Code in this repo and run /eklavya:quiz to finish, then commit again.
+
+  To see what is outstanding:  /eklavya:gate
+  To turn this off for the repo, set "mode" to "ambient" in .eklavya.json
+
+EOF
+exit 1

package/dist/plugin/hooks/hooks.json

@@ -0,0 +1,57 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "session-start"],
+            "timeout": 10,
+            "statusMessage": "Eklavya: loading learner profile"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "pre-tool-gate"],
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__.*log_session_concepts",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "checkpoint-quiz"],
+            "timeout": 10,
+            "statusMessage": "Eklavya: checking if it is time to ask"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "stop-quiz-check"],
+            "timeout": 15,
+            "statusMessage": "Eklavya: checking what you learned"
+          }
+        ]
+      }
+    ]
+  }
+}