{
    "table": "repo_docs",
    "pk": "id",
    "total": 452,
    "page": 1,
    "per": 25,
    "pages": 19,
    "filter": [],
    "rows": [
        {
            "id": 1,
            "ts": 1784098241,
            "repo": ".claude_tools",
            "path": "README.md",
            "kind": "md",
            "body": "# ~/.claude_tools \u2014 agent tooling, OUTSIDE project scope\n\nTools that must survive project deploys/redeploys and never be \"forgotten.\" Kept out of the project\ntree on purpose: a prior sbx deploy of core services was orphaned because tooling wasn't redirected\nand no telemetry was collected \u2014 this directory is the always-available fallback.\n\n## notesdb \u2014 notes + internal-telemetry store (server + client)\n\nA **stdlib-only** re-implementation of jazz-notes-db (no Docker, no fastapi/uvicorn/aiosqlite) so it\ncan't rot behind a missing venv or a down daemon. Split so the boundary is real, not decorative:\n\n- **`cnotesd.py` \u2014 the server. The single writer and the boundary.** The ONLY thing that touches the\n  SQL tables. It owns the schema + validation + invariants. Runs as a launchd service\n  (`com.claude.cnotesd`, `KeepAlive` \u2192 always-up) on `http://127.0.0.1:8002`. DB: `~/.claude_tools/notes.db`\n  (WAL; override `$NOTESDB_PATH`).\n- **`cnotes` (CLI) \u2014 a pure HTTP client.** Holds NO SQL; it never touches the tables. Writes are\n  `POST`, reads are `GET`. This is the point: clients (this CLI, sandboxed agents, services) all go\n  through the API, exactly like the read/write planes in `~/code/rebuild/SANDBOX-PLANES.md`.\n\n**Why not direct-write?** The HTTP layer *is* the boundary that stops any client editing the raw\ntables. A CLI that writes SQL directly would defeat it. Reliability (the \"can't be forgotten\"\nrequirement) is met by the **server being always-up** \u2014 and by a client-side **spool**: if the server\nis momentarily down, a write is appended to `~/.claude_tools/spool.jsonl` (a durable *outbox*, not the\nDB) and re-dispatched **through the server's validated path** on the next `flush`/successful write. No\nloss, no bypass.\n\nSchema is faithful to the original (`notes`, `telemetry`) + a free-form `events` table, so\n`backup_notes_db` exports stay restorable.\n\n```\ncnotes event KIND [--source S] [--data '{json}'] [--text X]     # internal-telemetry event\ncnotes add --title T --text X [--collection C] [--tags a,b]     # a note\ncnotes ls [--collection C] [--tag t] | get ID | search Q | rm ID\ncnotes events [--kind K] [--limit N]\ncnotes telemetry log --package P [--exit-state S] [--elapsed F] ... | ls | stats\ncnotes stats | flush | health          # flush drains the spool; --json goes BEFORE the subcommand\ncnotes --json <cmd>\n```\n\nService control: `launchctl kickstart -k gui/$(id -u)/com.claude.cnotesd` (restart),\n`launchctl print gui/$(id -u)/com.claude.cnotesd` (status). Log: `~/.claude_tools/notesdbd.log`.\n"
        },
        {
            "id": 2,
            "ts": 1784098241,
            "repo": ".congruency__rebase",
            "path": "README.md",
            "kind": "md",
            "body": "# congruencey \u2014 the ratchet\n\nSteven Peterson's 2006 PHP CMS (\"congruency\"), resurrected on PHP 8 and folded into a ratchet-managed\npackage. The repo is **three single branches** \u2014 a crank is a **commit + version tag**, not a branch:\n\n| branch | holds |\n|---|---|\n| **main** (this one) | the **ratchet** \u2014 the installers only: `install.py` (dev/test) + `deploy.py` (production). No app source. |\n| **source** | the CMS + tooling. A crank = one commit + a `version-4.05x` tag, in place (`mint_crank.py`). |\n| **state** | the compressed dev DB (a single `database.tar.xz`), tagged `state-<version>` to match a source version. |\n\n## Install a version (dev / test)\n```\ngit clone <repo> && cd congruencey        # lands on main (source-free)\npython3 install.py --version 4.071          # required: which source version to stand up\n```\n`install.py` (stdlib-only, self-contained) per step \u2014 recording telemetry, catching any bug thrown:\n1. **checkout** the source tag `version-X` (detached \u2014 materializes the source);\n2. **provision php** \u2014 `checkouts/current/tools/provision_php.py` (static PHP 8; idempotent);\n3. **install state** \u2014 the matching demo DB from the `state` branch (`state-<version>`, else newest \u2264 X);\n4. **stand up + verify** \u2014 `tooling/congruencey-tests/verify` (stand-up + bug-catalog + branch-coverage).\n\nFlags: `--no-verify`, `--return-to-main`.\n\n## Deploy a version (production)\n```\npython3 deploy.py --target /srv/site --version 4.071\n```\nExports the app to the target with a JSON config (`install.json`) + a **fresh production stub DB**\n(intro + catalog + 404, current styling, no demo content), creates the target if absent, and boots\nconfig-driven \u2014 verifying the stub is up (recorded as predictions). See **DEPLOY.md**.\n\n## How work happens (on `source`)\n```\npython3 checkouts/current/tools/mint_crank.py --patch P.py --name x   # a crank = commit + version tag\n```\nEach crank is one Python patch, captured **in place** on `source`, **test-first** (predictions recorded\nto `logs/predictions.jsonl`; a refuted prediction is a bug), then state-snapshotted and verified before\nit lands. The `version-4.05x` tags are the crank detents; `make_state.py --version X` snapshots the DB\nto the `state` branch (single `database.tar.xz`) via git plumbing, tagging `state-<version>`.\n\n## Telemetry & bugs\nEvery step emits to `jazz_telemetry` (`~/.jazz/congruency.sqlite`) when available; any unexpected\noutcome writes a Variant-A bug report to the registry's `bug_reports` sink (`logs/bug_reports.jsonl`)\nand opens a mechanical-id ticket. Best-effort \u2014 never blocks.\n\n## More docs\n`source:README.md` (structure) \u00b7 `source:DEPLOY.md` (production) \u00b7 `source:DEPENDENCIES.md` (runtime deps\n+ process changes) \u00b7 `source:checkouts/current/ARCHITECTURE.md` (the 2006 CMS internals).\n"
        },
        {
            "id": 3,
            "ts": 1784098241,
            "repo": "backup_notes_db",
            "path": "README.md",
            "kind": "md",
            "body": "# notes_db backup \u2014 private\n"
        },
        {
            "id": 4,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": ".MCP/README.md",
            "kind": "md",
            "body": "# mcp-coupler\n\nA **coupling device for any number of MCP servers** \u2014 one MCP server that fronts N\ndownstream MCP servers, merging all their tools into a single namespaced list and\nrouting each call to the owning server. Register the coupler once; it fans out.\n\n```\nhost \u2500\u2500stdio\u2500\u2500\u25ba coupler \u2500\u2500stdio\u2500\u2500\u25ba server A   (a1, a2 \u2192 A__a1, A__a2)\n                        \u2500\u2500stdio\u2500\u2500\u25ba server B   (b1     \u2192 B__b1)\n                        \u2500\u2500stdio\u2500\u2500\u25ba \u2026any number\u2026\n```\n\nZero dependencies \u2014 MCP stdio is just newline-delimited JSON-RPC 2.0, implemented\ndirectly on Node's stdlib. Nothing to `npm install`.\n\n## Configure\n\n`$COUPLER_CONFIG` (or `./coupler.config.json`). The `mcpServers` key is also\naccepted, so a Claude Code config block drops in verbatim:\n\n```json\n{\n  \"servers\": {\n    \"congruency\": { \"command\": \"node\", \"args\": [\"/home/notificationsforsteven/congruency-mcp/server.js\"] },\n    \"some-other\": { \"command\": \"npx\", \"args\": [\"-y\", \"@vendor/mcp\"], \"env\": { \"TOKEN\": \"\u2026\" } }\n  }\n}\n```\n\n## Tool naming\n\nEvery downstream tool is exposed as `<server>__<tool>` (double-underscore), so two\nservers can each have a `search` tool without colliding. Descriptions are prefixed\nwith `[server]`. Results pass through unchanged.\n\n## Built-in meta tools\n\n- `coupler__status` \u2014 health + tool count of every downstream.\n- `coupler__reconnect` \u2014 tear down and re-spawn all downstreams, re-aggregate.\n\n## Behaviour\n\n- **Lazy + warm**: downstreams are spawned on the first `tools/list`/`tools/call`\n  (and warmed on `initialize`), then cached.\n- **Resilient**: a downstream that fails to start or dies is isolated and marked\n  down in `coupler__status`; the others keep working. It never sinks the coupler.\n- **Timeouts**: 30 s handshake, 5 min per downstream `tools/call`.\n- **Clean shutdown**: on stdin close / SIGTERM it drains in-flight calls, kills all\n  child servers, and exits.\n\n## Install into Claude Code\n\nRegister **only the coupler** (remove the individual servers so tools aren't\nduplicated):\n\n```bash\nclaude mcp add coupler -s local -- node /home/notificationsforsteven/mcp-coupler/coupler.js\n```\n\nThen edit `coupler.config.json` to list the servers you want coupled. New tools\nappear at the next session start (`/mcp` reconnect).\n"
        },
        {
            "id": 5,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "README.md",
            "kind": "md",
            "body": "# Conductor \u2014 super-repo\n\nOne git repository holding every package, consolidated from the previously scattered nested repos under `test_project/`. Source-only, single history.\n\n## Layout\n- `packages/` \u2014 the shippable packages (codebean_mcp, code_pipeline, git_surface[_mcp], routed_vm, spec_graph_mcp, wayback).\n- `tools/` \u2014 supporting tools (unispec, spec_ast_graph, tournaments, vmctl_web, \u2026).\n- `spec/` \u2014 the requirement/spec apparatus (SPEC.md, decompose, sections/slices).\n\nThe codebean crank + generative solve pipeline lives in `packages/codebean_mcp/prototype/`.\n"
        },
        {
            "id": 6,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "packages/code_pipeline/README.md",
            "kind": "md",
            "body": "# code_pipeline\n\nThe Conductor **execution-provenance graph tracer** \u2014 the \"debug operator\" (DO) from the\nLiving Code-Graph spec (CM/DO/PS/GC), rebuilt clean.\n\n## Why this exists (not a fix \u2014 a replacement)\n`dz_debug` is **split-brained**: three folders on disk all named `dz_debug` (a good 269-line\nDB-backed tracer, a weak 42-line RAM-only one, and stale vendored copies), plus a\n`find_packages()` + same-name-project-folder trap that makes `import dz_debug` resolve to an\nempty namespace shell. So `from dz_debug import debug_decorator` \u2014 stamped onto every function\nby codebean \u2014 resolves to nothing, and the calling class was never recorded.\n\nWe are **not** untangling that rot. `code_pipeline` is a new name, a new source tree, rebuilt\nfrom the spec, with a **src-layout** so the outer-name shadow is structurally impossible.\n\n## What it does (spec IDs)\n- **DO-1** call graph: nodes `{handle, guid=uuid5(file:qualname:commit), file, commit}`, real\n  caller\u2192callee edges (contextvars call-stack), variable snapshots, run/trace scoping.\n- **DO-2** every branch point via `sys.monitoring` (loops aggregated by count \u2014 loops-above).\n- **PS-1..5**: a NEW, dedicated, auto-timestamped DB (`$CODE_PIPELINE_DB`, default\n  `~/code/forge/code_pipeline.db`); in-memory hot path \u2192 serialise on function stop;\n  FULL collection with backpressure (never a silent drop); not grandfathered onto telemetry.db.\n- Node `commit` joins the wayback git lineage; the runtime trace is a traversal of the static graph.\n\n## Use\n```python\nfrom code_pipeline import trace, new_run, edges, branches\nnew_run(task=\"my run\")\n@trace\ndef f(x): ...\n```\n\n## Env\n- `CODE_PIPELINE_DB` \u2014 trace DB path (default `~/code/forge/code_pipeline.db`)\n- `CODE_PIPELINE_REPR_LIMIT` (2000) \u00b7 `CODE_PIPELINE_QUEUE_MAX` (20000) \u00b7 `CODE_PIPELINE_BRANCHES` (1)\n\n## Test\n```\n~/code/.venv/bin/python tests/test_graph.py     # standalone, or: python -m pytest tests/\n```\n"
        },
        {
            "id": 7,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "packages/codebean_mcp/README.md",
            "kind": "md",
            "body": "# codebean-mcp\n\nAn MCP that lets an LLM **author code as an in-memory model** \u2014 packages, classes, functions \u2014\n**without touching files or git**. The model is the \"bean\"; `save()` materializes + commits behind\nthe scenes. The point is the **focused sub-mind**: it works on code structure and reads it via\n`render()`, never distracted by disk, paths, or branches.\n\n## Tools\n- `new_module(name)`\n- `add_class(module, name, bases, doc)`\n- `add_function(target, name, params, body, doc, decorators)` \u2014 target = `module` or `module.Class` (self inserted for methods)\n- `set_body(target, body)` \u2014 `module.func` or `module.Class.method`\n- `render(module?)` \u2014 read the generated source\n- `tree()` \u2014 structure (modules \u2192 classes/methods/functions)\n- `save(message)` \u2014 persist (materialize + git commit; **git is concealed** \u2014 you just describe the change)\n\nConfig: `CODEBEAN_ROOT` (hidden workspace, default `~/.codebean/work`), `CODEBEAN_PROJECT`.\nGenerated source is valid Python (verified by `compile()` in tests).\n"
        },
        {
            "id": 8,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "packages/git_surface/README.md",
            "kind": "md",
            "body": "# git-surface \u2014 agent-ergonomic git wrapper, evolved\n\nA real meta-evolutionary tournament that evolves an MCP-style git-surface wrapper toward\nminimal-friction, token-efficient, self-correcting tools for LLM agents.\n\n## Files\n- `gen1.py` \u2014 the seed: three tools (surface / atomic-read / blame) + the first real\n  tournament (naive vs evolved) scored on deterministic fitness. `python3 gen1.py`.\n- `evolve_step.py` \u2014 **one generation per invocation** (a stateless ratchet): mutate the\n  baseline (epoch-gated vectors) \u2192 evaluate the population on **deterministic fitness +\n  a live qwen friction judge** \u2192 elitist k-tournament select \u2192 persist. Bounded at gen 1000.\n- `run/state.json` \u2014 current generation + baseline genome.\n- `run/generations.jsonl` \u2014 append-only log, one line per generation (the real fitness curve).\n- `run/cron.log` \u2014 stdout of the scheduled runs.\n\n## The scheduled run (live)\nInstalled on system crontab, every 5 minutes:\n```\n*/5 * * * * PATH=/opt/homebrew/bin:/usr/bin:/bin /opt/homebrew/bin/python3 \\\n  .../git_surface/evolve_step.py >> .../git_surface/run/cron.log 2>&1 # git-surface-evolve\n```\n**Kill switch:** `crontab -l | grep -v git-surface-evolve | crontab -`\n\n## The qwen friction judge\nReal, local, free: `qwen/qwen3-coder-30b` via LM Studio's OpenAI server at\n`http://localhost:1234/v1` (started with `lms server start`). Each generation asks qwen to\nrate how low-friction a genome's tool responses are (0..1). **If LM Studio's server stops,**\nthe friction term degrades to a neutral 0.5 (`friction_src=qwen_unavailable`) and evolution\ncontinues on deterministic fitness \u2014 the cron never dies. Re-enable real scores with\n`lms server start`.\n\n## Epoch schedule (per the roadmap)\n- **1\u2013150 structural** \u2014 surface/read/error correctness. Converges fast to fitness \u2248 2.34\n  (structured surface + ranged read + fuzzy self-heal), then holds (elitism = no regression).\n- **151\u2013450 ergonomic** \u2014 unlocks `serialize` (compact) + `token_min` heuristics.\n- **451\u2013750 adversarial** / **751\u20131000 convergence** \u2014 all vectors active.\n  (Note: at the 5-min cadence, the ergonomic epoch unlocks ~gen 151 \u2248 12h in. To see gains\n  sooner, shrink the epoch bounds in `epoch_axes()` or lower the cron interval floor.)\n\n## Watch it\n```\ntail -f run/generations.jsonl        # live fitness curve\npython3 -c \"import json;[print(json.loads(l)['gen'],json.loads(l)['fitness']) for l in open('run/generations.jsonl')]\"\n```\nTelemetry: component `git-surface-evolve` in `~/code/forge/telemetry.db`.\n\n## Update \u2014 red-teamed + condensed (authorized)\n- **Fitness hardened (`score_responses`, v2).** `redteam.py` proved the original substring\n  correctness was **gameable**: a cheater emitting only the magic words scored 1.977 vs the\n  honest 1.932 by farming the token-thrift term. v2 requires the read to contain the **actual\n  file lines verbatim** + the surface to reflect **real git state** \u2192 cheater collapses to\n  1.477, honest holds 1.932 (defended by 0.455). Run `python3 redteam.py` to re-verify.\n- **Intervals condensed.** Cron cadence `*/5` \u2192 **`* * * * *` (1 min)**; epoch bounds\n  condensed to **20 / 60 / 120** (env `GS_EP_STRUCT|ERGO|ADV`), so all four epochs are\n  traversed in ~2h. The run was **reset** under v2 (old data archived as\n  `run/generations_v1_gameable.jsonl`).\n- **Finding.** On the Level-1 fixture the ergonomic epoch's token-min/serialize genes are\n  *neutral* \u2014 the honest optimum is already ~85 tokens, below the fitness resolution. Real\n  ergonomic gains need a larger fixture (the roadmap's Level-2 monorepo). Next: scale the\n  fixture, and/or enrich the genome (more axes) so 1000 generations has somewhere to go.\n\n## Update 2 \u2014 enriched (v3, autonomous)\n- **Genome enriched:** 5 axes / \u22643 alleles = **108 genomes**, and **alleles unlock by epoch**\n  (structural exposes basics; ergonomic+ unlocks `summary` surface, `ranged_hdr`, `compact`,\n  `cap_ctx`, `ranked` errors).\n- **Fixture level grows with the epoch:** L1 clean (structural) \u2192 **L2** big-file + many-changed\n  (ergonomic+), so the optimum **shifts** at gen 21 and evolution **re-adapts** \u2014 real dynamics\n  instead of a 3-generation plateau. Verified: fitness 1.903 \u2192 1.960, surface \u2192 `summary`.\n- **Fitness normalised** to `correctness + efficiency (+0.5\u00b7friction)`, multi-scenario\n  (small read / big read / missing / surface). Still ground-truth \u2014 `redteam.py` re-confirms\n  the cheater is defeated (honest 1.552 vs cheater 1.346).\n- **Open:** qwen friction is slightly noisy \u2192 memoize per-genome (elitism can wobble \u00b10.05);\n  L3 chaos + L4 history-churn fixtures are the next levels; genome can grow (paging/blame/stream).\n"
        },
        {
            "id": 9,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "packages/git_surface_mcp/README.md",
            "kind": "md",
            "body": "# git-surface-mcp\n\nAn **agent-ergonomic MCP git service** \u2014 the wrapper the evolutionary tournament\n(`../new_repo/packages/git_surface`) converged toward, materialised as a real, dependency-free\nMCP stdio server.\n\nTraditional git output is written for humans; an LLM agent burns context parsing noisy strings\nand hallucinates flags. This service inverts that with deep empathy for the containerised agent.\n\n## Tools\n| tool | returns |\n|---|---|\n| `inspect_git_surface(repo)` | branch \u00b7 short commit \u00b7 categorised changed paths (counts-only when large) \u2014 no raw `status`/`log` noise |\n| `pull_atomic_file(repo, path, start?, end?, max_tokens?)` | metadata header (lines/range/est_tokens) **then** content; missing path \u2192 **ranked fuzzy suggestions**; over `max_tokens` \u2192 content withheld + paging hint (never a silent context blow-up) |\n| `query_file_blame(repo, path, n?)` | commit count + last *n* touches (sha/date/subject), not the whole log |\n\n## Design principles (evolved, evidence-backed)\n- **Minimal token overhead** \u2014 files are atomic targets; metadata precedes content so the agent can page or abort.\n- **High atomic precision** \u2014 self-correcting error payloads (`did_you_mean`) let the agent self-heal without losing momentum.\n- **Structured, low-noise** \u2014 every response is a compact JSON object, not a wall of text.\n\n## Run\n```\npython -m git_surface_mcp            # MCP stdio server (JSON-RPC 2.0, newline-delimited)\npython tests/test_tools.py           # self-verifying tests (real git fixture)\n```\nStdlib only \u2014 no `mcp`/FastMCP dependency; `handle_message` is a pure function for testing.\n\n## Provenance\nDistilled from the git-surface tournament: structured/summary surface, ranged reads with a\ntoken header, and ranked fuzzy error self-heal were the traits the fitness function selected for.\nSee RFC-0028 (experimental) for the tournament method.\n"
        },
        {
            "id": 10,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "packages/spec_graph_mcp/README.md",
            "kind": "md",
            "body": "# spec-graph-mcp\n\nThe **RFC\u2192code provenance hub** the tournament + topology analysis predicted, materialised as a\nreal MCP service. It holds an **id\u2192node index** (the load-bearing hub the corpus organises around)\nbacked by a **content-hash cache** (so a rebuild re-scans only changed files and reports drift).\n\nBuilt on the shared framework primitives (`tournaments/arena.py`).\n\n## Tools\n| tool | returns |\n|---|---|\n| `surface` | overview: #requirements \u00b7 #linked \u00b7 #gaps \u00b7 top code hubs |\n| `link_requirement(req_id)` | the code nodes implementing a requirement (provenance); fuzzy `did_you_mean` on miss |\n| `gaps` | requirement ids with NO implementing code (compliance gaps) |\n| `atomic_read(path,start,end,max_tokens)` | file/range with a token header; withholds over budget |\n| `blame(path,n)` | compact churn summary |\n| `refresh` | re-scan via content-hash cache; returns files whose content drifted |\n\n## Run\n```\nSPECGRAPH_RFC=\"/path/SPEC.md\" SPECGRAPH_PKGS=\"/path/pkgA:/path/pkgB\" python -m spec_graph_mcp\npython tests/test_spec_graph.py     # self-verifying (temp fixture + drift)\n```\n\n## Provenance\nPredicted by the spec-ast-graph tournament (converged G3, F1 0.94, prec 1.0) and corroborated by\nthe corpus topology (id-citation edges are the low-resistance bridge; the hub is an id-indexed\nmodule). This class IS that prediction, made testable. See `tournaments/MANIFEST.md`.\n"
        },
        {
            "id": 11,
            "ts": 1784098241,
            "repo": "big-jazz",
            "path": "spec/README.md",
            "kind": "md",
            "body": "# new_repo \u2014 the enclosure (prototype)\n\nThe clean, from-scratch, born-instrumented, **contained** codebase that replaces the old rot.\nThis is the working prototype of the **Living Code-Graph** architecture specified in\n[`SPEC.md`](SPEC.md) \u2014 the \"enclosure\": the boundary that *holds* the code, *governs* who\ntouches it, and *watches* it.\n\n## The three pieces (and how they form the enclosure)\n\n| package | role | status |\n|---|---|---|\n| [`packages/code_pipeline`](packages/code_pipeline) | **Observability** \u2014 the born-instrumented execution-graph tracer (nodes = functions pinned to `(file, commit)`, edges = calls, every branch via `sys.monitoring`), into a new auto-timestamped DB. Retired + replaced the split-brained `dz_debug`. | built, 15/15 tests |\n| [`packages/routed_vm`](packages/routed_vm) | **The enclosure, physical** \u2014 a persistent OVS fabric + Incus instances + VNC desktop, in Python, systemd-backed (survives reboot). A contained, routed environment standing in for the logical enclosure until the object-model lands. | built, 4/4 tests, reboot-proven |\n| [`packages/wayback`](packages/wayback) | **Ground truth** \u2014 a read-only git\u00d7telemetry visualiser: what the codebase *is* over time vs what it *stubs against* (the anti-degeneration lens). | built |\n\n## The idea (see SPEC.md for the full normative version)\n- **Observe everything** (`code_pipeline`): degeneration becomes a visible diff, not a silent swap.\n- **Contain everything** (`routed_vm` + the tiers in SPEC): no agent is handed the whole spec or raw code \u2014 only its slice, via MCP.\n- Together: you can *see* the whole from the controller, while nothing can be *overwhelmed* by the whole.\n\n## Dev\n```\n~/code/.venv/bin/pip install -e packages/code_pipeline\npython packages/code_pipeline/tests/test_graph.py     # 15/15\npython packages/routed_vm/tests/test_routed_vm.py     # 4/4\n```\n\n## Provenance\nRefactored + generated 2026-07-01/02. `dz_debug` retired (its `Logger` folded into\n`code_pipeline.log`). Not a jazz package \u2014 its own tree, prototyping the monorepo shape (task #27).\n"
        },
        {
            "id": 12,
            "ts": 1784098241,
            "repo": "bootstrap_mcp",
            "path": "README.md",
            "kind": "md",
            "body": "# bootstrap-mcp (jazz-bootstrap)\n\nAn MCP server that kills the cold-start **\"adjustment period\"** for a fresh Claude Code running\ninside the jazz dev-shell sandbox. Just connecting orients the agent \u2014 the server's `instructions`\nland in the client's system prompt \u2014 and the tools verify the environment and point at the shared\nbrain (notes_db).\n\n## Tools\n- `orient()` \u2014 layout + conventions (local-first forge, jazz-push, soft-cap, permissions-first) + how to recall state.\n- `status()` \u2014 container?, tools present (docker/git/qemu/mksquashfs/jazz-push), notes_db reachability (tries `host.docker.internal:8001`), forge state (action count, registry/remotes/backups counts).\n- `memory()` \u2014 the host auto-memory `MEMORY.md` if the memory dir is mounted into the sandbox.\n- `checklist()` \u2014 ordered onboarding steps.\n\n## Wire it into the sandbox's Claude Code\nAdd to the sandbox `~/.claude.json` (or project `.mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"jazz-bootstrap\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"bootstrap_mcp\"],\n      \"env\": {\n        \"FORGE_HOME\": \"/work/forge\",\n        \"NOTES_DB_URL\": \"http://host.docker.internal:8001\",\n        \"JAZZ_MEMORY_DIR\": \"/work/memory\"\n      }\n    }\n  }\n}\n```\nThen a fresh agent's first move is `orient()` \u2192 `status()` \u2192 recall `build-v4`/`doc-v4`.\n\nConfig via env: `FORGE_HOME`, `NOTES_DB_URL`, `JAZZ_MEMORY_DIR`.\n"
        },
        {
            "id": 13,
            "ts": 1784098241,
            "repo": "bubble",
            "path": "docs/fulldocs.md",
            "kind": "md",
            "body": ""
        },
        {
            "id": 14,
            "ts": 1784098241,
            "repo": "bubble",
            "path": "modules/agent_guts/README.md",
            "kind": "md",
            "body": ""
        },
        {
            "id": 15,
            "ts": 1784098241,
            "repo": "bubble",
            "path": "modules/yaml_controls/README.md",
            "kind": "md",
            "body": ""
        },
        {
            "id": 16,
            "ts": 1784098241,
            "repo": "bubble",
            "path": "projects/yaml-controls-dev/README.md",
            "kind": "md",
            "body": ""
        },
        {
            "id": 17,
            "ts": 1784098241,
            "repo": "chain",
            "path": "README.md",
            "kind": "md",
            "body": "# Conductor Blockchain Ledger\n\nA local, tamper-evident **spine** for Conductor. Where `telemetry.db` is\nfast-and-local and `notes_db` is durable-and-shell-readable, the ledger is\n**immutable-and-ordered**: once a meaningful Conductor moment is anchored it\ncannot be silently altered or removed, and the whole history is a single\nhash-chained log you can verify with one call.\n\nIt runs on a **local Anvil node** (Foundry) \u2014 no real network, no gas cost, no\nkeys to protect. It is purely a local content-addressed + ordered attestation\nlayer, the on-chain twin of the signals jazz already produces.\n\n```\n  ./ledger.sh setup && ./ledger.sh deploy      # stand it all up\n  ./ledger.sh up                               # anvil+build+test+deploy+selftest\n  ./ledger.sh mcp                              # start the MCP server\n```\n\n---\n\n## Why a ledger (what it buys you)\n\nThe Conductor data-plane already **content-addresses** every volume snapshot\n(`volctl serialize` \u2192 sha256 + IPFS CID) and the control-plane already **signals**\nevery dispatch (`agent_status`) and every confirmation (`auth_gate`). Those\nrecords are mutable (sqlite, notes_db). The ledger adds the one property they\nlack: **immutability + global ordering**. After the fact you can prove:\n\n- *these exact bytes existed and were attested at block N* (provenance),\n- *this dispatch session opened, ran, and ended with this outcome* (sessions),\n- *this human approved this scoped decision, at this time* (gates),\n\nand that **none of it was edited after the fact** \u2014 the hash chain breaks if any\nentry is changed.\n\n---\n\n## Architecture\n\n```\n                         \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n   data-plane            \u2502            ~/code/chain (Foundry)         \u2502\n   volctl serialize \u2500\u2510   \u2502                                           \u2502\n   (sha256 + CID)    \u2502   \u2502   Provenance.sol   \u2500\u2500 content anchors     \u2502\n                     \u2502   \u2502   Sessions.sol     \u2500\u2500 dispatch lifecycle  \u2502\n   control-plane     \u251c\u2500\u2500\u25b6\u2502   ConductorLedger  \u2500\u2500 hash-chained log +  \u2502\n   coordinator       \u2502   \u2502                       registry (knows the \u2502\n   worker.spawn/     \u2502   \u2502                       other two addresses)\u2502\n   worker.finish     \u2502   \u2502                                           \u2502\n                     \u2502   \u2502            local Anvil :8545              \u2502\n   auth_gate         \u2502   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n   answer_gate \u2500\u2500\u2500\u2500\u2500\u2500\u2518                    \u25b2          \u25b2\n                                          \u2502          \u2502\n            jazz_telemetry.ledger  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518          \u2502   web3.py, fire-and-forget\n            (anchor_*, read_*, verify)                \u2502   degrades to a telemetry row\n                                                      \u2502\n            ledger_mcp (FastMCP)  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518   thin client over the lib\n```\n\n### The contracts (`src/`)\n\n| Contract | Anchors | Key |\n|---|---|---|\n| **`Provenance.sol`** | volctl artifacts: `sha256`, IPFS `cid`, `volume`, `mode`, `size` | `bytes32` sha256 (append-only set; duplicate sha rejected) |\n| **`Sessions.sol`** | coordinator dispatch: `task`, `model`, `agent`, `outcome` | `bytes32` session id; `open()` once \u2192 `close()` once |\n| **`ConductorLedger.sol`** | the **spine**: a hash-chained append-only log + a registry of the other two contracts; also where auth-gate **decisions** land | `seq` (each entry links `prevHash`\u2192`entryHash`) |\n\n`ConductorLedger` is the single address every consumer needs: it exposes\n`provenance()` and `sessions()` so the rest is discoverable, and `verifyChain()`\nwalks the log and returns the first broken link (or a sentinel if intact).\n\n### The Python lib (`jazz_telemetry/ledger/`)\n\nLives inside `jazz_telemetry` so every module that already does\n`from jazz_telemetry import telemetry` gets the ledger for free.\n\n- **`client.py`** \u2014 lazy, cached web3 connection; ABI loading (prefers the\n  Foundry `out/` build, falls back to bundled `ledger/abi/*.json`); zero-config\n  address discovery from `chain/deployments/<chainid>.json`.\n- **`anchor.py`** \u2014 the **fire-and-forget** write path. Every anchor drops a\n  local telemetry row first, then tries the chain; any failure (no web3, node\n  down, revert) is swallowed and recorded as a `*.fail` telemetry row. **Never\n  blocks, never raises** \u2014 exactly like `agent_status` / `auth_gate`.\n- **`read.py`** \u2014 the read / verification path. These **do** raise `LedgerError`\n  on an explicit problem (a reader that silently returns empty hides failures).\n\nPublic API (re-exported from `jazz_telemetry`):\n\n```python\nfrom jazz_telemetry import (\n    anchor_provenance, record_session_open, record_session_close,\n    anchor_gate, log_entry,                       # writes (fire-and-forget)\n    is_anchored, get_artifact, get_session,        # reads\n    ledger_count, ledger_entry, recent_entries, verify_chain,\n    chain_status, get_addresses,                   # status / discovery\n)\n```\n\n### The MCP server (`~/code/ledger_mcp/`)\n\nA thin FastMCP server \u2014 same shape as `notes_db_mcp` (thin client, returns\nJSON strings). Tools: `status`, `addresses`, `anchor_provenance`, `is_anchored`,\n`get_artifact`, `record_session_open`, `record_session_close`, `get_session`,\n`anchor_gate`, `log`, `log_count`, `recent`, `log_entry`, `verify_chain`.\n\nStart it: `./ledger.sh mcp` (or `python -m ledger_mcp` with `JAZZ_LEDGER_*` env).\n\n---\n\n## Integration points (the hooks already wired)\n\nAll three are **fire-and-forget and individually killable** \u2014 none can break the\nhost operation, and each respects an env switch.\n\n1. **volctl \u2192 provenance.** `volctl/core.py::serialize()` calls\n   `_anchor_provenance_safe()` right after it emits the `volume.serialize`\n   telemetry row, anchoring the **same** `(sha256, cid)`. Disable: `VOLCTL_LEDGER=0`.\n\n2. **coordinator \u2192 sessions.** `coordinator/dispatch.py` calls\n   `_ledger_session_open()` at the `worker.spawn` moment and\n   `_ledger_session_close()` at `worker.finish`, keyed by `<pkg>:<token.id>`.\n   Disable: `COORDINATOR_LEDGER=0`.\n\n3. **auth_gate \u2192 gate decisions.** `auth_gate.py::answer_gate()` anchors the\n   resolved decision (gate id, type, agent, response) on the ledger log the\n   moment a human answers. Disable: `JAZZ_GATE_LEDGER=0`.\n\nBecause the lib degrades to a telemetry row when the chain is absent, **these\nhooks are safe to ship before the chain is even deployed** \u2014 they simply no-op\nuntil `./ledger.sh deploy` has run.\n\n---\n\n## Configuration (env)\n\n| Var | Default | Meaning |\n|---|---|---|\n| `JAZZ_LEDGER` | `1` | `0` makes all anchors no-ops |\n| `JAZZ_LEDGER_RPC` | `http://127.0.0.1:8545` | Anvil RPC |\n| `JAZZ_LEDGER_KEY` | Anvil acct #0 | signing key (**local dev only**) |\n| `JAZZ_LEDGER_DIR` | `~/code/chain` | where `deployments/<id>.json` lives |\n| `JAZZ_LEDGER_ADDRESSES` | (discovery) | explicit address-book path override |\n\nThe default key is Anvil's well-known deterministic account #0 \u2014 it is a\n**public test key**, only ever used against the local node. Do not point this at\na real network.\n\n---\n\n## `ledger.sh` commands\n\n| Command | Does |\n|---|---|\n| `setup` | install Foundry, vendor `forge-std`, `pip install web3` into `.venv` |\n| `anvil` | start a background Anvil node on `:8545` (pid+log under `run/`) |\n| `build` | `forge build` |\n| `test` | `forge test -vv` (Solidity unit tests in `test/Ledger.t.sol`) |\n| `deploy` | start Anvil, deploy all three contracts, write the address book |\n| `mcp` | run the `ledger_mcp` FastMCP server (stdio) |\n| `selftest` | live Python E2E: anchor \u2192 read \u2192 verify the hash chain |\n| `status` | Anvil + deployment + `chain_status()` |\n| `stop` | stop the background Anvil node |\n| `up` | anvil + build + test + deploy + selftest (everything) |\n\n### Verify it works\n\n```bash\n./ledger.sh setup        # one-time: foundry + forge-std + web3\n./ledger.sh deploy       # starts anvil, deploys, writes deployments/31337.json\n./ledger.sh selftest     # anchors live, reads back, verifies the chain \u2192 PASSED\n./ledger.sh test         # the Solidity unit tests\n```\n\n`forge test` proves the contracts in isolation; `selftest` proves the whole\nPython \u2192 web3 \u2192 chain \u2192 read-back path against the deployed node.\n"
        },
        {
            "id": 18,
            "ts": 1784098241,
            "repo": "claude_tools",
            "path": "README.md",
            "kind": "md",
            "body": "# ~/.claude_tools \u2014 agent tooling, OUTSIDE project scope\n\nTools that must survive project deploys/redeploys and never be \"forgotten.\" Kept out of the project\ntree on purpose: a prior sbx deploy of core services was orphaned because tooling wasn't redirected\nand no telemetry was collected \u2014 this directory is the always-available fallback.\n\n## notesdb \u2014 notes + internal-telemetry store (server + client)\n\nA **stdlib-only** re-implementation of jazz-notes-db (no Docker, no fastapi/uvicorn/aiosqlite) so it\ncan't rot behind a missing venv or a down daemon. Split so the boundary is real, not decorative:\n\n- **`notesdbd.py` \u2014 the server. The single writer and the boundary.** The ONLY thing that touches the\n  SQL tables. It owns the schema + validation + invariants. Runs as a launchd service\n  (`com.claude.notesdbd`, `KeepAlive` \u2192 always-up) on `http://127.0.0.1:8002`. DB: `~/.claude_tools/notes.db`\n  (WAL; override `$NOTESDB_PATH`).\n- **`notesdb` (CLI) \u2014 a pure HTTP client.** Holds NO SQL; it never touches the tables. Writes are\n  `POST`, reads are `GET`. This is the point: clients (this CLI, sandboxed agents, services) all go\n  through the API, exactly like the read/write planes in `~/code/rebuild/SANDBOX-PLANES.md`.\n\n**Why not direct-write?** The HTTP layer *is* the boundary that stops any client editing the raw\ntables. A CLI that writes SQL directly would defeat it. Reliability (the \"can't be forgotten\"\nrequirement) is met by the **server being always-up** \u2014 and by a client-side **spool**: if the server\nis momentarily down, a write is appended to `~/.claude_tools/spool.jsonl` (a durable *outbox*, not the\nDB) and re-dispatched **through the server's validated path** on the next `flush`/successful write. No\nloss, no bypass.\n\nSchema is faithful to the original (`notes`, `telemetry`) + a free-form `events` table, so\n`backup_notes_db` exports stay restorable.\n\n```\nnotesdb event KIND [--source S] [--data '{json}'] [--text X]     # internal-telemetry event\nnotesdb add --title T --text X [--collection C] [--tags a,b]     # a note\nnotesdb ls [--collection C] [--tag t] | get ID | search Q | rm ID\nnotesdb events [--kind K] [--limit N]\nnotesdb telemetry log --package P [--exit-state S] [--elapsed F] ... | ls | stats\nnotesdb stats | flush | health          # flush drains the spool; --json goes BEFORE the subcommand\nnotesdb --json <cmd>\n```\n\nService control: `launchctl kickstart -k gui/$(id -u)/com.claude.notesdbd` (restart),\n`launchctl print gui/$(id -u)/com.claude.notesdbd` (status). Log: `~/.claude_tools/notesdbd.log`.\n"
        },
        {
            "id": 19,
            "ts": 1784098241,
            "repo": "cnotes",
            "path": "README.md",
            "kind": "md",
            "body": "# ~/.claude_tools \u2014 agent tooling, OUTSIDE project scope\n\nTools that must survive project deploys/redeploys and never be \"forgotten.\" Kept out of the project\ntree on purpose: a prior sbx deploy of core services was orphaned because tooling wasn't redirected\nand no telemetry was collected \u2014 this directory is the always-available fallback.\n\n## notesdb \u2014 notes + internal-telemetry store (server + client)\n\nA **stdlib-only** re-implementation of jazz-notes-db (no Docker, no fastapi/uvicorn/aiosqlite) so it\ncan't rot behind a missing venv or a down daemon. Split so the boundary is real, not decorative:\n\n- **`cnotesd.py` \u2014 the server. The single writer and the boundary.** The ONLY thing that touches the\n  SQL tables. It owns the schema + validation + invariants. Runs as a launchd service\n  (`com.claude.cnotesd`, `KeepAlive` \u2192 always-up) on `http://127.0.0.1:8002`. DB: `~/.claude_tools/notes.db`\n  (WAL; override `$NOTESDB_PATH`).\n- **`cnotes` (CLI) \u2014 a pure HTTP client.** Holds NO SQL; it never touches the tables. Writes are\n  `POST`, reads are `GET`. This is the point: clients (this CLI, sandboxed agents, services) all go\n  through the API, exactly like the read/write planes in `~/code/rebuild/SANDBOX-PLANES.md`.\n\n**Why not direct-write?** The HTTP layer *is* the boundary that stops any client editing the raw\ntables. A CLI that writes SQL directly would defeat it. Reliability (the \"can't be forgotten\"\nrequirement) is met by the **server being always-up** \u2014 and by a client-side **spool**: if the server\nis momentarily down, a write is appended to `~/.claude_tools/spool.jsonl` (a durable *outbox*, not the\nDB) and re-dispatched **through the server's validated path** on the next `flush`/successful write. No\nloss, no bypass.\n\nSchema is faithful to the original (`notes`, `telemetry`) + a free-form `events` table, so\n`backup_notes_db` exports stay restorable.\n\n```\ncnotes event KIND [--source S] [--data '{json}'] [--text X]     # internal-telemetry event\ncnotes add --title T --text X [--collection C] [--tags a,b]     # a note\ncnotes ls [--collection C] [--tag t] | get ID | search Q | rm ID\ncnotes events [--kind K] [--limit N]\ncnotes telemetry log --package P [--exit-state S] [--elapsed F] ... | ls | stats\ncnotes stats | flush | health          # flush drains the spool; --json goes BEFORE the subcommand\ncnotes --json <cmd>\n```\n\nService control: `launchctl kickstart -k gui/$(id -u)/com.claude.cnotesd` (restart),\n`launchctl print gui/$(id -u)/com.claude.cnotesd` (status). Log: `~/.claude_tools/notesdbd.log`.\n"
        },
        {
            "id": 20,
            "ts": 1784098241,
            "repo": "code",
            "path": "README.md",
            "kind": "md",
            "body": "# Vector Store\n\nA local RAG (Retrieval-Augmented Generation) agent with a web UI. Point it at a folder of documents, ask questions in plain English, and get answers grounded in your content \u2014 all running on your machine with no external API calls.\n\nBuilt on [`llm`](https://llm.datasette.io) + [`sqlite-utils`](https://sqlite-utils.datasette.io). Supports two backends:\n\n- **Ollama** \u2014 runs models locally via [Ollama](https://ollama.com)\n- **LM Studio** \u2014 runs models locally via [LM Studio](https://lmstudio.ai)\n\n---\n\n## How it works\n\n1. **Ingest** \u2014 `ingest.py` crawls a directory of documents, splits them into chunks, embeds each chunk, and stores the vectors in a local SQLite database.\n2. **Query** \u2014 `agent.py` (or the web UI) takes your question, finds the most relevant chunks via similarity search, and passes them as context to a local LLM to generate an answer.\n3. **Web UI** \u2014 `server.py` runs a Flask web server that wraps the same query and ingest logic behind a browser-based interface on `http://localhost:8080`.\n\n---\n\n## Prerequisites\n\n- **Python 3.10+**\n- One of the following model backends running locally:\n\n### Ollama\n\nInstall [Ollama](https://ollama.com/download), then pull the required models:\n\n```bash\nollama pull nomic-embed-text   # embedding model\nollama pull llama3.2           # generation model (or any other)\n```\n\nSet `BACKEND` to `\"ollama\"` in `source/config.json`.\n\n### LM Studio\n\nInstall [LM Studio](https://lmstudio.ai), load your models, and enable the local server (default: `http://localhost:1234`). You need one model for embeddings and one for generation \u2014 `nomic-embed-text-v1.5` and any chat model work well.\n\nSet `BACKEND` to `\"lmstudio\"` in `source/config.json` and update `LMSTUDIO_EMBEDDING_MODEL` and `LMSTUDIO_LLM_MODEL` to match what you have loaded.\n\n---\n\n## Installation\n\nThe project ships with an installer that handles everything \u2014 including downloading `uv` if you don't have it.\n\n```bash\nbash install.sh\n```\n\nThat will:\n1. Install [`uv`](https://github.com/astral-sh/uv) if it isn't already on your PATH\n2. Create a `.venv` virtual environment inside this directory\n3. Install all Python dependencies into it\n\nOnce it finishes, activate the environment:\n\n```bash\nsource .venv/bin/activate\n```\n\n### Manual install (without the script)\n\n```bash\npip install uv                          # or: brew install uv\nuv venv .venv\nsource .venv/bin/activate\nuv pip install -r source/requirements.txt\n```\n\n---\n\n## Usage\n\n### Web UI (recommended)\n\n```bash\nsource .venv/bin/activate\ncd source\npython ingest.py   # index your documents first\npython server.py   # starts at http://localhost:8080\n```\n\nOpen `http://localhost:8080` in your browser. The sidebar shows your active backend and model configuration. Type a question and press **Ask** or hit Enter.\n\n### Command-line agent\n\n```bash\nsource .venv/bin/activate\ncd source\npython ingest.py   # index your documents first\npython agent.py    # interactive prompt in the terminal\n```\n\n```\nRAG Agent ready\n  Model:      gemma-4-26b-a4b (LM Studio)\n  Embeddings: nomic-embed-text-v1.5 (LM Studio)\n  Collection: documents\n\nYou: What are the key findings in the report?\n\nThinking...\n\nAgent: Based on the provided documents, the key findings are...\n\nYou: quit\nGoodbye.\n```\n\nType `quit`, `exit`, or `q` to stop.\n\n### Adding documents\n\nDrop files into `source/input/` then run `ingest.py`:\n\n```bash\nmkdir -p source/input\ncp path/to/your/docs/* source/input/\ncd source && python ingest.py\n```\n\nSupported formats: `.txt`, `.md`, `.py`, `.json`, `.csv`, `.html`, and any other UTF-8 text file. Binary files are skipped automatically.\n\n### Re-indexing\n\nIf you change `CHUNK_SIZE`, switch backends, or add/remove documents, re-index from scratch:\n\n```bash\ncd source\npython reindex.py\n```\n\n---\n\n## Configuration\n\nAll settings live in `source/config.json`. Set `BACKEND` to `\"ollama\"` or `\"lmstudio\"`, then fill in the matching model names.\n\n### Ollama settings\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `BACKEND` | `\"ollama\"` | Set to `\"ollama\"` to use Ollama |\n| `BASE_URL` | `\"http://127.0.0.1:11434\"` | Ollama server address |\n| `EMBEDDING_MODEL` | `\"nomic-embed-text\"` | Ollama embedding model (must be pulled) |\n| `LLM_MODEL` | `\"llama3.2\"` | Ollama generation model (must be pulled) |\n\n### LM Studio settings\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `BACKEND` | `\"ollama\"` | Set to `\"lmstudio\"` to use LM Studio |\n| `LMSTUDIO_BASE_URL` | `\"http://localhost:1234/v1\"` | LM Studio server address |\n| `LMSTUDIO_EMBEDDING_MODEL` | `\"nomic-embed-text-v1.5\"` | Embedding model loaded in LM Studio |\n| `LMSTUDIO_LLM_MODEL` | `\"local-model\"` | Generation model loaded in LM Studio |\n\n### Shared settings\n\n| Key | Default | Description |\n|-----|---------|-------------|\n| `SOURCE_FOLDER` | `\"input\"` | Directory to crawl for documents (relative to `source/`) |\n| `COLLECTION_NAME` | `\"documents\"` | Name of the embedding collection in SQLite |\n| `DB_PATH` | `\"./cache/embeddings.db\"` | Path to the SQLite database (relative to `source/`) |\n| `CHUNK_SIZE` | `4000` | Characters per chunk |\n| `CHUNK_OVERLAP` | `400` | Overlap between consecutive chunks |\n| `TOP_K` | `5` | Number of chunks retrieved per query |\n\n---\n\n## Project structure\n\n```\nvector-store/\n\u251c\u2500\u2500 install.sh              # uv-based installer\n\u251c\u2500\u2500 source/\n\u2502   \u251c\u2500\u2500 server.py           # Flask web server (port 8080)\n\u2502   \u251c\u2500\u2500 agent.py            # Interactive RAG agent (CLI)\n\u2502   \u251c\u2500\u2500 backends.py         # Ollama and LM Studio backend adapters\n\u2502   \u251c\u2500\u2500 ingest.py           # Document ingestion pipeline\n\u2502   \u251c\u2500\u2500 reindex.py          # Clear and re-ingest from scratch\n\u2502   \u251c\u2500\u2500 crawl.py            # Recursive directory crawler\n\u2502   \u251c\u2500\u2500 file_collection.py  # File collection with deduplication\n\u2502   \u251c\u2500\u2500 file_wrapper.py     # Per-file metadata and checksums\n\u2502   \u251c\u2500\u2500 config.json         # Configuration\n\u2502   \u251c\u2500\u2500 requirements.txt    # Python dependencies\n\u2502   \u251c\u2500\u2500 static/             # Web UI assets (HTML + json-control library)\n\u2502   \u251c\u2500\u2500 input/              # Put your documents here (git-ignored)\n\u2502   \u2514\u2500\u2500 cache/              # SQLite database lives here (git-ignored)\n\u2514\u2500\u2500 test/\n    \u251c\u2500\u2500 test_crawl.py\n    \u251c\u2500\u2500 test_file_collections.py\n    \u251c\u2500\u2500 test_file_meta_data.py\n    \u2514\u2500\u2500 test_file_wrapper.py\n```\n\n---\n\n## Running tests\n\n```bash\nsource .venv/bin/activate\ncd source\npython -m pytest ../test/\n```\n\n---\n\n## Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| [`flask`](https://flask.palletsprojects.com) | Web server for the browser UI |\n| [`llm`](https://llm.datasette.io) | Core embedding and generation interface |\n| [`llm-ollama`](https://github.com/taketwo/llm-ollama) | Ollama backend plugin for `llm` |\n| [`openai`](https://github.com/openai/openai-python) | LM Studio OpenAI-compatible API client |\n| [`sqlite-utils`](https://sqlite-utils.datasette.io) | SQLite database access for embedding storage |\n"
        },
        {
            "id": 21,
            "ts": 1784098241,
            "repo": "code__big-jazz",
            "path": "README.md",
            "kind": "md",
            "body": "# Conductor \u2014 super-repo\n\nOne git repository holding every package, consolidated from the previously scattered nested repos under `test_project/`. Source-only, single history.\n\n## Layout\n- `packages/` \u2014 the shippable packages (codebean_mcp, code_pipeline, git_surface[_mcp], routed_vm, spec_graph_mcp, wayback).\n- `tools/` \u2014 supporting tools (unispec, spec_ast_graph, tournaments, vmctl_web, \u2026).\n- `spec/` \u2014 the requirement/spec apparatus (SPEC.md, decompose, sections/slices).\n\nThe codebean crank + generative solve pipeline lives in `packages/codebean_mcp/prototype/`.\n"
        },
        {
            "id": 22,
            "ts": 1784098241,
            "repo": "code__big-jazz",
            "path": "packages/code_pipeline/README.md",
            "kind": "md",
            "body": "# code_pipeline\n\nThe Conductor **execution-provenance graph tracer** \u2014 the \"debug operator\" (DO) from the\nLiving Code-Graph spec (CM/DO/PS/GC), rebuilt clean.\n\n## Why this exists (not a fix \u2014 a replacement)\n`dz_debug` is **split-brained**: three folders on disk all named `dz_debug` (a good 269-line\nDB-backed tracer, a weak 42-line RAM-only one, and stale vendored copies), plus a\n`find_packages()` + same-name-project-folder trap that makes `import dz_debug` resolve to an\nempty namespace shell. So `from dz_debug import debug_decorator` \u2014 stamped onto every function\nby codebean \u2014 resolves to nothing, and the calling class was never recorded.\n\nWe are **not** untangling that rot. `code_pipeline` is a new name, a new source tree, rebuilt\nfrom the spec, with a **src-layout** so the outer-name shadow is structurally impossible.\n\n## What it does (spec IDs)\n- **DO-1** call graph: nodes `{handle, guid=uuid5(file:qualname:commit), file, commit}`, real\n  caller\u2192callee edges (contextvars call-stack), variable snapshots, run/trace scoping.\n- **DO-2** every branch point via `sys.monitoring` (loops aggregated by count \u2014 loops-above).\n- **PS-1..5**: a NEW, dedicated, auto-timestamped DB (`$CODE_PIPELINE_DB`, default\n  `~/code/forge/code_pipeline.db`); in-memory hot path \u2192 serialise on function stop;\n  FULL collection with backpressure (never a silent drop); not grandfathered onto telemetry.db.\n- Node `commit` joins the wayback git lineage; the runtime trace is a traversal of the static graph.\n\n## Use\n```python\nfrom code_pipeline import trace, new_run, edges, branches\nnew_run(task=\"my run\")\n@trace\ndef f(x): ...\n```\n\n## Env\n- `CODE_PIPELINE_DB` \u2014 trace DB path (default `~/code/forge/code_pipeline.db`)\n- `CODE_PIPELINE_REPR_LIMIT` (2000) \u00b7 `CODE_PIPELINE_QUEUE_MAX` (20000) \u00b7 `CODE_PIPELINE_BRANCHES` (1)\n\n## Test\n```\n~/code/.venv/bin/python tests/test_graph.py     # standalone, or: python -m pytest tests/\n```\n"
        },
        {
            "id": 23,
            "ts": 1784098241,
            "repo": "code__big-jazz",
            "path": "packages/codebean_mcp/README.md",
            "kind": "md",
            "body": "# codebean-mcp\n\nAn MCP that lets an LLM **author code as an in-memory model** \u2014 packages, classes, functions \u2014\n**without touching files or git**. The model is the \"bean\"; `save()` materializes + commits behind\nthe scenes. The point is the **focused sub-mind**: it works on code structure and reads it via\n`render()`, never distracted by disk, paths, or branches.\n\n## Tools\n- `new_module(name)`\n- `add_class(module, name, bases, doc)`\n- `add_function(target, name, params, body, doc, decorators)` \u2014 target = `module` or `module.Class` (self inserted for methods)\n- `set_body(target, body)` \u2014 `module.func` or `module.Class.method`\n- `render(module?)` \u2014 read the generated source\n- `tree()` \u2014 structure (modules \u2192 classes/methods/functions)\n- `save(message)` \u2014 persist (materialize + git commit; **git is concealed** \u2014 you just describe the change)\n\nConfig: `CODEBEAN_ROOT` (hidden workspace, default `~/.codebean/work`), `CODEBEAN_PROJECT`.\nGenerated source is valid Python (verified by `compile()` in tests).\n"
        },
        {
            "id": 24,
            "ts": 1784098241,
            "repo": "code__big-jazz",
            "path": "packages/git_surface/README.md",
            "kind": "md",
            "body": "# git-surface \u2014 agent-ergonomic git wrapper, evolved\n\nA real meta-evolutionary tournament that evolves an MCP-style git-surface wrapper toward\nminimal-friction, token-efficient, self-correcting tools for LLM agents.\n\n## Files\n- `gen1.py` \u2014 the seed: three tools (surface / atomic-read / blame) + the first real\n  tournament (naive vs evolved) scored on deterministic fitness. `python3 gen1.py`.\n- `evolve_step.py` \u2014 **one generation per invocation** (a stateless ratchet): mutate the\n  baseline (epoch-gated vectors) \u2192 evaluate the population on **deterministic fitness +\n  a live qwen friction judge** \u2192 elitist k-tournament select \u2192 persist. Bounded at gen 1000.\n- `run/state.json` \u2014 current generation + baseline genome.\n- `run/generations.jsonl` \u2014 append-only log, one line per generation (the real fitness curve).\n- `run/cron.log` \u2014 stdout of the scheduled runs.\n\n## The scheduled run (live)\nInstalled on system crontab, every 5 minutes:\n```\n*/5 * * * * PATH=/opt/homebrew/bin:/usr/bin:/bin /opt/homebrew/bin/python3 \\\n  .../git_surface/evolve_step.py >> .../git_surface/run/cron.log 2>&1 # git-surface-evolve\n```\n**Kill switch:** `crontab -l | grep -v git-surface-evolve | crontab -`\n\n## The qwen friction judge\nReal, local, free: `qwen/qwen3-coder-30b` via LM Studio's OpenAI server at\n`http://localhost:1234/v1` (started with `lms server start`). Each generation asks qwen to\nrate how low-friction a genome's tool responses are (0..1). **If LM Studio's server stops,**\nthe friction term degrades to a neutral 0.5 (`friction_src=qwen_unavailable`) and evolution\ncontinues on deterministic fitness \u2014 the cron never dies. Re-enable real scores with\n`lms server start`.\n\n## Epoch schedule (per the roadmap)\n- **1\u2013150 structural** \u2014 surface/read/error correctness. Converges fast to fitness \u2248 2.34\n  (structured surface + ranged read + fuzzy self-heal), then holds (elitism = no regression).\n- **151\u2013450 ergonomic** \u2014 unlocks `serialize` (compact) + `token_min` heuristics.\n- **451\u2013750 adversarial** / **751\u20131000 convergence** \u2014 all vectors active.\n  (Note: at the 5-min cadence, the ergonomic epoch unlocks ~gen 151 \u2248 12h in. To see gains\n  sooner, shrink the epoch bounds in `epoch_axes()` or lower the cron interval floor.)\n\n## Watch it\n```\ntail -f run/generations.jsonl        # live fitness curve\npython3 -c \"import json;[print(json.loads(l)['gen'],json.loads(l)['fitness']) for l in open('run/generations.jsonl')]\"\n```\nTelemetry: component `git-surface-evolve` in `~/code/forge/telemetry.db`.\n\n## Update \u2014 red-teamed + condensed (authorized)\n- **Fitness hardened (`score_responses`, v2).** `redteam.py` proved the original substring\n  correctness was **gameable**: a cheater emitting only the magic words scored 1.977 vs the\n  honest 1.932 by farming the token-thrift term. v2 requires the read to contain the **actual\n  file lines verbatim** + the surface to reflect **real git state** \u2192 cheater collapses to\n  1.477, honest holds 1.932 (defended by 0.455). Run `python3 redteam.py` to re-verify.\n- **Intervals condensed.** Cron cadence `*/5` \u2192 **`* * * * *` (1 min)**; epoch bounds\n  condensed to **20 / 60 / 120** (env `GS_EP_STRUCT|ERGO|ADV`), so all four epochs are\n  traversed in ~2h. The run was **reset** under v2 (old data archived as\n  `run/generations_v1_gameable.jsonl`).\n- **Finding.** On the Level-1 fixture the ergonomic epoch's token-min/serialize genes are\n  *neutral* \u2014 the honest optimum is already ~85 tokens, below the fitness resolution. Real\n  ergonomic gains need a larger fixture (the roadmap's Level-2 monorepo). Next: scale the\n  fixture, and/or enrich the genome (more axes) so 1000 generations has somewhere to go.\n\n## Update 2 \u2014 enriched (v3, autonomous)\n- **Genome enriched:** 5 axes / \u22643 alleles = **108 genomes**, and **alleles unlock by epoch**\n  (structural exposes basics; ergonomic+ unlocks `summary` surface, `ranged_hdr`, `compact`,\n  `cap_ctx`, `ranked` errors).\n- **Fixture level grows with the epoch:** L1 clean (structural) \u2192 **L2** big-file + many-changed\n  (ergonomic+), so the optimum **shifts** at gen 21 and evolution **re-adapts** \u2014 real dynamics\n  instead of a 3-generation plateau. Verified: fitness 1.903 \u2192 1.960, surface \u2192 `summary`.\n- **Fitness normalised** to `correctness + efficiency (+0.5\u00b7friction)`, multi-scenario\n  (small read / big read / missing / surface). Still ground-truth \u2014 `redteam.py` re-confirms\n  the cheater is defeated (honest 1.552 vs cheater 1.346).\n- **Open:** qwen friction is slightly noisy \u2192 memoize per-genome (elitism can wobble \u00b10.05);\n  L3 chaos + L4 history-churn fixtures are the next levels; genome can grow (paging/blame/stream).\n"
        },
        {
            "id": 25,
            "ts": 1784098241,
            "repo": "code__big-jazz",
            "path": "packages/git_surface_mcp/README.md",
            "kind": "md",
            "body": "# git-surface-mcp\n\nAn **agent-ergonomic MCP git service** \u2014 the wrapper the evolutionary tournament\n(`../new_repo/packages/git_surface`) converged toward, materialised as a real, dependency-free\nMCP stdio server.\n\nTraditional git output is written for humans; an LLM agent burns context parsing noisy strings\nand hallucinates flags. This service inverts that with deep empathy for the containerised agent.\n\n## Tools\n| tool | returns |\n|---|---|\n| `inspect_git_surface(repo)` | branch \u00b7 short commit \u00b7 categorised changed paths (counts-only when large) \u2014 no raw `status`/`log` noise |\n| `pull_atomic_file(repo, path, start?, end?, max_tokens?)` | metadata header (lines/range/est_tokens) **then** content; missing path \u2192 **ranked fuzzy suggestions**; over `max_tokens` \u2192 content withheld + paging hint (never a silent context blow-up) |\n| `query_file_blame(repo, path, n?)` | commit count + last *n* touches (sha/date/subject), not the whole log |\n\n## Design principles (evolved, evidence-backed)\n- **Minimal token overhead** \u2014 files are atomic targets; metadata precedes content so the agent can page or abort.\n- **High atomic precision** \u2014 self-correcting error payloads (`did_you_mean`) let the agent self-heal without losing momentum.\n- **Structured, low-noise** \u2014 every response is a compact JSON object, not a wall of text.\n\n## Run\n```\npython -m git_surface_mcp            # MCP stdio server (JSON-RPC 2.0, newline-delimited)\npython tests/test_tools.py           # self-verifying tests (real git fixture)\n```\nStdlib only \u2014 no `mcp`/FastMCP dependency; `handle_message` is a pure function for testing.\n\n## Provenance\nDistilled from the git-surface tournament: structured/summary surface, ranged reads with a\ntoken header, and ranked fuzzy error self-heal were the traits the fitness function selected for.\nSee RFC-0028 (experimental) for the tournament method.\n"
        }
    ]
}