@theglitchking/babel-fish 2.0.3 → 2.4.0

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 `.claude/project-map/` output as a `project-map` corpus AND reads the structured `glossary.json` babel-fish emits alongside it. 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.3",
+  "version": "2.4.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 @@
-{}

package/.claude/project-map/reports/install-report.md

@@ -1,54 +0,0 @@
-# Codebase Mapper — Installation Report
-
-**Generated**: 2026-03-31 11:00:17
-**Iteration**: 1 of 3  
-**Score**: 97.0%  
-**Result**: ✅ PASSED (90% threshold)
-
----
-
-## Scoring Breakdown
-
-| Category | Score | Weight | Weighted | Status |
-|----------|-------|--------|----------|--------|
-| Section Completeness | 100.0% | 25% | 25.0 | ✅ 19/19 sections present |
-| Vocabulary Accuracy | 100.0% | 20% | 20.0 | ✅ 1/1 entries have valid file references |
-| Import Chain Validity | 80.0% | 15% | 12.0 | ⚠️ No chains traced (greenfield or non-Python stack — ok) |
-| Secret Safety | 100.0% | 15% | 15.0 | ✅ Checked 20 files — 0 potential leak(s) |
-| Section Size Bounds | 100.0% | 10% | 10.0 | ✅ 19 sections, 0 size violations |
-| Structural Integrity | 100.0% | 10% | 10.0 | ✅ 0 broken TOC links, 0 structural issues |
-| Checksum Functionality | 100.0% | 5% | 5.0 | ✅ checksums.json valid (hash: e3b0c44298fc...) |
-
-**Total: 97.0 / 100**
-
----
-
-## Issues Found
-
-_No issues found._
-
----
-
-## Final Verdict
-
-✅ **PASSED (97.0%)** — Map is production-ready.
-
-The project map meets quality standards and is ready to use.
-Future sessions will load relevant sections automatically via the developer skill.
-
----
-
-## How to Use the Project Map
-
-```bash
-# Read the map index
-cat .claude/project-map/PROJECT_MAP.md
-
-# Force regeneration
-python .claude/project-map/generate.py --force
-
-# Re-run grader
-python .claude/project-map/grader.py
-```
-
-_Report generated by `grader.py` — part of the Codebase Mapper plugin._

package/.claude/project-map/reports/iteration-01-report.md

@@ -1,54 +0,0 @@
-# Codebase Mapper — Installation Report
-
-**Generated**: 2026-03-31 11:00:17
-**Iteration**: 1 of 3  
-**Score**: 97.0%  
-**Result**: ✅ PASSED (90% threshold)
-
----
-
-## Scoring Breakdown
-
-| Category | Score | Weight | Weighted | Status |
-|----------|-------|--------|----------|--------|
-| Section Completeness | 100.0% | 25% | 25.0 | ✅ 19/19 sections present |
-| Vocabulary Accuracy | 100.0% | 20% | 20.0 | ✅ 1/1 entries have valid file references |
-| Import Chain Validity | 80.0% | 15% | 12.0 | ⚠️ No chains traced (greenfield or non-Python stack — ok) |
-| Secret Safety | 100.0% | 15% | 15.0 | ✅ Checked 20 files — 0 potential leak(s) |
-| Section Size Bounds | 100.0% | 10% | 10.0 | ✅ 19 sections, 0 size violations |
-| Structural Integrity | 100.0% | 10% | 10.0 | ✅ 0 broken TOC links, 0 structural issues |
-| Checksum Functionality | 100.0% | 5% | 5.0 | ✅ checksums.json valid (hash: e3b0c44298fc...) |
-
-**Total: 97.0 / 100**
-
----
-
-## Issues Found
-
-_No issues found._
-
----
-
-## Final Verdict
-
-✅ **PASSED (97.0%)** — Map is production-ready.
-
-The project map meets quality standards and is ready to use.
-Future sessions will load relevant sections automatically via the developer skill.
-
----
-
-## How to Use the Project Map
-
-```bash
-# Read the map index
-cat .claude/project-map/PROJECT_MAP.md
-
-# Force regeneration
-python .claude/project-map/generate.py --force
-
-# Re-run grader
-python .claude/project-map/grader.py
-```
-
-_Report generated by `grader.py` — part of the Codebase Mapper plugin._

package/.claude/project-map/reports/iteration-01-score.json

@@ -1,7 +0,0 @@
-{
-  "score": 97.0,
-  "passed": true,
-  "threshold": 90.0,
-  "iteration": 1,
-  "issues": []
-}

package/.claude/project-map/sections/01-vocabulary.md

@@ -1,8 +0,0 @@
-# Section 01 — Vocabulary Translation Layer
-
-> Maps human language to exact code locations. Auto-generated.
-
-
-| Alias | Type | Location | Notes |
-|-------|------|----------|-------|
-| _(no vocabulary generated yet — add source code to populate)_ | | | |

package/.claude/project-map/sections/02-service-topology.md

@@ -1,6 +0,0 @@
-# Section 02 — Service Topology
-
-> Docker services, ports, and dependencies.
-
-
-_No docker-compose services detected._

package/.claude/project-map/sections/03-environment.md

@@ -1,6 +0,0 @@
-# Section 03 — Environment Variables
-
-> Key names and non-sensitive values only. Secrets are redacted.
-
-
-_No .env files found._

package/.claude/project-map/sections/04-api-routes.md

@@ -1,6 +0,0 @@
-# Section 04 — API Routes
-
-
-| Method | Path | File | Line |
-|--------|------|------|------|
-| _(no routes detected yet)_ | | | |

package/.claude/project-map/sections/05-data-models.md

@@ -1,4 +0,0 @@
-# Section 05 — Data Models
-
-
-_No data models detected yet._

package/.claude/project-map/sections/06-schemas.md

@@ -1,4 +0,0 @@
-# Section 06 — Schemas / DTOs
-
-
-_No schemas detected yet._

package/.claude/project-map/sections/07-services.md

@@ -1,6 +0,0 @@
-# Section 07 — Services
-
-
-_Service discovery is inferred from directory structure and imports._
-
-

package/.claude/project-map/sections/08-background-jobs.md

@@ -1,5 +0,0 @@
-# Section 08 — Background Jobs
-
-
-_No background jobs detected._
-

package/.claude/project-map/sections/09-frontend-features.md

@@ -1,4 +0,0 @@
-# Section 09 — Frontend Features
-
-
-_No frontend feature directories detected._

package/.claude/project-map/sections/10-tools-commands.md

@@ -1,8 +0,0 @@
-# Section 10 — Tools & Commands
-
-
-| Name | Command | Source |
-|------|---------|--------|
-| `postinstall` | `npm run postinstall` | package.json |
-| `install.sh` | `bash install.sh` | shell |
-| `/babel-fish-developer-skill` | `/babel-fish-developer-skill` | skills |

package/.claude/project-map/sections/11-migrations.md

@@ -1,4 +0,0 @@
-# Section 11 — Migrations
-
-
-_No migrations detected._

package/.claude/project-map/sections/12-import-chains.md

@@ -1,7 +0,0 @@
-# Section 12 — Import Chains
-
-
-_Traces route → service → model → table for key endpoints._
-
-
-_No import chains traced (requires Python source files with routes)._

package/.claude/project-map/sections/13-frontend-backend-map.md

@@ -1,8 +0,0 @@
-# Section 13 — Frontend → Backend Map
-
-
-_Maps frontend API service calls to backend route paths._
-
-
-_No frontend→backend mappings detected yet._
-

package/.claude/project-map/sections/14-reverse-proxy.md

@@ -1,4 +0,0 @@
-# Section 14 — Reverse Proxy
-
-
-_No reverse proxy configuration detected._

package/.claude/project-map/sections/15-auth-config.md

@@ -1,6 +0,0 @@
-# Section 15 — Auth Configuration
-
-
-**Provider**: unknown
-
-

package/.claude/project-map/sections/16-infra-profile.md

@@ -1,13 +0,0 @@
-# Section 16 — Infrastructure Profile
-
-
-| Property | Value |
-|----------|-------|
-| **Language** | unknown |
-| **Framework** | unknown |
-| **Database** | unknown |
-| **ORM** | unknown |
-| **Auth** | unknown |
-| **Package Manager** | unknown |
-| **Infrastructure** | none |
-| **Services** | 0 docker services |

package/.claude/project-map/sections/17-learned-vocabulary.md

@@ -1,7 +0,0 @@
-# Section 17 — Learned Vocabulary
-
-
-_Aliases mined from Claude Code session history. Score = frequency × recency._
-
-
-_No session-mined vocabulary yet. Accumulates over time._

package/.claude/project-map/sections/18-dead-code.md

@@ -1,9 +0,0 @@
-# Section 18 — Dead Code Candidates
-
-
-> Files flagged for human review: no recent commits AND low vocabulary score.
-
-> **Do not auto-delete.** Review before removing.
-
-
-_No dead code candidates detected._

package/.claude/project-map/sections/19-doc-pointers.md

@@ -1,5 +0,0 @@
-# Section 19 — Documentation Pointers
-
-
-- [`CLAUDE.md`](CLAUDE.md)
-- [`README.md`](README.md)

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

@@ -1,12 +0,0 @@
-{
-  "name": "babel-fish",
-  "slug": "babel-fish",
-  "language": "unknown",
-  "framework": "unknown",
-  "database": "unknown",
-  "orm": "unknown",
-  "auth": "unknown",
-  "package_manager": "unknown",
-  "infrastructure": "none",
-  "project_root": "/mnt/e/the-glitch-kingdom/babel-fish"
-}

package/.claude/rules/operational-runbook.md

@@ -1,40 +0,0 @@
-# babel-fish — Operational Runbook
-
-> Auto-loaded every session. Contains operational knowledge that cannot be derived from code.
-> This file grows over time as the team discovers gotchas, quirks, and procedures.
-> **Edit this file manually** — it is NOT overwritten on regeneration.
-
-## Environment Differences
-
-<!-- TODO: Document how dev/staging/prod differ (DB, deploy method, secrets, URLs) -->
-
-| | Dev | Staging | Production |
-|---|---|---|---|
-| **URL** | | | |
-| **Database** | | | |
-| **Deploy** | | | |
-| **Secrets** | | | |
-
-## Known Issues & Workarounds
-
-<!-- This section fills in naturally. When you hit a non-obvious issue, add it here. -->
-<!-- Examples: "HMR doesn't work on WSL2", "port 6543 breaks migrations" -->
-
-_No known issues documented yet. When you encounter a non-obvious problem and its solution, add it here so future sessions don't re-discover it._
-
-## Deploy Procedures
-
-<!-- TODO: Document how to deploy to each environment -->
-
-## Key Commands
-
-| Command | What It Does |
-|---------|-------------|
-| `python .claude/project-map/generate.py --force` | Force-regenerate project map |
-| `python .claude/project-map/grader.py` | Grade map quality (0-100%) |
-| `bash .githooks/install.sh` | (Re)install git hooks |
-| `bash .claude/install.sh` | Re-run full plugin installer |
-
-## Dev Credentials
-
-<!-- Add test/dev credentials here (NEVER production secrets) -->

package/.claude/rules/project-vocabulary.md

@@ -1,25 +0,0 @@
-# babel-fish — Project Vocabulary
-
-> Auto-loaded every session. Maps human language to exact code locations.
-> Regenerated automatically via pre-commit hook. Do not edit the auto-generated rows.
-
-## Feature → Code Location
-
-| You Say | Frontend | Backend | Model/Table |
-|---------|----------|---------|-------------|
-| _(vocabulary populates as source code is added)_ | | | |
-
-## Infrastructure Vocabulary
-
-| You Say | What It Is | Key Details |
-|---------|-----------|-------------|
-| project | babel-fish | unknown / unknown stack |
-
-## Quick Actions
-
-| You Say | What To Do |
-|---------|-----------|
-| regenerate map | `python .claude/project-map/generate.py --force` |
-| grade map | `python .claude/project-map/grader.py` |
-| view project map | `cat .claude/project-map/PROJECT_MAP.md` |
-| install hooks | `bash .githooks/install.sh` |

package/.claude/settings.json

@@ -1,6 +0,0 @@
-{
-  "statusLine": {
-    "type": "command",
-    "command": "/mnt/e/the-glitch-kingdom/babel-fish/.claude/scripts/statusline.sh"
-  }
-}

package/.claude/settings.local.json

@@ -1,6 +0,0 @@
-{
-  "enabledMcpjsonServers": [
-    "semantic-vault"
-  ],
-  "enableAllProjectMcpServers": true
-}

package/.claude/skills/babel-fish-developer-skill/SKILL.md

@@ -1,56 +0,0 @@
----
-name: babel-fish-developer-skill
-description: |
-  Full-stack developer context for babel-fish (unknown/unknown).
-  Provides instant access to project map, vocabulary translation, and infrastructure details.
-  Invoke when working on any babel-fish feature, bug, or infrastructure task.
----
-
-# /babel-fish-developer — babel-fish Developer Context
-
-You are a developer working on **babel-fish**. This skill gives you complete
-knowledge of every route, model, service, feature, and infrastructure component
-via an auto-generated project map.
-
-## On Trigger — Load Only What You Need
-
-The project map is split into section files at `.claude/project-map/sections/`.
-Do NOT read them all. Start with:
-
-```
-Read: .claude/project-map/PROJECT_MAP.md
-```
-
-Use the Quick Routing table to pick which 2-3 sections to load.
-
-## Section Routing
-
-| Task | Read These Sections |
-|------|-------------------|
-| Feature / UX work | 01-vocabulary → 09-frontend → 04-routes |
-| Add a model or field | 05-models → 06-schemas → 12-import-chains |
-| Troubleshoot error | 02-topology → 03-environment → 14-proxy |
-| Infrastructure / scaling | 16-infra-profile → 02-topology |
-| Auth / security | 15-auth-config → 19-doc-pointers |
-| What tools exist | 10-tools-commands |
-| Background jobs | 08-background-jobs |
-
-## Platform Quick Reference
-
-- **Stack**: unknown / unknown
-- **Map**: `.claude/project-map/PROJECT_MAP.md`
-
-## Keeping the Map Current
-
-Regenerates automatically via pre-commit hook.
-Force: `python .claude/project-map/generate.py --force`
-
-## Growing the Runbook
-
-When you encounter a non-obvious operational issue, suggest adding it:
-
-> "This looks like operational knowledge worth documenting. Want me to add it
-> to the runbook? (Y/n)"
-
-If agreed, append a concise entry (symptom → cause → fix) to
-`.claude/rules/operational-runbook.md`.