git:20261017.8e6c628 to git:20261020.e6f9c96

# Working on Eklavya

Eklavya teaches the concepts behind agent-written code and keeps local project

memory. This is the contributor contract for agents working in this repository.

Read the nearest nested `CLAUDE.md` before editing `mcp/`, `hooks/`, `cli/`,

`skills/` or `web/`.

## Repository map

| Path | Responsibility |

|---|---|

| `mcp/src/` | MCP tools, config, SQLite, scheduling, memory, dashboard and the `eklavya` CLI (`cli.ts`) |

| `mcp/src/hooks/` | Hook implementations and shared helpers; registration lives in `hooks/hooks.json` |

| `mcp/src/migrations/`, `mcp/test/` | Forward-only migrations and runtime tests |

| `hooks/run.mjs` | Cross-platform launcher and background repair of an older runtime |

| `hooks/panel/` | The quiz side panel: a Claude Code mod (not a command hook), its state contract and its tests; enabled by default, controlled through `quiz.panel` |

| `skills/` | Slash commands and the tutor entry point with on-demand references |

| `user-skill/` | Chat and artifact skills installed to `~/.claude/skills/`; never move them into `skills/` or they register twice |

| `agents/` | Tutor and background explainer |

| `cli/`, `scripts/` | POSIX git gate, its installer, release version bump |

| `web/` | Landing page and user manual; Astro build deployed to Firebase |

| `docs/` | Contributor references and generated runtime architecture |

| `eval/` | Question, extraction, history, retrieval and performance evaluation; dated results are historical evidence |

| `CONTRIBUTING.md` | Setup, verification, acceptance checks and releases |

| `.claude/skills/` | Repository design, dashboard and documentation-verification contracts |

## Documentation is part of every feature

A code change is complete only when the manual and a README change in the

same PR. There is no exemption. Change the landing page (`web/public/`) only

when explicitly asked to. `.github/scripts/check-docs-sync.sh`

fails the PR otherwise, and its header lists what counts as product code. When

the change alters no existing claim on a surface, make a small source-backed

copy or link update where its reader looks for the feature. Keep the home page

lean and put reference material in the manual. Run `/verify-docs` (`.claude/skills/verify-docs/`) before

opening the PR; it runs weekly on `main` as well.

Read the source before documenting names, defaults, limits, paths or output.

`mcp/src/config.ts` owns configuration; each other claim belongs to the module

that implements it. Existing prose and recalled memory are not evidence.

| Change | Documentation to review |

|---|---|

| Install, repair, updates, removal or host support | Manual `installing`, `installation-options`, `updates`, `troubleshooting`; root and package README |

| Dials, defaults, scopes or config keys | Manual `dials`, `configuration`, `installing`, `faq`, `memory`, `migrating`; affected command skills; landing introduction and docs links; demo status; the dashboard Settings registry in `mcp/src/dashboard.ts` |

| Slash commands, CLI or MCP tools | Manual `commands`, `cli`, `memory`; `mcp/README.md`; relevant skills |

| Hook timing, question planning or grading | Manual `first-session`, `how-it-works`, `grading-engine`, `levels-and-tiers`; hook and tutor guidance |

| Commit gating | Manual `commit-gate`; `cli/CLAUDE.md`; setup skill and contributor acceptance checks |

| Memory, providers, privacy or storage | Manual `memory`, `your-data`, `migrating`, `configuration`, `faq` |

| Usage ping fields, counters or website analytics | Manual `usage-analytics`, `your-data`, `faq`; `user-skill/eklavya/SKILL.md` |

| Packs, seeds or concept graph | Manual `packs`; command reference and relevant skills; recount any published totals |

| Dashboard or explainer pages | Manual `dashboard`, `commands`, `configuration`; artifact skill and explainer agent |

| Delegation or host hook contracts | `docs/parallel-tutoring.md`, `docs/subagent-policy.md`, `docs/verified-schemas.md` |

`web/CLAUDE.md` maps every manual page to its exact sources. Add its row and a

sidebar entry whenever adding a page. Update affected diagrams in the same PR;

their labels and branches are claims about the code too.

Keep the README a short introduction and install link. Put ordered tasks in

guides, complete fields and flags in references, and implementation detail in

contributor docs. Use descriptive headings, concrete examples and short sections.

A diagram should clarify sequence or responsibility, have a text explanation,

work on a narrow screen and remain readable in both themes. Document shipped,

verified capabilities. Do not advertise unshipped work: a feature stays out of

`web/` until the code exists and ships. Do not imply that a standalone MCP client has Claude

Code's hook-driven learning loop.

## Required checks

1. Run the checks appropriate to the change in `CONTRIBUTING.md`. Isolate tests

from real learner state with temporary paths or explicit config: in-process

tests that call `loadConfig()` read the real `~/.eklavya/config.json`, so they

pass locally and fail in CI. Pin the config or point `EKLAVYA_HOME` at a temp

directory before calling a test green.

2. Build `web/` when docs or site content changes. Its SEO audit checks built

links, anchors and assets; inspect changed layouts at 1280, 900 and 560px in

both themes.

3. Verify commands, config examples and output against their implementation.

Search for renamed terms across the full repository, excluding dated results.

4. Fill `.github/PULL_REQUEST_TEMPLATE.md`. Behavior changes require the live

acceptance transcript; tutor changes also require before/after eval evidence.

5. Report any check not run or claim not verified. Never describe a planned

check as completed.

## Tests and CI shards

CI runs `mcp/test/` in five shards, and `.github/scripts/test-shards.json` says

which shard runs each file. Adding, renaming or deleting a `*.test.ts` file

also means updating that manifest in the same PR; an unlisted file fails CI.

`mcp/test/CLAUDE.md` and `.claude/rules/test-shards.md` give the steps.

## Runtime and design invariants

- Hooks fail open and exit 0 on every failure path. They must also have bounded

stdin reads and avoid waiting for inference.

- Configuration has two interfaces, the CLI (`eklavya config`) and the

dashboard's Settings workflow, at user and project scope. Both write through

one shared function; a config key, scope rule or validation change lands in

both in the same PR. A new key goes in the Settings registry or its explicit

CLI-only list, or `dashboard.test.ts` fails.

- Memory and quizzes have independent switches. Memory evidence cannot change

mastery; only an assessed answer can.

- Migrations are forward-only; update the schema expectations in

`mcp/test/migrate.test.ts` with each migration.

- Never commit learner databases or anything from `~/.eklavya/`.

- Conventional commits drive releases: `feat:` and `fix:` release; `docs:` and

`chore:` do not. Keep package/plugin versions aligned through release tooling.

- Before editing the site, read `.claude/skills/eklavya-design/SKILL.md`; before

editing the dashboard, also read `.claude/skills/eklavya-dashboard/SKILL.md`.

Use semantic color roles from `web/public/tokens.css`, keyboard-operable

controls and shareable dashboard filters. Keep the home page lean, with the

Archer Cloak mascot on a dark hero and the launch film (a native video, no autoplay) at `/#demo`.

Keep the compact `#legend` section with "The name", "The archer who taught

himself" and the bow, arrow and target artwork. Its decorative animation runs

once when the scene enters view and stays static under reduced motion.

Keep the GitHub star box visible and its

count accurate. `/demo/` is a legacy redirect to the home demo.

## Generated runtime diagram

Edit `docs/eklavya-runtime.architecture.json`, never the generated HTML. Set

`meta.repository.revision` to the commit whose code supplied the evidence, then

run the installed archify skill (adjust the skill path if installed elsewhere):

```bash

cd ~/.claude/skills/archify

node bin/archify.mjs deliver architecture <repo>/docs/eklavya-runtime.architecture.json \

<repo>/docs/eklavya-runtime.html --quality showcase --repo-root <repo> --json

node bin/archify.mjs visual-check <repo>/docs/eklavya-runtime.html --json

```

Require all delivery checks with no errors/warnings and every visual viewport

passing. Remove generated PNG/JSON inspection sidecars; they are evidence, not

deliverables. The website copies this artifact during its build. Generated

ignored files such as that copy get `talea-regenerable` in the root

`.gitattributes`, so worktree cleanup can remove them. Small manual

flows use `DocFlow.astro`; they do not require regenerating the architecture.

## Communicating with the maintainer

These preferences apply to chat, not to documents or code comments.

- Lead with the answer in plain English. Group topics under headings, use short

bullets, keep each topic within ten lines, and omit investigation narration.

- Close with `What I need from you:` followed by actions or `Nothing`. Name

unfinished work and skipped checks explicitly.

- Explain what something does before its implementation. Use a concrete example

for abstract ideas; keep gotchas visible. Corrections are one line, first.

- When presenting options, recommend one and give its reason and cost. If a

short-term patch differs from the proper fix, explain both, recommend today's

action, and say whether the remaining work needs an issue.

- Make each decision understandable in place. Do not use issue numbers or

references to earlier options as substitutes for explaining the fact.

- For bug explanations before implementation: issue, solution, user impact,

concrete example, changes needed, recommendation. Once agreed, implement.

Verify before concluding: inspect the specific population, use a measurement

window long enough for the behavior, read callers before claiming a guard is

missing, and inspect the whole diff. A sample cannot prove absence. Check whether

a defect is your own uncommitted change. Falsify your explanation where possible;

if evidence is incomplete, say what would settle it.