eklavya 1.7.0

package/dist/plugin/hooks/run.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * The one entry point every Eklavya hook and the MCP server go through.
+ *
+ * Why this file exists at all: hook commands run under `sh -c` on macOS and
+ * Linux, but on Windows under Git Bash, or PowerShell, or — if WSL is installed
+ * — WSL's bash, which cannot see Windows paths. Shell hooks are a documented
+ * minefield there (claude-code#18610, #21847, #23556, #73971). The hooks
+ * reference names the one portable form: `node` plus a script path, because
+ * `node.exe` is a real executable and needs no shell. So hooks.json says
+ *
+ *     "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs", "<name>"]
+ *
+ * and every platform-specific decision lives here instead of in four shell
+ * scripts.
+ *
+ * The second job is finding the runtime. The plugin payload is source and
+ * manifests only — no `dist/`, no `node_modules/`, because a git-installed
+ * plugin has neither. The compiled server, the hooks and their one native
+ * dependency live in the runtime directory that `eklavya install` populates.
+ * Resolution order, most specific first:
+ *
+ *   1. EKLAVYA_RUNTIME        — tests, and anyone pinning a build
+ *   2. the plugin's own mcp/dist   — a development checkout, so edits take effect
+ *   3. ~/.eklavya/runtime     — what `npx eklavya install` writes
+ *   4. npx eklavya@<pinned>   — the plugin was installed via /plugin and the
+ *                               runtime is not there yet
+ *
+ * Rule 4 is what keeps the two install routes interchangeable: `/plugin install`
+ * alone gets you a working MCP server immediately, and the first session heals
+ * the rest in the background.
+ *
+ * Hard rule (PRD §9.1): a hook must never break a session. Everything here
+ * fails to exit 0 in silence.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const name = process.argv[2];
+// Not `import.meta.dirname`: it is undefined before Node 20.11, and this file
+// has to survive being run by an old Node long enough to say so.
+const hereDir = path.dirname(fileURLToPath(import.meta.url));
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? path.dirname(hereDir);
+const runtimeHome = process.env.EKLAVYA_RUNTIME ?? path.join(homedir(), '.eklavya', 'runtime');
+
+/** Node 22 is where better-sqlite3 ships a prebuilt binary for every platform
+ *  Eklavya supports. Below it, `npm install` falls through to node-gyp and needs
+ *  a C++ toolchain — which is exactly the Windows install failure we removed. */
+const MIN_NODE_MAJOR = 22;
+
+function pinnedVersion() {
+  try {
+    const manifest = path.join(pluginRoot, '.claude-plugin', 'plugin.json');
+    return JSON.parse(readFileSync(manifest, 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** The compiled entry point for `name`, or null if no build is reachable. */
+function resolveEntry() {
+  const relative = name === 'server' ? ['dist', 'server.js'] : ['dist', 'hooks', `${name}.js`];
+
+  const candidates = [
+    process.env.EKLAVYA_RUNTIME ? path.join(process.env.EKLAVYA_RUNTIME, ...relative) : null,
+    // A development checkout: the plugin root is the repo, so mcp/dist is the
+    // build under edit. Requires node_modules too, or better-sqlite3 is missing.
+    existsSync(path.join(pluginRoot, 'mcp', 'node_modules', 'better-sqlite3'))
+      ? path.join(pluginRoot, 'mcp', ...relative)
+      : null,
+    path.join(runtimeHome, 'node_modules', 'eklavya', ...relative),
+  ].filter(Boolean);
+
+  return candidates.find((file) => existsSync(file)) ?? null;
+}
+
+/**
+ * Installs the runtime in the background, at most once.
+ *
+ * This is the self-heal for the `/plugin install` route, which puts the plugin
+ * on disk but cannot run npm for us. Detached and fully ignored: the session
+ * that triggers it is never blocked, never waits, and never sees the output.
+ */
+function healInBackground() {
+  const version = pinnedVersion();
+  if (!version) return;
+
+  // Claim the attempt BEFORE spawning. Four hooks fire per session and the
+  // check alone would let every one of them start its own npm — a spawn storm
+  // on the machine of the person whose install is already struggling. An hour
+  // makes the claim self-expiring, so a heal that dies still gets retried
+  // tomorrow instead of wedging the runtime as missing forever.
+  const stamp = path.join(runtimeHome, '.installing');
+  try {
+    const age = Date.now() - statSync(stamp).mtimeMs;
+    if (age < 60 * 60 * 1000) return;
+  } catch {
+    /* no stamp: this is the first attempt */
+  }
+
+  try {
+    mkdirSync(runtimeHome, { recursive: true });
+    writeFileSync(stamp, new Date().toISOString());
+  } catch {
+    // Cannot even write the stamp, so we cannot bound the retries. Doing
+    // nothing is the safe failure: the explicit installer still works.
+    return;
+  }
+
+  try {
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(
+      npm,
+      ['install', `eklavya@${version}`, '--prefix', runtimeHome, '--omit=dev', '--no-audit', '--no-fund'],
+      { detached: true, stdio: 'ignore', shell: process.platform === 'win32' },
+    );
+    child.unref();
+  } catch {
+    /* A failed heal is a slow install, not a broken session. */
+  }
+}
+
+async function main() {
+  if (!name) process.exit(0);
+
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < MIN_NODE_MAJOR) {
+    // Only the server is worth complaining about — a hook that says this on
+    // every tool call is noise. The installer already refuses loudly.
+    if (name === 'server') {
+      process.stderr.write(
+        `[eklavya] Node ${MIN_NODE_MAJOR}+ is required (found ${process.versions.node}).\n`,
+      );
+    }
+    process.exit(0);
+  }
+
+  const entry = resolveEntry();
+
+  if (entry) {
+    await import(pathToFileURL(entry).href);
+    return;
+  }
+
+  if (name === 'server') {
+    // No runtime yet: fetch it on demand so `/plugin install` alone gives a
+    // working server. stdout is the MCP transport, so npx's chatter must not
+    // land there.
+    const version = pinnedVersion();
+    if (!version) process.exit(0);
+    const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    const child = spawn(npx, ['--yes', `eklavya@${version}`, 'serve'], {
+      stdio: ['inherit', 'inherit', 'ignore'],
+      shell: process.platform === 'win32',
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    return;
+  }
+
+  // A hook with no runtime has nothing to say. Start the heal and get out of
+  // the way — the next session will have it.
+  healInBackground();
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/dist/plugin/scripts/install-git-hook.sh

@@ -0,0 +1,81 @@
+#!/bin/sh
+# Installs (or removes) the git pre-commit hook that enforces Eklavya's gate
+# outside Claude Code. Chains to any pre-commit hook already present rather than
+# replacing it.
+#
+#   scripts/install-git-hook.sh [--uninstall] [repo-path]
+
+set -eu
+
+MARKER="# >>> eklavya gate >>>"
+UNINSTALL=0
+REPO_ARG=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --uninstall) UNINSTALL=1 ;;
+    -h|--help) sed -n '2,8p' "$0"; exit 0 ;;
+    *) REPO_ARG=$arg ;;
+  esac
+done
+
+CLI_PATH=$(cd "$(dirname "$0")/../cli" && pwd)/eklavya-gate
+REPO=${REPO_ARG:-$(git rev-parse --show-toplevel 2>/dev/null || true)}
+
+if [ -z "$REPO" ]; then
+  printf 'Not inside a git repository, and no path given.\n' >&2
+  exit 1
+fi
+
+HOOK_DIR="$REPO/.git/hooks"
+HOOK="$HOOK_DIR/pre-commit"
+CHAINED="$HOOK_DIR/pre-commit.local"
+
+if [ "$UNINSTALL" -eq 1 ]; then
+  if [ -f "$HOOK" ] && grep -q "$MARKER" "$HOOK" 2>/dev/null; then
+    rm -f "$HOOK"
+    if [ -f "$CHAINED" ]; then
+      mv "$CHAINED" "$HOOK"
+      printf 'Removed the Eklavya gate and restored your previous pre-commit hook.\n'
+    else
+      printf 'Removed the Eklavya gate.\n'
+    fi
+  else
+    printf 'No Eklavya gate installed here.\n'
+  fi
+  exit 0
+fi
+
+mkdir -p "$HOOK_DIR"
+
+if [ -f "$HOOK" ] && grep -q "$MARKER" "$HOOK" 2>/dev/null; then
+  printf 'Eklavya gate already installed in %s\n' "$HOOK"
+  exit 0
+fi
+
+# Preserve whatever was there. The existing hook keeps running, first.
+if [ -f "$HOOK" ]; then
+  if [ -f "$CHAINED" ]; then
+    printf 'Refusing to overwrite: both %s and %s already exist.\n' "$HOOK" "$CHAINED" >&2
+    exit 1
+  fi
+  mv "$HOOK" "$CHAINED"
+  printf 'Moved your existing pre-commit hook to %s; it will still run first.\n' "$CHAINED"
+fi
+
+cat > "$HOOK" <<EOF
+#!/bin/sh
+$MARKER
+# Installed by Eklavya. Remove with scripts/install-git-hook.sh --uninstall
+
+if [ -x "\$(dirname "\$0")/pre-commit.local" ]; then
+  "\$(dirname "\$0")/pre-commit.local" "\$@" || exit \$?
+fi
+
+exec "$CLI_PATH"
+# <<< eklavya gate <<<
+EOF
+
+chmod +x "$HOOK"
+printf 'Installed the Eklavya commit gate in %s\n' "$HOOK"
+printf 'It only acts on repositories whose .eklavya.json sets "mode": "enforced".\n'

package/dist/plugin/skills/gate/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: gate
+description: Show the Eklavya commit-gate status for this session.
+disable-model-invocation: true
+---
+
+# /eklavya:gate
+
+Call `get_gate_status` and report it in a few lines:
+
+- Mode. If it is not `enforced`, say that nothing is gated and stop.
+- `answered` of `required` concepts, and the `pass_threshold` they need to clear.
+- Passed or not.
+
+If it has not passed, say exactly what remains and offer to run the quiz now. Do not run it without being asked.
+
+If it has passed, say so in one line. Don't celebrate.

package/dist/plugin/skills/learn/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: learn
+description: Run a structured Eklavya teaching session on a topic, ordered by prerequisites and calibrated to what the developer already knows.
+disable-model-invocation: true
+---
+
+# /eklavya:learn <topic>
+
+Teach `$ARGUMENTS` properly. This is a lesson, not a quiz — but it is still a conversation, and it still records what was learned.
+
+**First, offer to make it stick.** A one-off lesson ends when the conversation does. If they want this topic to keep coming back as they work, `set_config` with `focus: "learn"` and `focus_topic: "$ARGUMENTS"` — from then on quizzes plan from this topic, and use their real code as the example wherever the work touches it. Ask once, in one line; if they decline or say nothing, just teach the lesson. Do not set it silently: it changes what every later session asks about.
+
+1. `get_learner_profile` for the topic's domain. Note `suggested_tier`, and note `known` — those concepts are already theirs. Reference them; do not teach them.
+2. `get_concept_graph` with `include_mastery: true` and `unmastered_only: true`. The order returned **is** the teaching order: prerequisites come before what depends on them.
+3. If the topic isn't a known domain, ask which of the existing domains is closest, or teach from first principles and `upsert_concepts` as you go.
+
+Then, for each concept in order, and **at most 5 per session**:
+
+- Start from what they already know — the profile tells you what that is. Never re-explain a mastered prerequisite; reference it in a clause and move on.
+- Explain in a short paragraph, then show it in code from *this repo* if it appears here. Concrete beats general.
+- Ask one question to check it landed, and grade it with `record_attempt`. For the tier and — crucially — for what has already been asked, call `get_session_quiz_plan` with `slugs: [...]` for the concepts in this lesson and `ignore_cooldown: true`. Its `tier_to_ask` beats `suggested_tier`, and its `asked_before` is what keeps a lesson from re-asking a question from a past one.
+- If they miss it, that concept is not done. Come at it from a different angle before moving on.
+
+Stop when you hit five concepts or they've had enough. Close with what to review next and when — `next_review` from the recorded attempts tells you.
+
+If they set `focus: "learn"` at the top, say so in the closing line, and mention `/eklavya:mode` as the way back out. A standing setting they forgot they made is a setting that feels like a bug later.
+
+Never lecture for more than two exchanges without asking something.

package/dist/plugin/skills/level/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: level
+description: Show or pin Eklavya's difficulty level for this project — the easy/medium/hard band the questions are drawn from, and how far into it the developer is.
+disable-model-invocation: true
+---
+
+# /eklavya:level [auto|easy|medium|hard]
+
+Difficulty is a band, held **per project** and normally earned rather than chosen.
+
+| Level | Tier band | The questions it asks |
+|---|---|---|
+| `easy` | 1–2 | what a thing is, and what the machine does with it |
+| `medium` | 2–4 | why this choice here, and what breaks it |
+| `hard` | 3–5 | judgement, failure modes, when the architecture is wrong |
+
+Everyone starts a codebase at `easy`. That is the point: the developer has been *watching* the agent work, and tiers 1–2 are the questions that state can answer honestly. The band moves up on evidence — passing answers, at a real accuracy, spread across enough concepts — so week ten does not feel like week one.
+
+It is per project because "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.
+
+## No arguments
+
+1. `get_learner_profile` — the `level` block has everything: the band, the next one, `passed` of `needed`, the accuracy so far and the concept spread.
+2. `get_config` if you need to say whether it is pinned, and by which file.
+
+Report it in three lines or fewer:
+
+- **Where they are** — the level, and one clause on what that band asks for.
+- **The runway** — `passed`/`needed` passing answers, plus whichever other condition is still short (accuracy, or distinct concepts). Say the number; a progress bar nobody can total is not progress.
+- **What is next** — the band above, and what changes about the questions when they reach it. If they are on `hard`, say that this is the top and the tier ladder keeps working inside it.
+
+If `pinned` is set, say who pinned it (global config or this repo's `.eklavya.json`) and that nothing will promote while it stands. Do not report a runway toward a level a pin makes unreachable.
+
+## With an argument
+
+`set_config` with `difficulty`.
+
+- **`auto`** — back to earning it. The project's own record is still there; it resumes where its evidence left it.
+- **`easy` / `medium` / `hard`** — pins the band and stops progression. A hard set, not a floor.
+
+Scope, and ask when it is ambiguous:
+
+- **global** (default) — their own setting on every project. `hard` here is a senior saying they do not want the runway.
+- **repo** — `.eklavya.json` at the root, and it beats global for **everyone** working in that project. `easy` here is an onboarding codebase that stays gentle whoever opens it.
+
+Two things to say plainly before writing:
+
+- Pinning at repo scope overrides every contributor's personal setting in that project.
+- Pinning `hard` on a codebase someone has just met is the failure levels exist to prevent. If they are pinning up because the questions feel trivial, check the level first — they may simply be near a promotion.
+
+## Confirm
+
+One line: the new setting, the band it means, and what the next question will look like. Then stop — do not run a quiz unless they ask. `/eklavya:quiz` is for that.

package/dist/plugin/skills/mode/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: mode
+description: Show or change how Eklavya teaches — the focus (project, concept, learn), the enforcement mode (ambient, enforced, off), the cadence (interleaved, end) and the difficulty (auto, easy, medium, hard).
+disable-model-invocation: true
+---
+
+# /eklavya:mode [project|concept|learn|ambient|enforced|off|interleaved|end] [topic]
+
+Eklavya has **four independent dials**, and conflating them is the most common confusion. Say which one you are changing.
+
+| Dial | Question it answers | Values |
+|---|---|---|
+| `mode` | How hard does Eklavya push? | `ambient`, `enforced`, `off` |
+| `focus` | What does it teach? | `concept` (default), `project`, `learn` |
+| `cadence` | When does it ask? | `interleaved` (default), `end` |
+| `difficulty` | How hard may the questions get? | `auto` (default), `easy`, `medium`, `hard` |
+
+`difficulty` is the one that is normally *earned* rather than set: on `auto`, each project starts at `easy` and climbs. **`/eklavya:level` is the command for it** — send them there rather than explaining the ladder here, and only set it from this command if they explicitly asked to pin a level.
+
+They combine freely. `enforced` + `learn` is an intern who must pass a gate on a topic they chose; `ambient` + `project` is a gentle nudge grounded in today's diff. The default pairing is `ambient` + `concept`: teach the idea, use today's code as the way in. `off` is the exception — it wins outright and `focus` is never read.
+
+## No arguments
+
+Call `get_config` and report the effective settings in two lines: mode and what it means, focus and what it means, then cadence and difficulty in a clause each. If `overridden_by_repo` is non-empty, say which settings this repo is overriding and where the file is — someone whose personal focus silently stopped applying needs to be told why, not left to guess.
+
+Then offer the three focus choices below in one line each. Do not lecture.
+
+## The three focus values
+
+- **project** *(default)* — quizzes the code just written. Questions name the file, the line, the decision. Best when you are learning a codebase.
+- **concept** — same subject matter, asked so the answer transfers. The diff becomes the motivation rather than the subject: *"we cached this for 60s — what class of problem does a TTL solve, and when is it the wrong tool?"* Best when you are learning a stack rather than a repo.
+- **learn** — you name a topic; Eklavya teaches it in prerequisite order, whether or not today's work touches it. When the work *does* touch it, your real code becomes the worked example.
+
+## The two cadence values
+
+- **interleaved** *(default)* — one question mid-task, at the moment a concept is logged, while the code is still on screen. The end-of-task quiz then only asks for what is left of `max_questions_per_task`, which is a session budget rather than a batch size. This is the tool working as advertised: learning while the agent builds, not a pile of questions once it stops.
+- **end** — no mid-task questions at all. Everything waits for the end of the task. Reach for it when someone is pairing, demoing, or genuinely cannot be interrupted — and mention `min_minutes_between_checkpoints` first, since spacing the questions out is usually what they actually want.
+
+## Setting it
+
+`set_config` with `focus`, and `focus_topic` when they chose `learn`. Ask for the topic if they picked `learn` without naming one — a `learn` focus with no topic teaches nothing, and the planner will refuse with `reason: "no_topic"`.
+
+Scope matters and is worth one question when it is ambiguous:
+
+- **global** (default) — their own setting, everywhere. This is where a personal `learn` topic belongs.
+- **repo** — writes `.eklavya.json` at the repo root, and beats global for everyone working in it. This is where a lead pins `enforced` or `project` for onboarding.
+
+Warn before writing `focus` at repo scope: it overrides every contributor's personal focus in that project, including a `learn` topic they set for themselves. That is sometimes exactly right, but it should be deliberate.
+
+## Changing mode
+
+Same tool, `mode` key. Follow `/eklavya:setup` step 4 if they move **to** `enforced` — the git `pre-commit` hook is what covers commits made outside Claude Code, and enforced mode without it only gates half the ways to commit.
+
+## Confirm
+
+Say the new state back in one line — `Mode: ambient. Focus: learn (caching). Cadence: interleaved. Difficulty: auto (easy on this repo).` — and what changes next time they build something. If they set `learn`, add that `/eklavya:learn` teaches the topic on demand rather than waiting for a task to touch it.

package/dist/plugin/skills/progress/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: progress
+description: Show the Eklavya mastery map — which projects you have been learning on, what those sessions actually taught, what you skipped, and what is due for review.
+disable-model-invocation: true
+---
+
+# /eklavya:progress
+
+Render the learning map. Read-only: do not quiz, do not teach.
+
+1. `get_learner_profile` (no domain — you want everything).
+2. `get_concept_graph` with `include_mastery: true` only if you need a domain's
+   shape to explain something the profile already flagged. Usually you do not.
+3. `get_gate_status` if the mode is `enforced`.
+
+## What the report has to answer
+
+In this order, because this is the order a learner asks them:
+
+1. **Which project has this been happening on?** `projects` — repo, `answers`,
+   `passed`, `last_active`. Show the basename, not the full path, unless two
+   basenames collide. Compute accuracy yourself and show it as a percentage.
+   A repo of `null` anywhere means work recorded before the repo column
+   existed: label that row `unattributed`, never drop it and never guess.
+2. **What have I actually learned?** `recent_concepts` — and lead with the
+   `context` line, not the slug. `mason-lifecycle-hooks` means nothing;
+   "moved `flutter create` into pre_gen so brick files overlay it" is the
+   memory that makes the slug mean something. Slug second, in parentheses.
+3. **What did I skip?** `skipped` — `declined` means they chose to pass,
+   `dont_know` means they blanked and were taught. Say which. This is the
+   actionable list: those come back a tier lower, so it is a backlog, not a
+   scolding. If it is empty, say so in one clause; it is good news.
+4. **What is due?** `due_for_review` — the count, then the slugs with their
+   `tier_to_ask`. Already clamped to the level, so do not re-explain tiers.
+5. **What is shaky?** `weak` — each with a one-clause gloss of what the concept
+   actually is. A bare slug list is not a report.
+6. **What is mastered?** `known_total`, then the most recent few. If it is 0,
+   name the concepts closest to it instead (one more correct rep, not a first)
+   — a zero with no runway attached reads as failure and it is not.
+
+Finish with **one** concrete next step: `/eklavya:quiz` when anything is due,
+`/eklavya:learn <topic>` when a domain the developer clearly works in is
+mostly unseen.
+
+Then one line pointing at `eklavya dashboard` — the same data as a local page,
+with the history and the full concept list this report deliberately truncates.
+Mention it once, at the end; it is the deeper view, not a replacement for
+answering the question they just asked.
+
+## How to render it
+
+Keep it under 20 lines. A wall of statistics is not a progress report.
+
+- **Lead with movement, not inventory.** The first line is the level, the
+  project, and what changed. Counts of things that have not happened yet go
+  last or nowhere.
+- **Never draw a bar whose biggest segment is `unseen`.** A three-part
+  known/learning/unseen bar on a new learner is a chart of absence: every row
+  looks identical and the one number that moved is invisible. Per domain, one
+  line: `general — 21 in progress, 0 mastered, 46 not yet seen`. Collapse
+  domains with no activity at all into a single trailing line naming them.
+- **Tables only when every column is populated for every row.** Two columns
+  of zeros is prose pretending to be data.
+- The seed catalogue is large on purpose. Never present the unseen count as a
+  gap to close — nobody is meant to learn all 174 concepts, and framing it
+  that way makes the honest numbers feel like failure.
+
+## When there is nothing yet
+
+If `projects`, `recent_concepts` and `attempts` are all empty, say so plainly
+in two lines and suggest building something first — the tool has nothing to
+show until there is work to ground it in. Do not render empty sections.

package/dist/plugin/skills/quiz/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: quiz
+description: Start an Eklavya quiz now, on this session's work or on a named topic.
+disable-model-invocation: true
+---
+
+# /eklavya:quiz [topic]
+
+Quiz the developer now. Follow the `tutor` skill for how to ask and grade — this command only decides *what* to ask about.
+
+The developer asked for this, so always pass `ignore_cooldown: true`. The quiz cadence exists to stop Eklavya nagging; it must never refuse a request.
+
+**Topic given** (`$ARGUMENTS` is non-empty): treat it as a domain, or as one or more concept slugs.
+1. `get_learner_profile` with that domain — `known` is the list you must not ask about.
+2. `get_session_quiz_plan` with `domain: "<topic>"` (or `slugs: [...]` if they named specific concepts) and `ignore_cooldown: true`. The plan already drops what they have mastered, orders prerequisites first, sets each `tier_to_ask`, and hands you `asked_before` so nothing repeats.
+3. If the topic is not a known domain, `get_concept_graph` to see what domains exist, and offer the closest one rather than inventing questions.
+
+**No topic**: quiz this session's work.
+1. `get_learner_profile`.
+2. `get_session_quiz_plan` with `ignore_cooldown: true`.
+3. If `questions_needed` is 0, say why in one line and stop. The `reason` tells you which:
+   - `already_covered` → "Everything from this session has already been asked about. `/eklavya:quiz <topic>` to go wider."
+   - `nothing_logged` → "Nothing logged this session yet, so there's nothing grounded to ask about."
+   - `no_candidates` (topic mode) → that topic is fully mastered and nothing is due; name the closest domain that is not.
+   - `mode_off` → "Eklavya is off. `/eklavya:setup` to turn it back on."
+   - `no_topic` → focus is `learn` with nothing set; ask what they want to learn, then `/eklavya:mode learn <topic>`.
+   - `topic_unknown` → the graph has nothing matching their topic; offer the closest domain rather than inventing questions.
+
+**A named topic overrides the configured focus for this quiz only.** Someone who types `/eklavya:quiz caching` wants caching now; it is not a request to change their standing setting. Do not call `set_config` — `/eklavya:mode` is for that.
+
+Then ask one question at a time at each concept's `tier_to_ask`, following the plan's `framing` field, never repeating anything in `asked_before`, grade every answer with `record_attempt`, and close with one line: what moved, and what comes back for review when.

package/dist/plugin/skills/setup/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: setup
+description: First-run Eklavya setup — check prerequisites, create the knowledge database, and choose a mode.
+disable-model-invocation: true
+---
+
+# /eklavya:setup
+
+Get Eklavya working on this machine. Be brief; this should take one exchange.
+
+**1. Check prerequisites.** Run `node --version`. That is the whole list — the server, the CLI and all four hooks are Node, so nothing else has to be on `PATH`. Node must be 22+; below that the SQLite driver has no prebuilt binary and would need a C++ toolchain to install. If it is older, say so and how to upgrade on this platform, and stop: the rest of setup will not work.
+
+Optionally run `eklavya doctor`, which reports the same thing plus the database and the effective config.
+
+**2. Confirm the database.** Call `get_config` and report `global_path`, then check the DB:
+
+```bash
+sqlite3 ~/.eklavya/knowledge.db 'select domain, count(*) from concepts group by domain'
+```
+
+The server creates and seeds it on first start, and `npx eklavya install` creates it up front, so this should already show `web-auth`, `react`, `node-backend` and `git`. If the file is missing, the MCP server is not running — check `/plugin` for errors, and check that the runtime is installed (`npx eklavya install` finishes it in one step).
+
+**3. Choose a mode.** Ask which fits, and explain in one line each:
+
+- **ambient** (default) — questions after tasks, always skippable
+- **enforced** — the session quiz must pass before a commit goes through; for interns and onboarding
+- **off** — installed but dormant
+
+Then `set_config` with their choice. Use `scope: "repo"` if they want it to apply to this project only — that writes `.eklavya.json` at the repo root, which is how a lead pins enforced mode for one codebase. Otherwise global.
+
+**3b. Choose a focus.** One more question, because it changes every quiz. Mode is how hard Eklavya pushes; focus is what it teaches.
+
+- **project** (default) — asks about the code just written. Best when learning a codebase.
+- **concept** — asks the transferable version of the same ideas. Best when learning a stack.
+- **learn** — you name a topic and it teaches that, using your real code as the example where the work touches it.
+
+`set_config` with `focus`, plus `focus_topic` if they chose `learn` — that combination is useless without one. If they have no preference, say project is the default and move on; this should not become an interview. `/eklavya:mode` changes it later.
+
+**4. If they chose enforced, install the git hook.** The `PreToolUse` hook only covers commits made inside Claude Code. The git `pre-commit` hook covers every other path — a bare terminal, VS Code, Cursor:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}"/scripts/install-git-hook.sh
+```
+
+It chains to any existing `pre-commit` hook rather than replacing it, and only acts on repos whose `.eklavya.json` sets `"mode": "enforced"` — so installing it is safe even if they later switch to ambient. Mention `--uninstall` restores the previous hook.
+
+Skip this step for ambient or off.
+
+**5. Say what happens next.** In ambient mode: build something, and questions will follow. Point at `/eklavya:progress` and `/eklavya:quiz`. In enforced mode, add that commits are held until the session quiz passes, and `/eklavya:gate` shows what is outstanding.