@theglitchking/babel-fish 2.0.2 → 2.3.0

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.0"
+    "version": "2.3.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.0",
+      "version": "2.3.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.0",
+  "version": "2.3.0",
   "author": {
     "name": "TheGlitchKing",
     "email": "theglitchking@users.noreply.github.com"

package/CHANGELOG.md

@@ -2,6 +2,215 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+
+- Release-metadata consistency: the 2.0.2 npm payload shipped with
+  `.claude-plugin/plugin.json` still at version 2.0.0 (the manifest bump landed
+  after the 2.0.2 publish), so Claude Code read the installed plugin as 2.0.0
+  and `claude plugin update` never advanced. 2.0.3 bumps `package.json`,
+  `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` together
+  before publishing so the plugin version resolves correctly. No code change
+  from 2.0.2.
+
 ## [2.0.2] - 2026-06-08
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 [![GitHub: TheGlitchKing/babel-fish](https://img.shields.io/badge/GitHub-TheGlitchKing%2Fbabel--fish-blue)](https://github.com/TheGlitchKing/babel-fish)
 
 > [!NOTE]
-> **Pairs with [`semantic-memory`](https://github.com/TheGlitchKing/semantic-sidekick) (formerly `semantic-sidekick`).** When both are installed, semantic-memory consumes babel-fish's auto-generated `.babel-fish/` output as a `project-map` corpus AND extracts `01-vocabulary.md` into a structured `glossary.json` side-channel. That gives your AI a deterministic `translate("deals page") → "features/deal-pipeline/DealPipeline.tsx"` MCP verb instead of relying on semantic-search-luck. See [`docs/glossary-contract.md`](./docs/glossary-contract.md) for the producer/consumer data contract and [`docs/integration-with-semantic-memory.md`](./docs/integration-with-semantic-memory.md) for the setup walkthrough. babel-fish standalone behavior is unchanged — semantic-memory is purely additive.
+> **Pairs with [`semantic-memory`](https://github.com/TheGlitchKing/semantic-sidekick) (formerly `semantic-sidekick`).** When both are installed, semantic-memory consumes babel-fish's auto-generated `.babel-fish/` output as a `project-map` corpus AND extracts `01-vocabulary.md` into a structured `glossary.json` side-channel. That gives your AI a deterministic `translate("deals page") → "features/deal-pipeline/DealPipeline.tsx"` MCP verb instead of relying on semantic-search-luck. See [`.documentation/api/glossary-contract.md`](./.documentation/api/glossary-contract.md) for the producer/consumer data contract and [`.documentation/quickstart/integration-with-semantic-memory.md`](./.documentation/quickstart/integration-with-semantic-memory.md) for the setup walkthrough. babel-fish standalone behavior is unchanged — semantic-memory is purely additive.
 
 ---
 
@@ -200,7 +200,14 @@ python .claude/project-map/grader.py
 
 ## Learned Vocabulary
 
-Every AI session is mined for vocabulary. When you say "the numbers page" and the AI opens `DealAnalyzerV2.tsx`, that alias is recorded with a score (frequency × recency). Aliases with a score ≥ 5 appear in `17-learned-vocabulary.md` automatically.
+Every AI session is mined for vocabulary. When you say "the numbers page" and the AI opens `DealAnalyzerV2.tsx`, that alias is recorded with a score (frequency × recency). Aliases with a score ≥ 5 appear in `17-learned-vocabulary.md`.
+
+Mining runs automatically at session start *(2.2.0+)*, detached and best-effort — it never delays or blocks a session. Only transcripts changed since the last run are read.
+
+Two things to expect:
+
+- **Aliases land one session late.** A session's transcript isn't written until it ends, so what you say today is mined at the *next* session start.
+- **Operational sessions mine little.** The miner learns feature nouns — "the deals page", "the billing workflow". A session spent on refactoring or releases contains few of those and will correctly yield nothing. See [learned vocabulary is empty](./.documentation/troubleshooting/learned-vocabulary-empty.md).
 
 Run the miner manually:
 

package/checksums.json

@@ -1,4 +1,4 @@
 {
-  "install_sh": "3fa520851ef80139d792ade3e6008e4356678153f39414f79c1920bf2a69dab1",
-  "note": "SHA256 of .claude/install.sh — verified by the remote installer before execution"
+  "install_sh": "565ad35c264c8e683ade82f441ab5a9f8feb3921e0b4180623bb038b23452518",
+  "note": "SHA256 of .claude/install.sh \u2014 verified by the remote installer before execution"
 }

package/hooks/session-start.js

@@ -1,11 +1,44 @@
 #!/usr/bin/env node
 // babel-fish SessionStart hook. Runs the runtime's update check per
-// policy (off / nudge / auto). No plugin-specific .mcp.json reconcile.
+// policy (off / nudge / auto), then kicks off session vocabulary mining.
 
 import { runSessionStart } from "@theglitchking/claude-plugin-runtime";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+// Mining is best-effort: it must never delay or fail session start, so it is
+// detached with output discarded and nothing is awaited. It reads only
+// transcripts changed since the last run (see mine-sessions.py's cursor).
+//
+// Timing: SessionStart sees transcripts through the PREVIOUS session — the
+// current one isn't written yet — so an alias lands one session after it is
+// first used. Accepted; a SessionEnd hook would be exact but is a second hook
+// for one session of latency.
+function mineVocabulary(cwd) {
+  try {
+    const script = join(cwd, ".claude", "project-map", "mine-sessions.py");
+    if (!existsSync(script)) return; // marketplace install that skipped the copy
+
+    const python = ["python3", "python"].find(
+      (bin) => spawnSync(bin, ["--version"], { stdio: "ignore" }).status === 0
+    );
+    if (!python) return; // no interpreter — nothing to do, and nothing to say
+
+    spawn(python, [script], {
+      cwd,
+      detached: true,
+      stdio: "ignore",
+    }).unref();
+  } catch {
+    // never surface: a mining failure must not affect session start
+  }
+}
 
 await runSessionStart({
   packageName: "@theglitchking/babel-fish",
   pluginName: "babel-fish",
   configFile: "babel-fish.json",
 });
+
+mineVocabulary(process.cwd());

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@theglitchking/babel-fish",
-  "version": "2.0.2",
+  "version": "2.3.0",
   "description": "Gives your AI coding assistant instant, accurate knowledge of every route, model, service, feature, and infrastructure element in your codebase.",
   "type": "module",
   "bin": {
     "babel-fish": "bin/babel-fish.js"
   },
   "scripts": {
-    "postinstall": "node scripts/link-skills.js"
+    "postinstall": "node scripts/link-skills.js",
+    "test": "python3 .claude/project-map/test_generate.py && python3 .claude/project-map/test_mine_sessions.py && python3 .claude/project-map/test_grader.py"
   },
   "files": [
     "bin/",
@@ -15,11 +16,19 @@
     "hooks/",
     "scripts/link-skills.js",
     ".claude-plugin/",
-    ".claude/",
+    ".claude/install.sh",
+    ".claude/scripts/",
+    ".claude/templates/",
+    ".claude/project-map/generate.py",
+    ".claude/project-map/grader.py",
+    ".claude/project-map/mine-sessions.py",
+    ".claude/project-map/test_generate.py",
+    ".claude/project-map/test_mine_sessions.py",
+    ".claude/project-map/test_grader.py",
     ".githooks/",
     "skills/",
     "install.sh",
-    "checksums.json",
+    "./checksums.json",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/.claude/project-map/PROJECT_MAP.md

@@ -1,61 +0,0 @@
-# babel-fish — Project Map
-
-> Auto-generated by `generate.py` on 2026-04-01 20:29. Do not edit manually.
-
-
-## Stats
-
-| Metric | Count |
-|--------|-------|
-| API Routes | 0 |
-| Data Models | 0 |
-| Schemas/DTOs | 0 |
-| Frontend Features | 0 |
-| Migrations | 0 |
-| Docker Services | 0 |
-| Vocabulary Entries | 0 |
-| Stack | unknown / unknown |
-
-## Section Index
-
-| # | Section | Size | When to Read |
-|---|---------|------|--------------|
-| [01](sections/01-vocabulary.md) | 01 Vocabulary | 0.3 KB | Any task — start here if you don't know where the code lives |
-| [02](sections/02-service-topology.md) | 02 Service Topology | 0.1 KB | Debugging connectivity, adding a service, understanding ports |
-| [03](sections/03-environment.md) | 03 Environment | 0.1 KB | Environment setup, missing vars, config issues |
-| [04](sections/04-api-routes.md) | 04 Api Routes | 0.1 KB | Adding/editing API endpoints, checking what routes exist |
-| [05](sections/05-data-models.md) | 05 Data Models | 0.1 KB | Changing database schema, adding fields, understanding relations |
-| [06](sections/06-schemas.md) | 06 Schemas | 0.1 KB | Adding DTOs, changing request/response shapes |
-| [07](sections/07-services.md) | 07 Services | 0.1 KB | Adding service logic, understanding service boundaries |
-| [08](sections/08-background-jobs.md) | 08 Background Jobs | 0.1 KB | Working with background jobs, queues, scheduled tasks |
-| [09](sections/09-frontend-features.md) | 09 Frontend Features | 0.1 KB | Frontend feature work, understanding UI structure |
-| [10](sections/10-tools-commands.md) | 10 Tools Commands | 0.3 KB | Available commands, scripts, developer tooling |
-| [11](sections/11-migrations.md) | 11 Migrations | 0.1 KB | Database migrations, schema history |
-| [12](sections/12-import-chains.md) | 12 Import Chains | 0.2 KB | Tracing data flow from HTTP request to DB |
-| [13](sections/13-frontend-backend-map.md) | 13 Frontend Backend Map | 0.1 KB | Understanding which frontend calls which backend endpoint |
-| [14](sections/14-reverse-proxy.md) | 14 Reverse Proxy | 0.1 KB | Proxy routing, nginx/caddy config |
-| [15](sections/15-auth-config.md) | 15 Auth Config | 0.1 KB | Auth flow, sessions, permissions |
-| [16](sections/16-infra-profile.md) | 16 Infra Profile | 0.3 KB | Infrastructure overview, tech stack summary |
-| [17](sections/17-learned-vocabulary.md) | 17 Learned Vocabulary | 0.2 KB | Vocabulary learned from past sessions |
-| [18](sections/18-dead-code.md) | 18 Dead Code | 0.2 KB | Dead code review |
-| [19](sections/19-doc-pointers.md) | 19 Doc Pointers | 0.1 KB | Finding documentation, READMEs, wikis |
-
-## Quick Routing
-
-| Task | Read Sections |
-|------|--------------|
-| Feature / UX work | 01 → 09 → 04 |
-| Add model or field | 05 → 06 → 12 |
-| Troubleshoot error | 02 → 03 → 14 |
-| Infrastructure / scaling | 16 → 02 |
-| Auth / security | 15 → 19 |
-| What tools exist | 10 |
-| Background jobs | 08 |
-| Migration history | 11 |
-
-## Regenerate
-
-```bash
-python .claude/project-map/generate.py          # skip if unchanged
-python .claude/project-map/generate.py --force  # always regenerate
-```

package/.claude/project-map/checksums.json

@@ -1,6 +0,0 @@
-{
-  "input_hash": "01b723fba1eeffe29b8a71be2fbd81197a22fc0e4fec0eb10a096361b4b3d054",
-  "generated_at": "2026-04-01T20:29:02.877707",
-  "route_count": 0,
-  "model_count": 0
-}

package/.claude/project-map/learned-vocabulary.json

@@ -1 +0,0 @@
-{}