@theglitchking/babel-fish 2.0.3 → 2.4.0

package/.claude/project-map/test_grader.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Regression tests for grader.py — run: python3 .claude/project-map/test_grader.py
+
+Guards the fixes from issue #9. The headline defect there was that the grader
+scored a completely empty map and a populated one identically (97.0% both), so
+these assert the SIGNAL that separates them, not the score — deliberately, since
+folding usefulness into the weighted score would fail legitimately sparse repos.
+"""
+from __future__ import annotations
+
+import importlib.util
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).parent
+
+
+def load_grader(map_dir: Path):
+    spec = importlib.util.spec_from_file_location("grader_under_test", HERE / "grader.py")
+    g = importlib.util.module_from_spec(spec)
+    argv, sys.argv = sys.argv, ["grader.py"]
+    try:
+        spec.loader.exec_module(g)
+    finally:
+        sys.argv = argv
+    g.MAP_DIR = map_dir
+    g.SECTIONS_DIR = map_dir / "sections"
+    g.PROJECT_ROOT = map_dir
+    return g
+
+
+def write_map(map_dir: Path, *, vocab: int, scanned: int, extracted: int = 0) -> None:
+    (map_dir / "sections").mkdir(parents=True, exist_ok=True)
+    (map_dir / "PROJECT_MAP.md").write_text(f"""## Stats
+
+| Metric | Count |
+|--------|-------|
+| API Routes | {extracted} |
+| Data Models | 0 |
+| Schemas/DTOs | 0 |
+| Frontend Features | 0 |
+| Vocabulary Entries | {vocab} |
+
+### Source files scanned
+
+| Language | Files |
+|----------|-------|
+| python | {scanned} |
+
+## Section Index
+""")
+
+
+def test_empty_vocabulary_warns(tmp):
+    write_map(tmp, vocab=0, scanned=0)
+    w = load_grader(tmp).usefulness_warnings()
+    assert any("Vocabulary is empty" in x for x in w), w
+
+
+def test_populated_vocabulary_does_not_warn(tmp):
+    write_map(tmp, vocab=10, scanned=3)
+    w = load_grader(tmp).usefulness_warnings()
+    assert not any("Vocabulary is empty" in x for x in w), w
+
+
+def test_many_files_no_extraction_warns(tmp):
+    write_map(tmp, vocab=7, scanned=47, extracted=0)
+    w = load_grader(tmp).usefulness_warnings()
+    assert any("Scanned 47" in x for x in w), w
+
+
+def test_few_files_no_extraction_is_quiet(tmp):
+    """This repo: 3 CLI shims yielding no routes is correct, not a defect."""
+    write_map(tmp, vocab=10, scanned=3, extracted=0)
+    w = load_grader(tmp).usefulness_warnings()
+    assert not any("Scanned" in x for x in w), w
+
+
+def test_warnings_do_not_touch_the_score(tmp):
+    """Usefulness is reported, never scored — scoring it would fail sparse repos."""
+    g = load_grader(tmp)
+    write_map(tmp, vocab=0, scanned=99)
+    for name in dir(g):
+        if name.startswith("grade_"):
+            r = getattr(g, name)()
+            assert 0.0 <= r.raw_score <= 100.0
+    assert g.usefulness_warnings(), "expected warnings for an empty map"
+
+
+def test_populated_chains_not_misread_as_empty(tmp):
+    """`or '_No' in content` matched _Note / _Nothing anywhere in the file and
+    scored a populated section as an acceptable empty one at a flat 80%."""
+    (tmp / "sections").mkdir(parents=True, exist_ok=True)
+    (tmp / "sections" / "12-import-chains.md").write_text(
+        "# Section 12\n\n_Note: partial._\n\n```\nsrc/a.py -> src/b.py\n```\n")
+    g = load_grader(tmp)
+    r = g.grade_import_chains()
+    assert "No chains traced" not in r.details, (
+        f"a populated section was scored as empty: {r.details}")
+
+
+def test_stub_chains_still_recognised(tmp):
+    (tmp / "sections").mkdir(parents=True, exist_ok=True)
+    (tmp / "sections" / "12-import-chains.md").write_text(
+        "# Section 12\n\n_No import chains traced._\n")
+    r = load_grader(tmp).grade_import_chains()
+    assert "No chains traced" in r.details, r.details
+
+
+def test_empty_vocab_section_reaches_greenfield_branch(tmp):
+    """generate.py used to emit a placeholder TABLE ROW, which parsed as a valid
+    entry with a neutral location — scoring an empty vocabulary 100% and leaving
+    this branch permanently unreachable."""
+    (tmp / "sections").mkdir(parents=True, exist_ok=True)
+    (tmp / "sections" / "01-vocabulary.md").write_text(
+        "# Section 01\n\n| Alias | Type | Location | Notes |\n|---|---|---|---|\n\n"
+        "_No vocabulary generated yet — add source code to populate._\n")
+    r = load_grader(tmp).grade_vocabulary_accuracy()
+    assert r.raw_score == 85.0, f"greenfield branch not reached: {r.raw_score} {r.details}"
+
+
+def test_generate_emits_prose_not_a_row_for_empty_vocab():
+    spec = importlib.util.spec_from_file_location("gen", HERE / "generate.py")
+    gen = importlib.util.module_from_spec(spec)
+    argv, sys.argv = sys.argv, ["generate.py"]
+    try:
+        spec.loader.exec_module(gen)
+    finally:
+        sys.argv = argv
+    out = gen.build_vocabulary_section([])
+    rows = [l for l in out.splitlines()
+            if l.strip().startswith("|") and "Alias" not in l and set(l.strip()) - set("|-: ")]
+    assert not rows, f"empty vocabulary must not emit a table row, got {rows}"
+    assert "No vocabulary generated yet" in out
+
+
+def main() -> int:
+    import inspect
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = []
+    base = Path(tempfile.mkdtemp(prefix="grader-test-"))
+    try:
+        for fn in tests:
+            d = base / fn.__name__
+            d.mkdir(parents=True)
+            try:
+                if "tmp" in inspect.signature(fn).parameters:
+                    fn(d)
+                else:
+                    fn()
+                print(f"  ok   {fn.__name__}")
+            except Exception as e:
+                failed.append(fn.__name__)
+                print(f"  FAIL {fn.__name__}: {type(e).__name__}: {e}")
+    finally:
+        shutil.rmtree(base, ignore_errors=True)
+    print(f"\n{len(tests) - len(failed)}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude/project-map/test_mine_sessions.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Regression tests for mine-sessions.py — run: python3 .claude/project-map/test_mine_sessions.py
+
+Same shape as test_generate.py: stdlib assert + __main__, no framework.
+
+Every test here corresponds to a defect that shipped and produced NO error —
+the miner exited 0 and reported "Extracted 0 alias(es)" for its entire
+existence. Silent-zero is the failure mode these guard against.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import shutil
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+HERE = Path(__file__).parent
+
+
+def load_miner(project_root: Path, cursor_dir: Path):
+    spec = importlib.util.spec_from_file_location("miner_under_test", HERE / "mine-sessions.py")
+    mod = importlib.util.module_from_spec(spec)
+    argv, sys.argv = sys.argv, ["mine-sessions.py"]
+    try:
+        spec.loader.exec_module(mod)
+    finally:
+        sys.argv = argv
+    mod.PROJECT_ROOT = project_root
+    mod.MINE_CURSOR = cursor_dir / ".mine-cursor.json"
+    return mod
+
+
+def write_transcript(path: Path, entries: list[dict]) -> None:
+    path.write_text("\n".join(json.dumps(e) for e in entries) + "\n")
+
+
+def user_msg(text: str, **extra) -> dict:
+    """A genuine user turn, in the real nested shape Claude Code writes."""
+    return {"type": "user", "timestamp": datetime.now(timezone.utc).isoformat(),
+            "message": {"role": "user", "content": [{"type": "text", "text": text}]}, **extra}
+
+
+def tool_msg(name: str, inp: dict) -> dict:
+    return {"type": "assistant", "timestamp": datetime.now(timezone.utc).isoformat(),
+            "message": {"role": "assistant",
+                        "content": [{"type": "tool_use", "name": name, "input": inp}]}}
+
+
+def tool_result() -> dict:
+    """Tool results come back with role=user — the collision that broke pairing."""
+    return {"type": "user", "timestamp": datetime.now(timezone.utc).isoformat(),
+            "message": {"role": "user",
+                        "content": [{"type": "tool_result", "content": "ok"}]}}
+
+
+# ── Defect 1: JSONL nesting ──────────────────────────────────────────────────
+
+def test_reads_nested_message_content(m, root):
+    msg = user_msg("open the settings page")
+    assert m.msg_role(msg) == "user", "role must be read from message.role"
+    content = m.msg_content(msg)
+    assert isinstance(content, list) and content[0]["text"] == "open the settings page"
+
+
+def test_still_reads_flat_content(m, root):
+    """Older/third-party transcripts must not regress."""
+    flat = {"role": "user", "content": [{"type": "text", "text": "hello there"}]}
+    assert m.msg_role(flat) == "user"
+    assert m.msg_content(flat)[0]["text"] == "hello there"
+
+
+def test_extracts_tool_paths_from_nested(m, root):
+    paths = m.extract_file_paths_from_tool_calls(
+        [tool_msg("Read", {"file_path": str(root / "src/app.py")})])
+    assert paths == ["src/app.py"], paths
+
+
+# ── Defect 2: regex quantifiers ──────────────────────────────────────────────
+
+def test_the_x_page_pattern_matches(m, root):
+    """'{2,40?}' compiled fine and matched nothing — no error, just silence."""
+    got = m.extract_user_phrases("please look at the settings page")
+    assert "settings" in got, got
+
+
+def test_x_feature_pattern_matches(m, root):
+    got = m.extract_user_phrases("the billing workflow is broken")
+    assert any("billing" in g for g in got), got
+
+
+# ── Defect 3: tool_result / user-turn collision ──────────────────────────────
+
+def test_tool_result_is_not_a_user_turn(m, root):
+    assert m.is_user_turn(user_msg("the deals page")) is True
+    assert m.is_user_turn(tool_result()) is False, (
+        "tool results carry role=user; treating them as user turns closed the "
+        "pairing window on the assistant's own output"
+    )
+
+
+def test_meta_and_sidechain_are_not_user_turns(m, root):
+    assert m.is_user_turn(user_msg("skill body text", isMeta=True)) is False
+    assert m.is_user_turn(user_msg("subagent text", isSidechain=True)) is False
+
+
+# ── Defect 4: Bash-mediated file access ──────────────────────────────────────
+
+def test_bash_paths_extracted_when_file_exists(m, root):
+    (root / "src").mkdir(parents=True, exist_ok=True)
+    (root / "src/app.py").write_text("# app\n")
+    got = m.extract_paths_from_bash("sed -n '1,40p' src/app.py", root)
+    assert got == ["src/app.py"], got
+
+
+def test_bash_paths_ignore_nonexistent(m, root):
+    got = m.extract_paths_from_bash("cat totally/made/up.py && ls -la", root)
+    assert got == [], f"only real files may become aliases, got {got}"
+
+
+# ── Defect 6: session discovery ──────────────────────────────────────────────
+
+def test_slug_keeps_leading_separator(m, root, monkey_home):
+    """.lstrip('-') meant the exact match never hit, so every lookup fell
+    through to a fuzzy substring match that ALSO ran additively. A decoy
+    sharing the project name proves the exact path is used and that another
+    project's transcripts are not swept in — "kentro" matches four real
+    directories on this machine."""
+    projects = monkey_home / ".claude" / "projects"
+    slug = str(root).replace("/", "-")
+    (projects / slug).mkdir(parents=True)
+    write_transcript(projects / slug / "s.jsonl", [user_msg("hi there")])
+
+    decoy = projects / (slug + "-other-project")
+    decoy.mkdir(parents=True)
+    write_transcript(decoy / "d.jsonl", [user_msg("decoy transcript")])
+
+    found = m.find_session_files(root)
+    assert len(found) == 1, f"expected only the exact match, got {found}"
+    assert found[0].parent.name == slug, found[0]
+
+
+# ── End to end ───────────────────────────────────────────────────────────────
+
+def test_mines_alias_to_path(m, root, monkey_home):
+    """The test that fails if any defect returns."""
+    (root / "src").mkdir(parents=True, exist_ok=True)
+    (root / "src/deals.py").write_text("# deals\n")
+    slug = str(root).replace("/", "-")
+    d = monkey_home / ".claude" / "projects" / slug
+    d.mkdir(parents=True)
+
+    entries = []
+    for _ in range(6):  # clear MIN_SCORE = 5.0 at weight 1.0
+        entries.append(user_msg("update the deals page please"))
+        entries.append(tool_msg("Read", {"file_path": str(root / "src/deals.py")}))
+        entries.append(tool_result())
+    write_transcript(d / "s.jsonl", entries)
+
+    miner = m.SessionMiner(root)
+    miner.mine(m.find_session_files(root))
+    res = miner.results()
+    assert res, "mined nothing from a transcript containing 6 clear pairings"
+    assert "deals" in res, list(res)
+    assert "src/deals.py" in res["deals"]["targets"], res["deals"]
+
+
+def test_junk_phrases_filtered(m, root):
+    got = m.extract_user_phrases('he said "that, if not" and "total documents:"')
+    assert not any("," in g or ":" in g for g in got), got
+
+
+def main() -> int:
+    import inspect
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = []
+    tmp = Path(tempfile.mkdtemp(prefix="mine-test-"))
+    try:
+        for fn in tests:
+            root = tmp / fn.__name__ / "repo"
+            home = tmp / fn.__name__ / "home"
+            root.mkdir(parents=True); home.mkdir(parents=True)
+            m = load_miner(root, root)
+            params = inspect.signature(fn).parameters
+            kwargs = {}
+            needs_home = "monkey_home" in params
+            if needs_home:
+                # find_session_files() resolves ~/.claude/projects via Path.home()
+                m.Path.home = staticmethod(lambda: home)
+                kwargs["monkey_home"] = home
+            try:
+                fn(m, root, **kwargs)
+                print(f"  ok   {fn.__name__}")
+            except Exception as e:
+                failed.append(fn.__name__)
+                print(f"  FAIL {fn.__name__}: {type(e).__name__}: {e}")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    print(f"\n{len(tests) - len(failed)}/{len(tests)} passed")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official marketplace for babel-fish - Codebase introspection and vocabulary translation for AI coding assistants",
-    "version": "2.0.3"
+    "version": "2.4.0"
   },
   "plugins": [
     {
       "name": "babel-fish",
       "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-      "version": "2.0.3",
+      "version": "2.4.0",
       "author": {
         "name": "TheGlitchKing"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "babel-fish",
   "description": "Auto-generates a project map, vocabulary translation layer, and developer skill for any codebase. Introspects routes, models, services, features, infrastructure, and session history to give Claude instant full-stack context. Self-updates via pre-commit hook.",
-  "version": "2.0.3",
+  "version": "2.4.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/.githooks/pre-commit

@@ -14,7 +14,8 @@ if echo "$STAGED_FILES" | grep -qE "$EXTENSIONS_PATTERN" 2>/dev/null; then
             echo "[codebase-mapper] Regenerating project map..."
             if $PYTHON "$MAP_SCRIPT" 2>/dev/null; then
                 git add .claude/project-map/PROJECT_MAP.md .claude/project-map/checksums.json \
-                        .claude/project-map/sections/*.md .claude/project-map/learned-vocabulary.json 2>/dev/null || true
+                        .claude/project-map/sections/*.md .claude/project-map/learned-vocabulary.json \
+                        .claude/project-map/glossary.json 2>/dev/null || true
             fi
         fi
     fi

package/CHANGELOG.md

@@ -2,6 +2,254 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.4.0] - 2026-09-04
+
+### Added
+
+- **`glossary.json` — a structured vocabulary artifact for machine consumers**
+  ([#10](https://github.com/TheGlitchKing/babel-fish/issues/10)). Written to
+  `.claude/project-map/glossary.json` on every map build and staged by the
+  pre-commit hook. Consumers read this instead of parsing `01-vocabulary.md`.
+
+  The markdown was never a good parsing target: its `Notes` column mixes
+  descriptions with metadata, and pipe-escaping leaks into values — this repo's
+  own output contained `(auto \| nudge \| off)`. The JSON carries the real
+  string.
+
+### Fixed
+
+- **The glossary contract described a format babel-fish has never emitted.**
+  `glossary-contract.md` v1.0 specified bullet entries
+  (`- **key** → \`path\` — desc`) and stated that non-conforming bullets are
+  ignored; the generator has always written a markdown table. A consumer built
+  strictly to that spec would extract **zero entries**. Rewritten (v2.0) around
+  `glossary.json`, with the markdown documented as human-facing output that is
+  not parsed.
+
+- **Both sides of that contract documented a directory neither produces.** The
+  contract, the integration guide and the README referred to `.babel-fish/`;
+  babel-fish writes `.claude/project-map/`. The same error is mirrored in
+  semantic-memory's `smart-middle-activation.md` and `corpora-json.md`, where it
+  would have made Phase 3.1.0 find nothing — silently. Corrected here and filed
+  there as
+  [semantic-memory#28](https://github.com/the-glitch-kingdom/semantic-memory/issues/28).
+
+- **`--project-root` crashed the generator.** `write_glossary()` computed the
+  source path with `SECTIONS_DIR.relative_to(PROJECT_ROOT)`, but `SECTIONS_DIR`
+  is bound to the script's own location, so pointing `--project-root` elsewhere
+  raised `ValueError`. Found by a test written for the new artifact.
+
+- `integration-with-semantic-memory.md` no longer describes a setup that does
+  not exist. semantic-memory 1.5.1 ships no `translate` verbs, no `project-map`
+  corpus and no glossary reader; the guide now says so at the top instead of
+  giving instructions for it.
+
+### Note
+
+The consumer is unbuilt, so nothing was pinned to the old format. Issue #10
+originally advised caution about "a breaking change to a format a downstream
+consumer pins to" — checking semantic-memory's source showed zero
+`translate`/`reverse_translate`/`list_vocabulary` verbs in its 164-entry tool
+surface and no `glossary` string in `src/`. That freed the format choice
+entirely.
+
+## [2.3.0] - 2026-09-04
+
+### Fixed
+
+- **The grader could not tell a useless map from a good one**
+  ([#9](https://github.com/TheGlitchKing/babel-fish/issues/9)). All seven graded
+  categories measure *form*, and `generate.py` always emits well-formed output,
+  so the completely empty pre-2.1.0 map scored **97.0% PASS** — identical
+  category-for-category to the populated map. Verified against the real artifact
+  recovered from git, not a reconstruction.
+
+  Rather than reweighting, usefulness is now reported as **warnings that never
+  touch the score**, so no existing install flips from pass to fail:
+
+  - `generate.py` records *inputs* beside outputs (`### Source files scanned`).
+    "0 routes" cannot be judged alone; "0 routes from 47 Python files" can. The
+    counts already existed in `main()` and were being discarded.
+  - An empty vocabulary warns — that is what babel-fish is for, so zero entries
+    means the map gave you nothing. This fires on the real pre-2.1.0 map and is
+    the signal that would have surfaced #6 at install time.
+  - Ten or more source files scanned with nothing extracted warns separately,
+    catching a parser that does not fit the stack. Small repos stay quiet.
+  - A populated-sections count prints as an explicit diagnostic.
+
+- **The greenfield branch in `grade_vocabulary_accuracy()` was unreachable.**
+  `build_vocabulary_section()` emitted a placeholder *table row* for an empty
+  vocabulary, which parsed as a valid entry whose blank location counts as
+  neutral — scoring 1/1 = 100% and stepping straight over the `if not rows`
+  branch written to award 85%. It now emits prose.
+
+- **`or '_No' in content` matched too much.** Any italicised word beginning
+  "No" (`_Note`, `_Nothing`) anywhere in `12-import-chains.md` scored a
+  populated section as an acceptable empty one at a flat 80%.
+
+### Fixed (packaging)
+
+- **The npm tarball shipped local and generated files.** `files` listed
+  `.claude/` wholesale, and npm does **not** honour `.gitignore` for paths named
+  there — so every release carried this repo's own generated project map,
+  another plugin's local state (`.claude/.semantic-memory/`), five plugins'
+  update caches, ~150 kB of `__pycache__` bytecode, and
+  `.claude/settings.local.json`. `files` now lists only what
+  `.claude/install.sh` actually copies plus the test suites. Also anchored
+  `checksums.json` to `./checksums.json`: a bare filename in `files` globs at
+  any depth, so it was matching `.claude/project-map/checksums.json` too.
+
+  Tarball: 76 files / 140.9 kB → **33 files / 65.6 kB**. Verified by installing
+  from the packed tarball into a scratch project.
+
+### Added
+
+- 9 tests in `test_grader.py`, 7 of which fail against the previous code.
+  `npm test` now runs three suites (8 + 12 + 9 = 29).
+- `architecture/grading-semantics.md` — what the score means, what it
+  deliberately omits, and the measurements behind that choice.
+
+### Not done, deliberately
+
+Issue #9 originally proposed scoring section completeness on populated content.
+Measured and withdrawn: it fails the *correct* map too (85.2%), because 19
+sections is aspirational — a plugin repo can never populate routes, models,
+schemas or migrations, so `populated/19` tops out near 10/19 on a perfect map.
+It would fail every legitimately sparse repo, a worse failure than the one it
+fixes. The 90% threshold and the category weights are unchanged.
+
+## [2.2.0] - 2026-09-04
+
+### Fixed
+
+- **Session vocabulary mining has never worked**
+  ([#7](https://github.com/TheGlitchKing/babel-fish/issues/7)). The issue
+  reported that `mine-sessions.py` has no caller. It also had six defects, each
+  sufficient on its own to make it extract nothing — it exited 0 reporting
+  "Extracted 0 alias(es)" for its entire existence, which is why they survived.
+
+  1. **Wrong JSONL nesting.** Read `msg['content']`; Claude Code writes
+     `msg['message']['content']`. Measured on a real transcript: 0 vs 157
+     `tool_use` blocks, 0 vs 14 user messages. Both halves of the pairing were
+     empty.
+  2. **Invalid regex quantifiers.** `{2,40?}` and `{2,30?}` are malformed brace
+     expressions that Python silently treats as literals, so both patterns
+     compiled and matched nothing — including the one implementing this
+     feature's own README example, "the numbers page".
+  3. **Tool results collide with user turns.** Results arrive as `role: "user"`
+     (167 of 181 in one transcript), so the pairing window closed on the
+     assistant's own output.
+  4. **Bash file access was invisible.** A real session ran 148 Bash calls
+     against 2 Read and 2 Edit; only 4 of 157 tool calls qualified.
+  5. **Injected text was mined as user speech.** Skill and slash-command bodies
+     arrive in the user slot, and taught the miner aliases from the injected
+     documents themselves (`block_index_edits`, `refactor authentication
+     system` — the latter from a skill's worked example). Now skipped via
+     `isMeta` / `isSidechain`.
+  6. **Session discovery never matched exactly.** `.lstrip('-')` stripped the
+     leading separator that `~/.claude/projects/` slugs keep, so every lookup
+     fell through to a fuzzy substring match that also ran additively — and a
+     name like `kentro` matches four unrelated projects, whose aliases would be
+     attributed to this repo.
+
+  Verified against 220 MB of transcripts for a real product repo: 0 aliases
+  before, 170 after, reading like genuine domain vocabulary (`sign-up` →
+  `payments.py`, `pricing` → `subscription_gate.py`).
+
+- **`README.md` claimed mining happened "automatically".** It did not — nothing
+  called the miner. Now true, and documented with its two real caveats.
+
+### Added
+
+- **Mining runs at session start.** `hooks/session-start.js` spawns the miner
+  detached with output discarded and nothing awaited; it cannot delay or fail a
+  session, and no-ops when Python or the script is absent.
+- **Incremental cursor** (`.mine-cursor.json`). Not only a cost guard:
+  `merge_learned()` adds scores, so re-mining a counted transcript inflates it
+  without bound. `--all` forces a full re-mine.
+- 12 tests in `test_mine_sessions.py`, one per defect plus an end-to-end mine.
+  All 12 fail against the previous miner. `npm test` runs both suites (20).
+- Docs: `architecture/session-vocabulary-mining.md` (including the transcript
+  shape assumptions the miner depends on but does not control) and
+  `troubleshooting/learned-vocabulary-empty.md`.
+
+### Known issues
+
+- Aliases land one session late: SessionStart mines transcripts through the
+  previous session, since the current one isn't written yet.
+- Phrase quality is heuristic. Filtering drops clause-like candidates, but a
+  quoted string in a user message can still become an alias.
+
+## [2.1.1] - 2026-09-04
+
+### Fixed
+
+- **Section 19 listed generated hit-em-with-the-docs reports.**
+  `.documentation/reports/` holds timestamped audit output, so every `hewtd
+  maintain` wrote a new filename, which changed the doc path set, moved the
+  checksum and forced a full map regeneration — the exact churn the path-only
+  doc hash exists to prevent, reintroduced through a directory that was
+  gitignored but never excluded from the doc walk. `reports` joins `archive` in
+  `DOC_SKIP_DIRS`. Regression test added; it fails without the fix.
+
+## [2.1.0] - 2026-09-04
+
+### Fixed
+
+- **Plugin and skill repositories no longer generate an empty project map**
+  ([#6](https://github.com/TheGlitchKing/babel-fish/issues/6)). Run babel-fish
+  against a repo of markdown skills, slash commands and bash scripts and every
+  one of the 19 sections came back a "none detected" stub. Two causes, both
+  fixed:
+
+  - The checksum was blind to the files that define such a repo.
+    `collect_watched_files()` returned 11 files for babel-fish's own repository,
+    with no `.md` and no `.sh`, so editing a `SKILL.md` left the checksum
+    bit-identical and `is_unchanged()` exited before parsing. Skill and command
+    manifests are now matched by path glob (`skills/*/SKILL.md`,
+    `commands/*.md`), and `.sh` joins `WATCHED_EXTENSIONS`.
+  - Nothing read those manifests. `SkillParser` now feeds skill and command
+    frontmatter into section 01 (vocabulary) and section 10 (tools) — the two
+    sections they already fit. No new sections, no renumbering.
+
+  Measured on this repository: 0 vocabulary entries to 10, sections 2,589 bytes
+  to 4,389. On `hit-em-with-the-docs`, an unrelated plugin repo: 0 to 30.
+
+- **Section 19 missed `.documentation/` trees and went stale silently.** Doc
+  directories were never watched, so adding a document did not move the
+  checksum and the pointer list rotted until an unrelated source file happened
+  to change. Doc paths are now hashed **without** mtime: adding, renaming or
+  deleting a document refreshes section 19, while editing one does not force a
+  full regeneration. `.documentation` joins the doc directories, and generated
+  navigation (`INDEX.md`, `REGISTRY.md`) plus `archive/` are excluded — without
+  that, a 15-domain tree contributes 32 nav files and crowds every real
+  document out of the 30-entry cap.
+
+- **`checksums.json` was stale**, so the documented curl installer aborted with
+  `CHECKSUM MISMATCH` for everyone. `.claude/install.sh` was edited in `da8d2f7`
+  without regenerating the manifest.
+
+### Added
+
+- First tests in the repository: `npm test` runs an 8-test regression suite over
+  a fixture repo shaped like #6. Stdlib `assert`, no framework. Verified to fail
+  7/8 against the pre-fix generator rather than merely passing after it.
+- `.documentation/` docs for the watch set, the skill parser contract, and an
+  empty/stale map troubleshooting guide; operational runbook gained the
+  corresponding gotchas.
+
+### Known issues
+
+- `grader.py` scores a completely empty map at 97.0% PASS, the same as a fully
+  populated one — "Vocabulary Accuracy" is 100% on zero entries because
+  0/0 = 100. It measures well-formedness, not usefulness, and must not be used
+  to confirm an extractor fix. Left unchanged here: adding a floor would fail
+  existing installs that currently pass.
+- `01-vocabulary.md` is emitted as a markdown table, while
+  `.documentation/api/glossary-contract.md` specifies `- **key** → \`path\``
+  bullets. A consumer implemented strictly to that contract extracts zero
+  entries. Predates this release; which side moves is undecided.
+
 ## [2.0.3] - 2026-06-08
 
 ### Fixed