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

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.

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. CI also enforces 100% coverage across the whole suite; shards passing is not enough. See .claude/rules/coverage.md for how to measure it before pushing.
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):

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.