shikhu 0.1.0__tar.gz

shikhu-0.1.0/.claude/skills/study/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: study
+description: Tutor the user through a source file with a cached summary, a guided walkthrough, and free-form Q&A — then persist a review record so future quizzes know what was covered.
+argument-hint: "[file-path]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash(uv run shikhu *)
+  - Bash(ls *)
+  - Bash(git ls-files *)
+---
+
+# /study — guided file review before a quiz
+
+## About shikhu
+
+Shikhu is a knowledge-coverage CLI that tracks how well a user understands *their own* codebase. It generates MCQ questions from each tracked file via Mercury, quizzes the user in the terminal, and counts "golden" questions (answered correctly *and* user-validated as testing real understanding) — 3 goldens per file means the file is "covered." `shikhu` is the entry point (`src/shikhu/cli.py`); commands live in `src/shikhu/commands/`.
+
+The flow is **code → study → quiz**. `/study` is the *learn* step: you build the user's mental model of one file before they quiz on it, and every conceptual question they ask gets logged to `review_questions` so `shikhu generate-from-study <file>` can later seed quiz Qs that test those same concepts.
+
+## Your role
+
+You are the user's study partner. Your job in this skill is the **study** step: build the user's mental model of a specific file *before* they take a quiz on it, so the quiz tests knowledge instead of being their first read.
+
+## 1. Resolve the target file
+
+The argument is `$ARGUMENTS`. Treat it as the path to study.
+
+- If no argument is provided, tell the user `Usage: /study <file-path>` and stop. (Auto-recommendation is a follow-up ship, not in scope here.)
+- Verify the file exists with `Read` before proceeding. If it doesn't, stop and tell the user.
+- Check that the file is tracked by git:
+  ```bash
+  git ls-files --error-unmatch "$ARGUMENTS"
+  ```
+  If the command exits non-zero (file untracked), tell the user one line — *"Heads up: `$ARGUMENTS` isn't tracked by git, so `shikhu refresh` and `shikhu coverage` won't see it until you `git add` it. /study still works."* — then continue. Don't stop.
+
+## 2. Load context (small, deliberate footprint)
+
+Do these in parallel where possible:
+
+1. **Read the target file** with the `Read` tool — you'll walk through it.
+2. **Read `CLAUDE.md`** for project conventions.
+3. **Load cached summary + prior reviews** in one call:
+   ```bash
+   uv run shikhu study-context "$ARGUMENTS"
+   ```
+   If the output says `No cached summary`, tell the user one line — *"No cached summary yet, generating one now (~30s)…"* — then run:
+   ```bash
+   uv run shikhu summarize --file "$ARGUMENTS"
+   uv run shikhu study-context "$ARGUMENTS"
+   ```
+   The second call now returns the freshly cached summary; proceed with that.
+
+   If there are prior reviews, skim their `agent_summary` lines so you don't repeat ground already covered.
+
+## 3. Start the review (get a review_id you'll close later)
+
+```bash
+uv run shikhu log-review "$ARGUMENTS" --start
+```
+
+Capture the stdout integer — that's the `review_id`. You'll need it for every `log-study-question` call and to close the review at the end.
+
+## 4. Present the summary
+
+Show the cached summary verbatim to the user, framed as "here's the 30-second overview before we dig in." Then ask:
+> *"Want to walk through it section-by-section, or do you have specific questions already?"*
+
+## 5. Walk the file
+
+Default path: walk the file top-down, one logical section at a time (a function, a class, a config block — let the code's structure guide you, not line counts).
+
+For each section:
+- **Reference it** with `file_path:line_number` so the user can navigate to it in their editor.
+- **Explain what it does** in 2-3 sentences, leaning on what's in the summary and the code itself.
+- **Ask one probe question** — not a quiz question, a model-check question. E.g. *"What do you think happens if this is called with an empty list?"* or *"Why do you think this is cached instead of recomputed?"*
+- **Listen to their answer.** If they ask a question back, answer it — and log it:
+  ```bash
+  uv run shikhu log-study-question <review_id> "<their question, quoted>" --conceptual --answered
+  ```
+  Use `--not-conceptual` for mechanical/syntax questions, `--unanswered` if you couldn't give a good answer.
+
+If the user steers — "skip to X", "I want to understand Y" — follow their lead. The file walk is a default, not a script.
+
+## 6. Close the loop
+
+When the user signals they're done (they say so, or the walk is complete):
+
+1. **Write a short agent summary** (3-5 sentences): what sections you covered, what the user seemed to grasp well, what was shaky, what they should revisit. This is the durable record that survives even if transcripts move.
+2. **Resolve the Claude Code transcript path** for this session. Claude Code encodes the cwd by replacing `/`, `_`, and `.` with `-`:
+   ```bash
+   ls -t ~/.claude/projects/$(pwd | tr '/_.' '-')/*.jsonl 2>/dev/null | head -1
+   ```
+   (If this returns nothing, skip `--transcript`; the `agent_summary` alone is enough to keep the review record useful.)
+3. **Close the review** with both pieces:
+   ```bash
+   uv run shikhu log-review "$ARGUMENTS" --review-id <review_id> --summary "<your summary>" --transcript "<path or omit>"
+   ```
+
+## 7. Offer the quiz
+
+End with:
+> *"Ready to test it? Run `uv run shikhu quiz --file $ARGUMENTS` — or come back later and I'll have remembered what we covered."*
+
+Do **not** auto-launch the quiz. Quizzing is a separate intentional act.
+
+## Style
+
+- Concise. This is a tutoring session, not a lecture.
+- Cite `path:line` whenever you reference code so the user can jump there in their editor.
+- Never invent behavior the code doesn't show — if unsure, say so and read the relevant file.
+- If the user edits the file during the session, flag it: the summary and questions for this file will go stale and `shikhu refresh` will need to run.

shikhu-0.1.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+# Dependabot version updates. Security alerts are enabled separately at the
+# repo level (Settings → Security → Dependabot alerts).
+version: 2
+updates:
+  # Python dependencies (pyproject.toml + uv.lock). Use the `uv` ecosystem
+  # so Dependabot updates the lockfile too — the `pip` ecosystem doesn't
+  # touch uv.lock, which breaks our `uv lock --check` CI step.
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      python-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+  # GitHub Actions versions in .github/workflows/
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      actions-minor-patch:
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

shikhu-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Validate lockfile is in sync with pyproject.toml
+        run: uv lock --check
+
+      # Tests are deterministic (temp DBs, no network/API keys), so no secrets needed.
+      - name: Sync dependencies
+        run: uv sync --frozen
+
+      - name: Lint + format check (ruff)
+        run: |
+          uv run ruff check src tests
+          uv run ruff format --check src tests
+
+      - name: Type check (ty — advisory, non-blocking)
+        continue-on-error: true
+        run: uv run ty check src/
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --junitxml=junit.xml
+
+      - name: Publish test results
+        uses: EnricoMi/publish-unit-test-result-action@v2
+        if: always()
+        with:
+          files: junit.xml
+
+  smoke-install:
+    name: Packaging smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build wheel
+        run: uv build --wheel
+
+      - name: Install wheel into clean stdlib venv
+        run: |
+          python -m venv /tmp/shikhu-smoke
+          /tmp/shikhu-smoke/bin/pip install --upgrade pip --quiet
+          /tmp/shikhu-smoke/bin/pip install dist/shikhu-*.whl
+
+      - name: shikhu --help works post-install
+        run: /tmp/shikhu-smoke/bin/shikhu --help
+
+      - name: shikhu init creates DB + .quizignore in a fresh directory
+        run: |
+          mkdir /tmp/shikhu-smoke-test
+          cd /tmp/shikhu-smoke-test
+          /tmp/shikhu-smoke/bin/shikhu init
+          test -f coverage.db
+          test -f .quizignore

shikhu-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+# Cuts a GitHub Release + publishes to PyPI when a vX.Y.Z tag is pushed.
+# Builds the wheel + sdist, publishes to PyPI via Trusted Publishing (OIDC —
+# no API token stored), then attaches the artifacts to a GitHub Release.
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write   # required for gh release create
+  id-token: write   # required for PyPI Trusted Publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Tests must pass before releasing
+        run: |
+          uv sync --frozen
+          uv run pytest tests/ -q
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --generate-notes

shikhu-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+coverage.db
+.quizignore
+__pycache__/
+.venv/
+venv/
+dist/
+benchmark_dataset_*.json
+
+# vet skill installs (per-harness, local tooling — not project deliverables)
+.agents/
+.codex/
+.opencode/
+.claude/skills/vet/
+
+# local scratch / dogfooding artifacts
+trial_run.md
+workflows.html

shikhu-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

shikhu-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arjun Patel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shikhu-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: shikhu
+Version: 0.1.0
+Summary: Knowledge coverage for your codebase
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: anthropic>=0.84.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: requests>=2.34.2
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.26.2
+Provides-Extra: evals
+Requires-Dist: gliner2>=1.3.1; extra == 'evals'
+Provides-Extra: mcp
+Requires-Dist: fastmcp[apps]>=3.3.1; extra == 'mcp'
+Requires-Dist: mcp[cli]>=1.27.1; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Project Shikhu
+
+[![CI](https://github.com/arjunpatel7/shikhu/actions/workflows/ci.yml/badge.svg)](https://github.com/arjunpatel7/shikhu/actions/workflows/ci.yml)
+
+Project Shikhu helps you learn your codebases that you generate with AI.
+
+Use shikhu to study your codebase, track your understanding, and increase your understanding of your code. Shikhu does this by learning about your files, generating quizzes for you to take, and even by helping you study the code after you make it.
+
+Conceptual understanding is measured by **knowledge coverage** — the share of your codebase backed by *golden questions* (questions you answered correctly *and* confirmed actually test understanding of the file). Three goldens per file = fully covered.
+
+Think test coverage, but for your brain!
+
+## Getting Started
+
+Prerequisites:
+- An **Inception API key** (required). This gives you access to fast, text-diffusion models for question generation and summarization. You can get one for free at [Inception Labs](https://platform.inceptionlabs.ai/).
+- A **skill-compatible coding agent** like Claude Code, Codex, or Cursor (strongly recommended). The core loop — `refresh`, `quiz`, `coverage` — runs entirely in your terminal, but Shikhu really shines when paired with the `/study` skill (step 5): it turns "I don't get this file" into a guided walkthrough *and* feeds your weak spots back into future quizzes.
+
+### 1. Install
+
+**To use Shikhu on your own codebase** — install it as a standalone tool, then run it from inside any repo:
+
+```bash
+uv tool install git+https://github.com/arjunpatel7/shikhu.git
+```
+
+This puts `shikhu` on your `PATH` in an isolated environment (no clash with your project's dependencies). `cd` into any repo and the commands below just work — each repo gets its own `coverage.db`, `.quizignore`, and `.env`. (`pipx install git+…` or `pip install git+…` into a virtualenv work too.)
+
+Provide your Mercury API key via a `.env` file in the repo you're quizzing (auto-loaded), or export it in your shell:
+```
+INCEPTION_API_KEY=your-key-here
+```
+
+Get a key at [Inception Labs](https://www.inceptionlabs.ai/).
+
+
+### 2. Initialize
+
+```bash
+shikhu init
+```
+
+This creates a database and a `.quizignore` file (like `.gitignore` but for quiz generation). Add files to the latter to avoid getting quizzed on them, like config or docfiles.
+
+### 3. Generate questions
+
+Next, you're ready to batch some questions. Run the following command:
+
+```bash
+shikhu refresh
+```
+
+Shikhu scans your tracked files, checks for stale questions, and generates new ones using the Mercury API. Files matching `.quizignore` patterns are skipped.
+
+Under the hood, `refresh` runs two passes in parallel: **summaries** (a cached Mercury summary per file, used to seed question generation and to feed `/study`) and **questions** (one batch per file). Both skip files whose content hash and prompt version haven't changed, so re-running `refresh` after a small edit only regenerates the files that actually changed. If you only want to refresh summaries, run `shikhu summarize`; tune parallelism with `--summary-workers` (default 8).
+
+### 4. Take a quiz
+
+After working on your code base, it's time to take a quiz!
+
+(document any args here too)
+
+```bash
+shikhu quiz
+```
+
+You'll get multiple-choice questions about your code. After each answer you can rate the question quality — good questions that you answer correctly can become **golden questions**. These are eventually used as measures of knowledge coverage. You'll have **3 golden questions** per file, and passing all of them represents basic understanding of the file.
+
+`shikhu quiz` has a couple of flags worth knowing:
+- `--n <int>` — number of questions in the round (default 5)
+- `--file <path>` — quiz only on one file (handy after editing it)
+
+**What happens to old questions?** When you edit a file, Shikhu detects the change (via content hash) and marks that file's questions stale on the next `refresh`. Stale questions stick around in the database — nothing is deleted — and `refresh` generates a fresh batch on top.
+
+Golden questions get special treatment. If a file changes after you mastered it, those goldens are flagged for **re-validation**: they come up first in your next quiz so you can prove the change didn't break your understanding. Answer correctly and they go back to golden + fresh; answer wrong and they lose golden status (your coverage updates accordingly).
+
+### 5. Drill weak spots with `/study` (optional)
+
+When a quiz surfaces a file you don't really understand, use the project's `/study` skill (inside your agent) to walk through it. The skill loads a cached summary, takes you through the file, and **logs every conceptual question you ask** to the database.
+
+Then turn those questions into quiz questions that test the same concepts:
+
+```bash
+shikhu generate-from-study path/to/file.py
+shikhu quiz --file path/to/file.py
+```
+
+This reinforces exactly the gaps you surfaced during study — not generic file-level questions.
+
+### 6. Check your coverage
+
+Wanna know how well you know your codebase? Run this commmand
+
+```bash
+shikhu coverage
+```
+
+Shows which files you've mastered and which need work. Each file needs 3 golden questions to be fully covered.
+
+## All Commands
+
+| Command | What it does |
+|---------|-------------|
+| `shikhu init` | Set up database, check API keys, create `.quizignore` |
+| `shikhu quiz` | Take a quiz (default 5 questions) |
+| `shikhu quiz --n 10` | Quiz with 10 questions |
+| `shikhu quiz --file path.py` | Quiz on a single file |
+| `shikhu refresh` | Staleness check + regenerate stale questions and summaries |
+| `shikhu summarize` | Parallel Mercury summaries for every tracked file |
+| `shikhu summarize --file path.py` | Force-regenerate summary for one file |
+| `shikhu generate-from-study path.py` | Generate quiz Qs seeded by your prior `/study` questions for that file |
+| `shikhu coverage` | Print knowledge-coverage report |
+| `shikhu clean` | Delete the database (asks for confirmation) |
+| `shikhu clean --yes` | Delete without confirmation |
+
+
+## How It Works
+
+1. **Question generation** — Mercury (Inception Labs) reads your source files and generates conceptual multiple-choice questions about design decisions, architecture, and how things work.
+
+2. **Quizzing** — Answer questions in the terminal. Rate question quality. Correct answers on good questions become **golden** — validated proof you understand that file.
+
+3. **Coverage tracking** — Each file targets 3 golden questions. Coverage = how many files have reached that bar.
+
+4. **Staleness** — When code changes (detected via SHA-256 hashing), related questions are marked stale so your coverage stays honest.
+
+5. **Study-driven generation** — `/study` captures the conceptual questions you actually ask while learning a file. `shikhu generate-from-study` turns those into quiz questions, so the next quiz tests the gaps you surfaced — not just whatever Mercury picks from the file.
+
+## Golden Questions
+
+A golden question is one you:
+- Answered correctly
+- Rated as good quality
+- Confirmed it tests real understanding of the file
+
+3 golden questions per file = fully covered. Golden questions go stale when the underlying code changes, keeping coverage honest over time.
+
+## Privacy & Data
+
+Everything Shikhu knows lives in one local SQLite file, `coverage.db`, in the repo you run it from. Nothing is uploaded anywhere. Two things are worth knowing:
+
+- **File contents are sent to the Mercury API** (Inception Labs) to generate questions and summaries — that's the only data that leaves your machine, under your own API key. Use `.quizignore` to exclude anything you don't want sent.
+- **Shikhu reads your local Claude Code transcripts** for the current project (`~/.claude/projects/...`) to find conceptual questions you've asked, and stores them in `coverage.db` to seed better quiz questions. These prompts never leave your machine — but it's one more reason `coverage.db` must stay out of git. `shikhu init` adds it to your `.gitignore` automatically.
+
+## Configuration
+
+### `.quizignore`
+
+Controls which files are skipped during generation:
+```
+# Skip these
+*.lock
+.claude/
+tests/
+deprecated/
+```
+
+### Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `INCEPTION_API_KEY` | Yes | Mercury API for question generation |
+
+## Tech
+
+- Python 3.12+, managed with [uv](https://docs.astral.sh/uv/)
+- [Mercury](https://www.inceptionlabs.ai/) for question generation
+- [Typer](https://typer.tiangolo.com/) + [Rich](https://rich.readthedocs.io/) for the CLI
+- SQLite for local storage
+- SHA-256 file hashing for staleness detection
+
+## Love the repo and have some ideas?
+Feel free to open an issue! We aren't accepting PRs at this time.

shikhu-0.1.0/README.md

@@ -0,0 +1,173 @@
+# Project Shikhu
+
+[![CI](https://github.com/arjunpatel7/shikhu/actions/workflows/ci.yml/badge.svg)](https://github.com/arjunpatel7/shikhu/actions/workflows/ci.yml)
+
+Project Shikhu helps you learn your codebases that you generate with AI.
+
+Use shikhu to study your codebase, track your understanding, and increase your understanding of your code. Shikhu does this by learning about your files, generating quizzes for you to take, and even by helping you study the code after you make it.
+
+Conceptual understanding is measured by **knowledge coverage** — the share of your codebase backed by *golden questions* (questions you answered correctly *and* confirmed actually test understanding of the file). Three goldens per file = fully covered.
+
+Think test coverage, but for your brain!
+
+## Getting Started
+
+Prerequisites:
+- An **Inception API key** (required). This gives you access to fast, text-diffusion models for question generation and summarization. You can get one for free at [Inception Labs](https://platform.inceptionlabs.ai/).
+- A **skill-compatible coding agent** like Claude Code, Codex, or Cursor (strongly recommended). The core loop — `refresh`, `quiz`, `coverage` — runs entirely in your terminal, but Shikhu really shines when paired with the `/study` skill (step 5): it turns "I don't get this file" into a guided walkthrough *and* feeds your weak spots back into future quizzes.
+
+### 1. Install
+
+**To use Shikhu on your own codebase** — install it as a standalone tool, then run it from inside any repo:
+
+```bash
+uv tool install git+https://github.com/arjunpatel7/shikhu.git
+```
+
+This puts `shikhu` on your `PATH` in an isolated environment (no clash with your project's dependencies). `cd` into any repo and the commands below just work — each repo gets its own `coverage.db`, `.quizignore`, and `.env`. (`pipx install git+…` or `pip install git+…` into a virtualenv work too.)
+
+Provide your Mercury API key via a `.env` file in the repo you're quizzing (auto-loaded), or export it in your shell:
+```
+INCEPTION_API_KEY=your-key-here
+```
+
+Get a key at [Inception Labs](https://www.inceptionlabs.ai/).
+
+
+### 2. Initialize
+
+```bash
+shikhu init
+```
+
+This creates a database and a `.quizignore` file (like `.gitignore` but for quiz generation). Add files to the latter to avoid getting quizzed on them, like config or docfiles.
+
+### 3. Generate questions
+
+Next, you're ready to batch some questions. Run the following command:
+
+```bash
+shikhu refresh
+```
+
+Shikhu scans your tracked files, checks for stale questions, and generates new ones using the Mercury API. Files matching `.quizignore` patterns are skipped.
+
+Under the hood, `refresh` runs two passes in parallel: **summaries** (a cached Mercury summary per file, used to seed question generation and to feed `/study`) and **questions** (one batch per file). Both skip files whose content hash and prompt version haven't changed, so re-running `refresh` after a small edit only regenerates the files that actually changed. If you only want to refresh summaries, run `shikhu summarize`; tune parallelism with `--summary-workers` (default 8).
+
+### 4. Take a quiz
+
+After working on your code base, it's time to take a quiz!
+
+(document any args here too)
+
+```bash
+shikhu quiz
+```
+
+You'll get multiple-choice questions about your code. After each answer you can rate the question quality — good questions that you answer correctly can become **golden questions**. These are eventually used as measures of knowledge coverage. You'll have **3 golden questions** per file, and passing all of them represents basic understanding of the file.
+
+`shikhu quiz` has a couple of flags worth knowing:
+- `--n <int>` — number of questions in the round (default 5)
+- `--file <path>` — quiz only on one file (handy after editing it)
+
+**What happens to old questions?** When you edit a file, Shikhu detects the change (via content hash) and marks that file's questions stale on the next `refresh`. Stale questions stick around in the database — nothing is deleted — and `refresh` generates a fresh batch on top.
+
+Golden questions get special treatment. If a file changes after you mastered it, those goldens are flagged for **re-validation**: they come up first in your next quiz so you can prove the change didn't break your understanding. Answer correctly and they go back to golden + fresh; answer wrong and they lose golden status (your coverage updates accordingly).
+
+### 5. Drill weak spots with `/study` (optional)
+
+When a quiz surfaces a file you don't really understand, use the project's `/study` skill (inside your agent) to walk through it. The skill loads a cached summary, takes you through the file, and **logs every conceptual question you ask** to the database.
+
+Then turn those questions into quiz questions that test the same concepts:
+
+```bash
+shikhu generate-from-study path/to/file.py
+shikhu quiz --file path/to/file.py
+```
+
+This reinforces exactly the gaps you surfaced during study — not generic file-level questions.
+
+### 6. Check your coverage
+
+Wanna know how well you know your codebase? Run this commmand
+
+```bash
+shikhu coverage
+```
+
+Shows which files you've mastered and which need work. Each file needs 3 golden questions to be fully covered.
+
+## All Commands
+
+| Command | What it does |
+|---------|-------------|
+| `shikhu init` | Set up database, check API keys, create `.quizignore` |
+| `shikhu quiz` | Take a quiz (default 5 questions) |
+| `shikhu quiz --n 10` | Quiz with 10 questions |
+| `shikhu quiz --file path.py` | Quiz on a single file |
+| `shikhu refresh` | Staleness check + regenerate stale questions and summaries |
+| `shikhu summarize` | Parallel Mercury summaries for every tracked file |
+| `shikhu summarize --file path.py` | Force-regenerate summary for one file |
+| `shikhu generate-from-study path.py` | Generate quiz Qs seeded by your prior `/study` questions for that file |
+| `shikhu coverage` | Print knowledge-coverage report |
+| `shikhu clean` | Delete the database (asks for confirmation) |
+| `shikhu clean --yes` | Delete without confirmation |
+
+
+## How It Works
+
+1. **Question generation** — Mercury (Inception Labs) reads your source files and generates conceptual multiple-choice questions about design decisions, architecture, and how things work.
+
+2. **Quizzing** — Answer questions in the terminal. Rate question quality. Correct answers on good questions become **golden** — validated proof you understand that file.
+
+3. **Coverage tracking** — Each file targets 3 golden questions. Coverage = how many files have reached that bar.
+
+4. **Staleness** — When code changes (detected via SHA-256 hashing), related questions are marked stale so your coverage stays honest.
+
+5. **Study-driven generation** — `/study` captures the conceptual questions you actually ask while learning a file. `shikhu generate-from-study` turns those into quiz questions, so the next quiz tests the gaps you surfaced — not just whatever Mercury picks from the file.
+
+## Golden Questions
+
+A golden question is one you:
+- Answered correctly
+- Rated as good quality
+- Confirmed it tests real understanding of the file
+
+3 golden questions per file = fully covered. Golden questions go stale when the underlying code changes, keeping coverage honest over time.
+
+## Privacy & Data
+
+Everything Shikhu knows lives in one local SQLite file, `coverage.db`, in the repo you run it from. Nothing is uploaded anywhere. Two things are worth knowing:
+
+- **File contents are sent to the Mercury API** (Inception Labs) to generate questions and summaries — that's the only data that leaves your machine, under your own API key. Use `.quizignore` to exclude anything you don't want sent.
+- **Shikhu reads your local Claude Code transcripts** for the current project (`~/.claude/projects/...`) to find conceptual questions you've asked, and stores them in `coverage.db` to seed better quiz questions. These prompts never leave your machine — but it's one more reason `coverage.db` must stay out of git. `shikhu init` adds it to your `.gitignore` automatically.
+
+## Configuration
+
+### `.quizignore`
+
+Controls which files are skipped during generation:
+```
+# Skip these
+*.lock
+.claude/
+tests/
+deprecated/
+```
+
+### Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `INCEPTION_API_KEY` | Yes | Mercury API for question generation |
+
+## Tech
+
+- Python 3.12+, managed with [uv](https://docs.astral.sh/uv/)
+- [Mercury](https://www.inceptionlabs.ai/) for question generation
+- [Typer](https://typer.tiangolo.com/) + [Rich](https://rich.readthedocs.io/) for the CLI
+- SQLite for local storage
+- SHA-256 file hashing for staleness detection
+
+## Love the repo and have some ideas?
+Feel free to open an issue! We aren't accepting PRs at this time.