eklavya-mcp 1.0.0

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/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/seed/git.json

@@ -0,0 +1,49 @@
+{
+  "domain": "git",
+  "concepts": [
+    { "slug": "git-repository", "name": "Repository and object model", "tier": 1, "description": "Commits, trees and blobs in a content-addressed store — everything else in git is a view over this." },
+    { "slug": "git-commit", "name": "Commits", "tier": 1, "description": "An immutable snapshot plus parent pointers; history is a DAG, not a list." },
+    { "slug": "git-staging-area", "name": "Staging area", "tier": 1, "description": "The index — the explicit space between working tree and commit that makes partial commits possible." },
+    { "slug": "git-branch", "name": "Branches", "tier": 1, "description": "A movable pointer to a commit; branching is cheap because nothing is copied." },
+    { "slug": "git-remote", "name": "Remotes and tracking branches", "tier": 1, "description": "Local mirrors of another repository's refs, updated only by fetch." },
+    { "slug": "gitignore", "name": ".gitignore", "tier": 1, "description": "Patterns excluding files from tracking — and why it does nothing for already-tracked files." },
+
+    { "slug": "git-merge", "name": "Merging", "tier": 2, "description": "Joining histories with a merge commit; fast-forward versus true merge." },
+    { "slug": "git-rebase", "name": "Rebasing", "tier": 2, "description": "Replaying commits onto a new base, producing new commit objects with new hashes." },
+    { "slug": "git-conflict-resolution", "name": "Conflict resolution", "tier": 2, "description": "What a conflict actually is, and why resolving it is a content decision git cannot make." },
+    { "slug": "git-stash", "name": "Stashing", "tier": 2, "description": "Parking uncommitted work on a hidden ref to get a clean tree." },
+    { "slug": "git-detached-head", "name": "Detached HEAD", "tier": 2, "description": "HEAD pointing at a commit rather than a branch, and how commits made there get orphaned." },
+    { "slug": "git-hooks", "name": "Git hooks", "tier": 2, "description": "Local scripts fired at lifecycle points such as pre-commit — the mechanism Eklavya's own gate uses." },
+
+    { "slug": "git-reset-modes", "name": "reset --soft/--mixed/--hard", "tier": 3, "description": "Which of HEAD, index and working tree each mode moves — the difference between recoverable and lost work." },
+    { "slug": "git-reflog", "name": "Reflog", "tier": 3, "description": "The local log of where refs have pointed; the recovery tool for almost every 'I lost it' situation." },
+    { "slug": "git-cherry-pick", "name": "Cherry-picking", "tier": 3, "description": "Applying one commit's change onto another branch, and the duplicate-commit problem it creates." },
+    { "slug": "git-merge-vs-rebase", "name": "Merge vs rebase: tradeoffs", "tier": 3, "description": "Truthful history versus readable history, and why the choice is a team policy, not a technical fact." },
+
+    { "slug": "git-interactive-rebase", "name": "Interactive rebase", "tier": 4, "description": "Reordering, squashing and editing history — and what it does to anyone who already pulled it." },
+    { "slug": "git-force-push-safety", "name": "Force-push safety", "tier": 4, "description": "Why --force-with-lease exists and what plain --force silently destroys." },
+    { "slug": "git-bisect", "name": "Bisect", "tier": 4, "description": "Binary search over history to find the commit that introduced a regression." }
+  ],
+  "edges": [
+    { "from": "git-repository", "to": "git-commit", "relation": "prerequisite_of" },
+    { "from": "git-commit", "to": "git-branch", "relation": "prerequisite_of" },
+    { "from": "git-commit", "to": "git-staging-area", "relation": "prerequisite_of" },
+    { "from": "git-branch", "to": "git-merge", "relation": "prerequisite_of" },
+    { "from": "git-branch", "to": "git-rebase", "relation": "prerequisite_of" },
+    { "from": "git-branch", "to": "git-remote", "relation": "prerequisite_of" },
+    { "from": "git-branch", "to": "git-detached-head", "relation": "prerequisite_of" },
+    { "from": "git-merge", "to": "git-conflict-resolution", "relation": "prerequisite_of" },
+    { "from": "git-merge", "to": "git-merge-vs-rebase", "relation": "prerequisite_of" },
+    { "from": "git-rebase", "to": "git-merge-vs-rebase", "relation": "prerequisite_of" },
+    { "from": "git-rebase", "to": "git-interactive-rebase", "relation": "prerequisite_of" },
+    { "from": "git-interactive-rebase", "to": "git-force-push-safety", "relation": "prerequisite_of" },
+    { "from": "git-remote", "to": "git-force-push-safety", "relation": "prerequisite_of" },
+    { "from": "git-staging-area", "to": "git-reset-modes", "relation": "prerequisite_of" },
+    { "from": "git-detached-head", "to": "git-reflog", "relation": "prerequisite_of" },
+    { "from": "git-reset-modes", "to": "git-reflog", "relation": "prerequisite_of" },
+    { "from": "git-commit", "to": "git-cherry-pick", "relation": "prerequisite_of" },
+    { "from": "git-commit", "to": "git-bisect", "relation": "prerequisite_of" },
+    { "from": "git-staging-area", "to": "git-stash", "relation": "related_to" },
+    { "from": "gitignore", "to": "git-staging-area", "relation": "related_to" }
+  ]
+}

package/dist/seed/node-backend.json

@@ -0,0 +1,43 @@
+{
+  "domain": "node-backend",
+  "concepts": [
+    { "slug": "node-event-loop", "name": "The event loop", "tier": 1, "description": "One thread, a queue of callbacks; concurrency comes from not waiting, not from parallelism." },
+    { "slug": "node-modules", "name": "CommonJS vs ESM", "tier": 1, "description": "require versus import, and the resolution and interop rules that differ between them." },
+    { "slug": "node-http-server", "name": "HTTP server basics", "tier": 1, "description": "Request and response streams underneath every framework abstraction." },
+    { "slug": "node-env-vars", "name": "Environment variables and secrets", "tier": 1, "description": "Configuration outside the code, and why secrets never belong in the repository." },
+
+    { "slug": "express-routing", "name": "Routing", "tier": 2, "description": "Matching method and path to a handler, including how route order decides ambiguity." },
+    { "slug": "express-middleware", "name": "Middleware", "tier": 2, "description": "Functions in a chain that may inspect, mutate, short-circuit or pass along a request." },
+    { "slug": "node-async-await", "name": "async/await and promises", "tier": 2, "description": "Sequencing asynchronous work without blocking the loop, and where errors surface." },
+    { "slug": "express-body-parsing", "name": "Request body parsing", "tier": 2, "description": "Turning a request stream into a usable value, and why size limits matter." },
+    { "slug": "node-input-validation", "name": "Input validation", "tier": 2, "description": "Rejecting malformed input at the boundary rather than deep inside a handler." },
+    { "slug": "express-error-handling", "name": "Error-handling middleware", "tier": 2, "description": "The four-argument handler, and why an unawaited rejection never reaches it." },
+
+    { "slug": "express-middleware-order", "name": "Middleware ordering", "tier": 3, "description": "The chain is sequential; a misplaced auth or parser leaves a route unprotected or a body undefined." },
+    { "slug": "node-connection-pooling", "name": "Connection pooling", "tier": 3, "description": "Reusing database connections, and what pool exhaustion looks like from the outside." },
+    { "slug": "node-streams-backpressure", "name": "Streams and backpressure", "tier": 3, "description": "Letting a slow consumer throttle a fast producer instead of buffering into memory." },
+    { "slug": "node-logging-observability", "name": "Structured logging", "tier": 3, "description": "Machine-readable logs with request correlation, so production failures are diagnosable." },
+
+    { "slug": "node-event-loop-blocking", "name": "Blocking the event loop", "tier": 4, "description": "Synchronous CPU work stalling every other request on the process." },
+    { "slug": "node-graceful-shutdown", "name": "Graceful shutdown", "tier": 4, "description": "Draining in-flight requests and closing resources on SIGTERM instead of dropping them." },
+    { "slug": "node-clustering-scaling", "name": "Clustering and horizontal scale", "tier": 4, "description": "Multiple processes behind a balancer, and what that breaks for in-process state." }
+  ],
+  "edges": [
+    { "from": "node-event-loop", "to": "node-async-await", "relation": "prerequisite_of" },
+    { "from": "node-event-loop", "to": "node-event-loop-blocking", "relation": "prerequisite_of" },
+    { "from": "node-http-server", "to": "express-routing", "relation": "prerequisite_of" },
+    { "from": "node-http-server", "to": "node-streams-backpressure", "relation": "prerequisite_of" },
+    { "from": "express-routing", "to": "express-middleware", "relation": "prerequisite_of" },
+    { "from": "express-middleware", "to": "express-middleware-order", "relation": "prerequisite_of" },
+    { "from": "express-middleware", "to": "express-body-parsing", "relation": "prerequisite_of" },
+    { "from": "express-middleware", "to": "express-error-handling", "relation": "prerequisite_of" },
+    { "from": "node-async-await", "to": "express-error-handling", "relation": "prerequisite_of" },
+    { "from": "express-body-parsing", "to": "node-input-validation", "relation": "prerequisite_of" },
+    { "from": "node-async-await", "to": "node-connection-pooling", "relation": "prerequisite_of" },
+    { "from": "node-http-server", "to": "node-graceful-shutdown", "relation": "prerequisite_of" },
+    { "from": "node-env-vars", "to": "node-clustering-scaling", "relation": "related_to" },
+    { "from": "node-connection-pooling", "to": "node-clustering-scaling", "relation": "prerequisite_of" },
+    { "from": "node-modules", "to": "node-http-server", "relation": "related_to" },
+    { "from": "node-logging-observability", "to": "node-graceful-shutdown", "relation": "related_to" }
+  ]
+}

package/dist/seed/react.json

@@ -0,0 +1,46 @@
+{
+  "domain": "react",
+  "concepts": [
+    { "slug": "react-component", "name": "Components", "tier": 1, "description": "A function taking props and returning a description of UI — not a template and not an object." },
+    { "slug": "react-jsx", "name": "JSX", "tier": 1, "description": "Syntax sugar over createElement calls; it produces data, not DOM." },
+    { "slug": "react-props", "name": "Props", "tier": 1, "description": "Read-only inputs flowing down; mutating them breaks the model." },
+    { "slug": "react-state", "name": "State", "tier": 1, "description": "Values a component owns, whose change triggers a re-render." },
+    { "slug": "react-lists-keys", "name": "Lists and keys", "tier": 1, "description": "Keys give list children a stable identity across renders; index keys quietly break on reorder." },
+
+    { "slug": "react-hooks-rules", "name": "Rules of hooks", "tier": 2, "description": "Hooks are matched to state by call order, which is why they cannot be conditional." },
+    { "slug": "react-usestate", "name": "useState", "tier": 2, "description": "Declaring state, and why updates are queued rather than applied immediately." },
+    { "slug": "react-useeffect", "name": "useEffect", "tier": 2, "description": "Synchronizing with something outside React — not a lifecycle callback." },
+    { "slug": "react-controlled-inputs", "name": "Controlled inputs", "tier": 2, "description": "Form values driven by state, with React as the single source of truth." },
+    { "slug": "react-lifting-state", "name": "Lifting state up", "tier": 2, "description": "Moving shared state to the nearest common ancestor instead of syncing two copies." },
+
+    { "slug": "react-render-model", "name": "Render and commit model", "tier": 3, "description": "Render is a pure computation; commit applies the diff. Confusing the two explains most surprising bugs." },
+    { "slug": "react-useeffect-deps", "name": "useEffect dependencies", "tier": 3, "description": "The dependency array is a correctness contract, not a performance knob." },
+    { "slug": "react-useeffect-cleanup", "name": "useEffect cleanup", "tier": 3, "description": "Returning a teardown to cancel subscriptions and in-flight work before the next effect run." },
+    { "slug": "react-context", "name": "Context", "tier": 3, "description": "Passing values past intermediate components — and the re-render cost of doing it carelessly." },
+    { "slug": "react-memoization", "name": "useMemo and useCallback", "tier": 3, "description": "Stabilizing values and identities; usually a fix for referential equality, not for slow code." },
+
+    { "slug": "react-stale-closure", "name": "Stale closures", "tier": 4, "description": "A callback capturing an old render's variables — the classic source of 'my state is one step behind'." },
+    { "slug": "react-reconciliation", "name": "Reconciliation", "tier": 4, "description": "How React decides to update, move or remount a node, and how component identity is determined." },
+    { "slug": "react-race-conditions", "name": "Async race conditions", "tier": 4, "description": "Out-of-order responses overwriting newer data, and why cleanup or an abort signal is the fix." }
+  ],
+  "edges": [
+    { "from": "react-component", "to": "react-jsx", "relation": "prerequisite_of" },
+    { "from": "react-component", "to": "react-props", "relation": "prerequisite_of" },
+    { "from": "react-props", "to": "react-state", "relation": "prerequisite_of" },
+    { "from": "react-state", "to": "react-usestate", "relation": "prerequisite_of" },
+    { "from": "react-hooks-rules", "to": "react-usestate", "relation": "prerequisite_of" },
+    { "from": "react-hooks-rules", "to": "react-useeffect", "relation": "prerequisite_of" },
+    { "from": "react-usestate", "to": "react-controlled-inputs", "relation": "prerequisite_of" },
+    { "from": "react-state", "to": "react-lifting-state", "relation": "prerequisite_of" },
+    { "from": "react-lifting-state", "to": "react-context", "relation": "prerequisite_of" },
+    { "from": "react-useeffect", "to": "react-useeffect-deps", "relation": "prerequisite_of" },
+    { "from": "react-useeffect", "to": "react-useeffect-cleanup", "relation": "prerequisite_of" },
+    { "from": "react-useeffect-cleanup", "to": "react-race-conditions", "relation": "prerequisite_of" },
+    { "from": "react-state", "to": "react-render-model", "relation": "prerequisite_of" },
+    { "from": "react-render-model", "to": "react-memoization", "relation": "prerequisite_of" },
+    { "from": "react-render-model", "to": "react-reconciliation", "relation": "prerequisite_of" },
+    { "from": "react-lists-keys", "to": "react-reconciliation", "relation": "prerequisite_of" },
+    { "from": "react-useeffect-deps", "to": "react-stale-closure", "relation": "prerequisite_of" },
+    { "from": "react-memoization", "to": "react-stale-closure", "relation": "related_to" }
+  ]
+}

package/dist/seed/web-auth.json

@@ -0,0 +1,78 @@
+{
+  "domain": "web-auth",
+  "concepts": [
+    { "slug": "http-statelessness", "name": "HTTP statelessness", "tier": 1, "description": "HTTP carries no memory between requests; every auth mechanism exists to re-establish identity on each one." },
+    { "slug": "http-cookies", "name": "Cookies", "tier": 1, "description": "Key-value pairs the browser stores per origin and replays automatically on matching requests." },
+    { "slug": "cookie-attributes", "name": "Cookie attributes", "tier": 1, "description": "Domain, Path, Expires/Max-Age, Secure, HttpOnly and SameSite — each narrows when the browser will send the cookie." },
+    { "slug": "password-hashing", "name": "Password hashing", "tier": 1, "description": "Storing a slow salted hash (bcrypt/argon2) rather than the password, so a database leak is not an account leak." },
+    { "slug": "https-tls", "name": "HTTPS and TLS", "tier": 1, "description": "Transport encryption; without it every credential and token is readable in transit." },
+    { "slug": "base64url-encoding", "name": "base64url encoding", "tier": 1, "description": "URL-safe encoding used by JWT segments — encoding, not encryption, and trivially reversible." },
+    { "slug": "auth-vs-authz", "name": "Authentication vs authorization", "tier": 1, "description": "Who you are versus what you may do; conflating them is a common source of privilege bugs." },
+
+    { "slug": "session-auth", "name": "Server-side sessions", "tier": 2, "description": "Server stores session state, the client holds only an opaque session id in a cookie." },
+    { "slug": "token-auth", "name": "Token-based auth", "tier": 2, "description": "The client holds a self-describing credential the server validates without a session store lookup." },
+    { "slug": "jwt-structure", "name": "JWT structure", "tier": 2, "description": "header.payload.signature — three base64url segments, the first two readable by anyone." },
+    { "slug": "jwt-signing", "name": "JWT signing", "tier": 2, "description": "HMAC or asymmetric signature proving the token was issued by someone holding the key." },
+    { "slug": "bearer-scheme", "name": "Bearer token scheme", "tier": 2, "description": "Authorization: Bearer <token> — possession alone is authority, which is exactly the risk." },
+    { "slug": "httponly-cookies", "name": "HttpOnly cookies", "tier": 2, "description": "Marks a cookie unreadable from JavaScript, removing the easiest XSS token-theft path." },
+    { "slug": "secure-cookie-flag", "name": "Secure cookie flag", "tier": 2, "description": "Restricts a cookie to HTTPS connections so it never crosses the wire in cleartext." },
+    { "slug": "samesite-cookies", "name": "SameSite cookies", "tier": 2, "description": "Lax/Strict/None controls whether the browser attaches a cookie to cross-site requests — the main structural CSRF defence." },
+    { "slug": "access-token", "name": "Access tokens", "tier": 2, "description": "Short-lived credential presented on each API call; short life is what limits the blast radius of theft." },
+    { "slug": "refresh-token", "name": "Refresh tokens", "tier": 2, "description": "Long-lived credential exchanged for new access tokens, so the powerful credential is used rarely." },
+    { "slug": "cors-basics", "name": "CORS basics", "tier": 2, "description": "Browser-enforced rules for cross-origin requests, including whether credentials may be attached." },
+    { "slug": "auth-middleware", "name": "Auth middleware", "tier": 2, "description": "The request-pipeline stage that verifies the credential and attaches the identity to the request." },
+
+    { "slug": "session-vs-token-tradeoffs", "name": "Sessions vs tokens: tradeoffs", "tier": 3, "description": "Revocability and server state versus statelessness and horizontal scale — there is no free option." },
+    { "slug": "jwt-expiry-claims", "name": "JWT expiry and claims", "tier": 3, "description": "exp, iat, nbf, aud, iss — validating all of them, not just the signature." },
+    { "slug": "token-storage-tradeoffs", "name": "Token storage tradeoffs", "tier": 3, "description": "localStorage, memory, or httpOnly cookie — each trades an XSS exposure against a CSRF exposure." },
+    { "slug": "csrf", "name": "CSRF", "tier": 3, "description": "Forcing a browser to make an authenticated request it did not intend, exploiting automatic cookie attachment." },
+    { "slug": "xss-token-theft", "name": "XSS token theft", "tier": 3, "description": "Injected script reading any credential the JavaScript context can reach." },
+    { "slug": "middleware-order-auth", "name": "Auth middleware ordering", "tier": 3, "description": "Body parsing, CORS, auth and route handlers must run in an order that never leaves a route unprotected." },
+    { "slug": "refresh-token-rotation", "name": "Refresh token rotation", "tier": 3, "description": "Issuing a new refresh token on every use so a stolen one becomes detectable and short-lived." },
+    { "slug": "rbac", "name": "Role-based access control", "tier": 3, "description": "Authorization decided by role assignments rather than per-user checks scattered through handlers." },
+    { "slug": "oauth2-authorization-code", "name": "OAuth2 authorization code flow", "tier": 3, "description": "Delegated authorization via a redirect and a back-channel code exchange." },
+
+    { "slug": "pkce", "name": "PKCE", "tier": 4, "description": "Proof Key for Code Exchange — binds the code exchange to the client that started the flow, defeating code interception." },
+    { "slug": "jwt-revocation", "name": "JWT revocation", "tier": 4, "description": "The core weakness of stateless tokens: you cannot un-issue one without reintroducing server state." },
+    { "slug": "session-fixation", "name": "Session fixation", "tier": 4, "description": "Attacker pre-sets a session id and waits for the victim to authenticate into it; regenerate on login." },
+    { "slug": "token-replay-detection", "name": "Token replay detection", "tier": 4, "description": "Detecting reuse of a rotated refresh token as a theft signal, and killing the whole token family." },
+
+    { "slug": "key-rotation-jwks", "name": "Signing key rotation and JWKS", "tier": 5, "description": "Publishing and rotating signing keys with `kid` so verification survives a key change without downtime." }
+  ],
+  "edges": [
+    { "from": "http-statelessness", "to": "session-auth", "relation": "prerequisite_of" },
+    { "from": "http-statelessness", "to": "token-auth", "relation": "prerequisite_of" },
+    { "from": "http-cookies", "to": "cookie-attributes", "relation": "prerequisite_of" },
+    { "from": "http-cookies", "to": "session-auth", "relation": "prerequisite_of" },
+    { "from": "cookie-attributes", "to": "httponly-cookies", "relation": "prerequisite_of" },
+    { "from": "cookie-attributes", "to": "secure-cookie-flag", "relation": "prerequisite_of" },
+    { "from": "cookie-attributes", "to": "samesite-cookies", "relation": "prerequisite_of" },
+    { "from": "https-tls", "to": "secure-cookie-flag", "relation": "prerequisite_of" },
+    { "from": "base64url-encoding", "to": "jwt-structure", "relation": "prerequisite_of" },
+    { "from": "jwt-structure", "to": "jwt-signing", "relation": "prerequisite_of" },
+    { "from": "jwt-structure", "to": "jwt-expiry-claims", "relation": "prerequisite_of" },
+    { "from": "token-auth", "to": "jwt-structure", "relation": "prerequisite_of" },
+    { "from": "token-auth", "to": "access-token", "relation": "prerequisite_of" },
+    { "from": "access-token", "to": "refresh-token", "relation": "prerequisite_of" },
+    { "from": "token-auth", "to": "bearer-scheme", "relation": "prerequisite_of" },
+    { "from": "auth-vs-authz", "to": "rbac", "relation": "prerequisite_of" },
+    { "from": "session-auth", "to": "session-vs-token-tradeoffs", "relation": "prerequisite_of" },
+    { "from": "token-auth", "to": "session-vs-token-tradeoffs", "relation": "prerequisite_of" },
+    { "from": "samesite-cookies", "to": "csrf", "relation": "prerequisite_of" },
+    { "from": "httponly-cookies", "to": "xss-token-theft", "relation": "prerequisite_of" },
+    { "from": "xss-token-theft", "to": "token-storage-tradeoffs", "relation": "prerequisite_of" },
+    { "from": "csrf", "to": "token-storage-tradeoffs", "relation": "prerequisite_of" },
+    { "from": "auth-middleware", "to": "middleware-order-auth", "relation": "prerequisite_of" },
+    { "from": "refresh-token", "to": "refresh-token-rotation", "relation": "prerequisite_of" },
+    { "from": "refresh-token-rotation", "to": "token-replay-detection", "relation": "prerequisite_of" },
+    { "from": "jwt-expiry-claims", "to": "jwt-revocation", "relation": "prerequisite_of" },
+    { "from": "session-vs-token-tradeoffs", "to": "jwt-revocation", "relation": "prerequisite_of" },
+    { "from": "session-auth", "to": "session-fixation", "relation": "prerequisite_of" },
+    { "from": "oauth2-authorization-code", "to": "pkce", "relation": "prerequisite_of" },
+    { "from": "token-auth", "to": "oauth2-authorization-code", "relation": "prerequisite_of" },
+    { "from": "jwt-signing", "to": "key-rotation-jwks", "relation": "prerequisite_of" },
+    { "from": "password-hashing", "to": "session-auth", "relation": "related_to" },
+    { "from": "cors-basics", "to": "csrf", "relation": "related_to" },
+    { "from": "auth-middleware", "to": "rbac", "relation": "related_to" }
+  ]
+}

package/dist/seed.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { seedDir } from './paths.js';
+import { isValidSlug } from './slug.js';
+/**
+ * Bump when seed content changes so existing installs pick up the new graphs on
+ * next start. Seeding is idempotent, so re-running is always safe.
+ */
+export const SEED_VERSION = 1;
+const SEED_VERSION_KEY = 'seed_version';
+export const RELATIONS = ['prerequisite_of', 'related_to', 'part_of'];
+function validateGraph(graph, file) {
+    if (!graph.domain)
+        throw new Error(`${file}: missing "domain"`);
+    if (!Array.isArray(graph.concepts) || graph.concepts.length === 0) {
+        throw new Error(`${file}: "concepts" must be a non-empty array`);
+    }
+    const slugs = new Set();
+    for (const c of graph.concepts) {
+        if (!isValidSlug(c.slug))
+            throw new Error(`${file}: invalid slug "${c.slug}"`);
+        if (slugs.has(c.slug))
+            throw new Error(`${file}: duplicate slug "${c.slug}"`);
+        if (!c.name)
+            throw new Error(`${file}: concept "${c.slug}" missing name`);
+        if (!Number.isInteger(c.tier) || c.tier < 1 || c.tier > 5) {
+            throw new Error(`${file}: concept "${c.slug}" has tier ${c.tier}, expected 1..5`);
+        }
+        slugs.add(c.slug);
+    }
+    for (const e of graph.edges ?? []) {
+        if (!RELATIONS.includes(e.relation)) {
+            throw new Error(`${file}: unknown relation "${e.relation}"`);
+        }
+        // Edges may only point within the same seed file: cross-domain links are the
+        // LLM's job via upsert_concepts, and this keeps each file independently valid.
+        if (!slugs.has(e.from))
+            throw new Error(`${file}: edge from unknown slug "${e.from}"`);
+        if (!slugs.has(e.to))
+            throw new Error(`${file}: edge to unknown slug "${e.to}"`);
+        if (e.from === e.to)
+            throw new Error(`${file}: self-edge on "${e.from}"`);
+    }
+}
+export function loadSeedGraphs(dir = seedDir()) {
+    return fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .sort()
+        .map((file) => {
+        const graph = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+        validateGraph(graph, file);
+        return graph;
+    });
+}
+/**
+ * Upserts a graph by slug. Mastery rows are never touched — a learner's history
+ * survives any number of seed updates.
+ */
+export function applySeedGraph(db, graph) {
+    const upsertConcept = db.prepare(`INSERT INTO concepts (slug, name, domain, description, tier, source)
+     VALUES (@slug, @name, @domain, @description, @tier, 'seed')
+     ON CONFLICT(slug) DO UPDATE SET
+       name        = excluded.name,
+       domain      = excluded.domain,
+       description = excluded.description,
+       tier        = excluded.tier,
+       source      = 'seed'`);
+    const idOf = db.prepare('SELECT id FROM concepts WHERE slug = ?');
+    const insertEdge = db.prepare(`INSERT OR IGNORE INTO edges (from_concept, to_concept, relation) VALUES (?, ?, ?)`);
+    let edges = 0;
+    db.transaction(() => {
+        for (const c of graph.concepts) {
+            upsertConcept.run({
+                slug: c.slug,
+                name: c.name,
+                domain: c.domain ?? graph.domain,
+                description: c.description ?? null,
+                tier: c.tier,
+            });
+        }
+        for (const e of graph.edges ?? []) {
+            const from = idOf.get(e.from);
+            const to = idOf.get(e.to);
+            if (!from || !to)
+                continue;
+            insertEdge.run(from.id, to.id, e.relation);
+            edges += 1;
+        }
+    })();
+    return { concepts: graph.concepts.length, edges, domains: [graph.domain] };
+}
+export function seedAll(db, dir = seedDir()) {
+    const summary = { concepts: 0, edges: 0, domains: [] };
+    for (const graph of loadSeedGraphs(dir)) {
+        const s = applySeedGraph(db, graph);
+        summary.concepts += s.concepts;
+        summary.edges += s.edges;
+        summary.domains.push(graph.domain);
+    }
+    db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(SEED_VERSION_KEY, String(SEED_VERSION));
+    return summary;
+}
+/** Seeds on first run, and again whenever SEED_VERSION moves. */
+export function seedIfNeeded(db, dir = seedDir()) {
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(SEED_VERSION_KEY);
+    if (row && Number(row.value) === SEED_VERSION)
+        return null;
+    return seedAll(db, dir);
+}
+//# sourceMappingURL=seed.js.map

package/dist/seed.js.map

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

package/dist/server.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { openDb } from './db.js';
+import { dbPath } from './paths.js';
+import { registerTools } from './tools/index.js';
+// stdout is the MCP transport. Anything diagnostic goes to stderr or it corrupts
+// the protocol stream.
+function log(message) {
+    process.stderr.write(`[eklavya-mcp] ${message}\n`);
+}
+async function main() {
+    const db = openDb();
+    log(`db ready at ${dbPath()}`);
+    const server = new McpServer({ name: 'eklavya', version: '0.1.0' }, {
+        capabilities: { tools: {} },
+        instructions: 'Eklavya tracks what this developer has actually learned. Log the concepts your work touches, ' +
+            'and quiz from the learner profile rather than from scratch — never ask about a concept already mastered.',
+    });
+    registerTools(server, db);
+    const shutdown = () => {
+        try {
+            db.close();
+        }
+        catch {
+            // closing a already-closed handle on shutdown is not worth reporting
+        }
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await server.connect(new StdioServerTransport());
+    log('server connected over stdio');
+}
+main().catch((err) => {
+    log(`fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,iFAAiF;AACjF,uBAAuB;AACvB,SAAS,GAAG,CAAC,OAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,OAAO,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IACpB,GAAG,CAAC,eAAe,MAAM,EAAE,EAAE,CAAC,CAAC;IAE/B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,EACrC;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,YAAY,EACV,+FAA+F;YAC/F,0GAA0G;KAC7G,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAE1B,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,CAAC;YACH,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,qEAAqE;QACvE,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAEhC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,GAAG,CAAC,6BAA6B,CAAC,CAAC;AACrC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,GAAG,CAAC,UAAU,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/session.js

@@ -0,0 +1,24 @@
+const CURRENT_SESSION_KEY = 'current_session';
+export const FALLBACK_SESSION_ID = 'default';
+export function getCurrentSession(db) {
+    const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(CURRENT_SESSION_KEY);
+    return row?.value ?? null;
+}
+export function setCurrentSession(db, sessionId) {
+    db.prepare(`INSERT INTO meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(CURRENT_SESSION_KEY, sessionId);
+}
+/**
+ * The model cannot see its own Claude Code session id, but the Phase 2 hooks
+ * receive the real one on stdin — so both sides have to agree on a resolution
+ * order or the hooks query rows that were written under a different key
+ * (phase-1 decision G1).
+ */
+export function resolveSessionId(db, explicit) {
+    const candidate = (explicit && explicit.trim()) ||
+        (process.env.EKLAVYA_SESSION_ID && process.env.EKLAVYA_SESSION_ID.trim()) ||
+        getCurrentSession(db) ||
+        FALLBACK_SESSION_ID;
+    return candidate;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAEA,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAC9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE7C,MAAM,UAAU,iBAAiB,CAAC,EAAM;IACtC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAEzE,CAAC;IACd,OAAO,GAAG,EAAE,KAAK,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAM,EAAE,SAAiB;IACzD,EAAE,CAAC,OAAO,CACR;2DACuD,CACxD,CAAC,GAAG,CAAC,mBAAmB,EAAE,SAAS,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAM,EAAE,QAAwB;IAC/D,MAAM,SAAS,GACb,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7B,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACzE,iBAAiB,CAAC,EAAE,CAAC;QACrB,mBAAmB,CAAC;IAEtB,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/slug.js

@@ -0,0 +1,75 @@
+/**
+ * Concept slugs are the join key across the whole system, and the LLM is allowed
+ * to mint new ones (PRD §8 tool 6). Normalizing hard here is what keeps slug
+ * sprawl from turning the graph into mush (PRD §15).
+ */
+export function normalizeSlug(input) {
+    return input
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .replace(/-{2,}/g, '-')
+        .slice(0, 80);
+}
+export function isValidSlug(slug) {
+    return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug) && slug.length <= 80;
+}
+/**
+ * Token-set similarity between two slugs.
+ */
+export function tokenJaccard(a, b) {
+    const ta = new Set(a.split('-').filter(Boolean));
+    const tb = new Set(b.split('-').filter(Boolean));
+    if (ta.size === 0 || tb.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            intersection += 1;
+    const union = ta.size + tb.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Words that add no meaning to a concept name. Stripping these is what lets
+ * `jwt-structure-basics` find `jwt-structure` without also merging
+ * `refresh-token-rotation` into `refresh-token` — both pairs look identical to a
+ * similarity score, but only one of them is the same idea twice.
+ */
+const QUALIFIER_TOKENS = new Set([
+    'basic', 'basics', 'fundamental', 'fundamentals', 'intro', 'introduction',
+    'overview', 'explained', 'explainer', 'concept', 'concepts', 'general',
+    'generic', 'guide', 'tutorial', 'usage', 'primer', '101',
+    'strategy', 'strategies', 'approach', 'approaches',
+]);
+export function stripQualifiers(slug) {
+    const tokens = slug.split('-').filter(Boolean);
+    while (tokens.length > 1 && QUALIFIER_TOKENS.has(tokens[tokens.length - 1]))
+        tokens.pop();
+    while (tokens.length > 1 && QUALIFIER_TOKENS.has(tokens[0]))
+        tokens.shift();
+    return tokens.join('-');
+}
+/**
+ * Deliberately strict: 1.0 only catches a pure token reordering
+ * (`structure-jwt` ~ `jwt-structure`). Everything else has to survive the
+ * qualifier strip above. A test asserts no two shipped seed concepts match.
+ */
+export const FUZZY_MATCH_THRESHOLD = 0.8;
+export function findFuzzyMatch(slug, candidates, threshold = FUZZY_MATCH_THRESHOLD) {
+    const stripped = stripQualifiers(slug);
+    const sameOnceQualifiersGo = candidates.find((c) => stripQualifiers(c.slug) === stripped);
+    if (sameOnceQualifiersGo)
+        return sameOnceQualifiersGo;
+    let best;
+    let bestScore = 0;
+    for (const candidate of candidates) {
+        const score = tokenJaccard(stripped, stripQualifiers(candidate.slug));
+        if (score > bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return bestScore >= threshold ? best : undefined;
+}
+//# sourceMappingURL=slug.js.map

package/dist/slug.js.map

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