@roulabs/mx 1.0.2 → 1.1.1

package/bin/mx.js

@@ -78,6 +78,15 @@ function removeStaleRuntimeReadme(targetDir) {
   }
   return false;
 }
+function stampContextIndex(targetDir, templatesDir2) {
+  const dest = path2.join(targetDir, "context", "INDEX.json");
+  if (exists(dest)) return null;
+  const src = path2.join(templatesDir2, "context", "INDEX.json");
+  if (!exists(src)) throw new MxError(`missing template: ${src}`, "NO_TEMPLATE");
+  fs3.mkdirSync(path2.dirname(dest), { recursive: true });
+  fs3.copyFileSync(src, dest);
+  return dest;
+}
 
 // ../../packages/core/src/runtime.ts
 var DEFAULT_RUNTIME = path3.join(os.homedir(), "mx");
@@ -153,13 +162,18 @@ function initRuntime(target0, templatesDir2) {
     created.push(marker);
   }
   created.push(stampClaudeMd(target, templatesDir2));
+  const ctxIndex = stampContextIndex(target, templatesDir2);
+  if (ctxIndex) created.push(ctxIndex);
   removeStaleRuntimeReadme(target);
   return { runtime: target, created };
 }
 function updateRuntime(root, templatesDir2) {
   const dest = stampClaudeMd(root, templatesDir2);
+  const updated = [dest];
+  const ctxIndex = stampContextIndex(root, templatesDir2);
+  if (ctxIndex) updated.push(ctxIndex);
   removeStaleRuntimeReadme(root);
-  return { runtime: root, updated: [dest] };
+  return { runtime: root, updated };
 }
 
 // ../../packages/core/src/repos.ts
@@ -619,7 +633,10 @@ works (${data.works.length}):`);
     case "update": {
       const root = requireRuntime({ runtime: flags.runtime });
       const res = updateRuntime(root, templatesDir());
-      emit(() => console.log(`Re-stamped CLAUDE.md into ${res.runtime}`), res);
+      emit(() => {
+        console.log(`Updated runtime at ${res.runtime}`);
+        for (const p of res.updated) console.log(`  + ${p}`);
+      }, res);
       return;
     }
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roulabs/mx",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "mx — run several features in parallel across shared repos using git worktrees",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -31,6 +31,9 @@ here to change how mx works, you're in the wrong place: switch to that repo. Don
 mx/
 ├── CLAUDE.md               # this file (installed by the mx CLI)
 ├── .mx-root                # empty marker: "this is the mx root"
+├── context/                # shared memory across all features (see § Context registry)
+│   ├── INDEX.json          # single source of truth — metadata for every entry
+│   └── <path>.md           # body-only entries; nested folders allowed
 ├── repos/                  # PRISTINE reference clones, each on its default branch
 │   ├── repo-a/
 │   └── repo-b/
@@ -72,6 +75,81 @@ mx/
 4. The work root is **not** a git repo. Run build/test/git commands from inside the relevant worktree.
 5. If several sessions share one work, the user gives each a lane (usually one repo). Stay in your lane.
 
+## Context registry — shared memory across every feature in this runtime
+
+`<runtime>/context/` is mx-owned institutional memory for this runtime — findings, decisions, runbooks, notes, debugging journeys, RCAs, session summaries, project-local procedures, imported reference material, anything worth carrying across sessions. mx stamps a starter `INDEX.json` at init; everything after that is yours to shape.
+
+### Two-file design
+
+- **`INDEX.json`** — the **single source of truth** for all entry metadata. JSON array.
+- **Body files** at `<runtime>/context/<path>.md` — **only the prose**. No frontmatter, no in-file header. To know what an entry is about, look up its `path` in INDEX.
+
+### INDEX.json schema
+
+Top-level JSON array of entry objects. The schema is **closed** — these fields, these types, nothing else. Adding ad-hoc fields will drift across sessions; don't.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `path` | `string` | yes | **The unique identifier.** Kebab-case segments separated by `/`. No `.md` extension. Regex: `^[a-z0-9-]+(/[a-z0-9-]+)*$`. File lives at `<runtime>/context/<path>.md`. |
+| `description` | `string` | yes | 1–3 sentences covering (a) the gist / key claim, (b) where in the system it applies, (c) when this entry is relevant — enough to decide *whether to open the body* without actually opening it. |
+| `type` | `string` | no | Free-form label. Suggested vocabulary: `fact`, `decision`, `runbook`, `note`, `skill`. |
+| `tags` | `string[]` | no | Free-form tag strings. |
+| `related` | `string[]` | no | Each item is another entry's `path`. |
+| `last_verified` | `string` | no | ISO date `YYYY-MM-DD`. Use for entries where freshness matters. |
+
+Example entry:
+
+```json
+{
+  "path": "auth/tokens",
+  "description": "Session tokens are namespaced by tenant_id, 30-day expiry, rotated on password or role change. Validation happens at the edge in middleware/auth.go before any handler runs. Read when touching multi-tenant request handling, session lifecycle, or token storage.",
+  "type": "fact",
+  "tags": ["auth", "security"],
+  "related": ["auth/tenant-isolation"],
+  "last_verified": "2026-06-05"
+}
+```
+
+### Reading
+
+Primary path:
+
+1. Read `<runtime>/context/INDEX.json` — every entry's metadata in one Read.
+2. Open files at `<runtime>/context/<path>.md` for entries whose metadata matches the current task.
+
+When INDEX descriptions don't surface what you need — and often they won't — fall back to anything that works:
+
+- **Grep `<runtime>/context/`** for keywords. Frequently the term you need lives in a body, not in any description.
+- **`ls` the folder recursively** to spot entries on disk that aren't indexed (orphans), and read them directly when relevant.
+- **Follow `related` chains** outward from a known-relevant entry to find the rest of a cluster.
+- **Read everything** if the registry is small (< ~30 entries) and you're starting unfamiliar work — cheaper than guessing.
+
+INDEX is the *primary* discovery surface, not the only one. Use whatever gets you to the right entry fastest — direct grep, full-content scan, recursive read, following links, your judgment.
+
+A 30-second skim of INDEX is free; do it before any non-trivial task. Skip only for typo-fix-level work.
+
+### Maintain INDEX.json as you go
+
+When you add, rename, remove, or restructure an entry, update INDEX in the same change. Drift means orphan files (invisible to future sessions) or stale entries (false positives). After editing INDEX, sanity-check it parses as valid JSON.
+
+### Organize as much as you can
+
+- **Nest by subject** — `infra/cell/guide`, `auth/tokens`, `payments/stripe/webhook-quirks`. Match the domain's natural divisions.
+- **One concept per file.** If you can't fit the gist + scope + when-relevant into a 1–3 sentence `description`, the file is doing too much — split it. Aim for ≤ ~200 lines per body file; line count is just a tripwire that flags "look closer." When in doubt, factor the shared concept out into its own entry and `related`-link from the children.
+- **Cross-link via `related` in INDEX**, not in body content.
+
+### When and what to write
+
+Three triggers for new entries:
+
+1. **When the user asks.** "Save this," "remember this," "add to context" — write the entry immediately and update INDEX.
+2. **When you make a non-obvious discovery during the session.** A root cause you traced, a system invariant you confirmed, a decision reached together, a gotcha that tripped you up — propose inline: *"This seems worth saving — add it as `<path>` with this description? OK?"* Write only after the user confirms.
+3. **Before ending a substantial session.** Review what was learned and propose 1–3 entries the user can approve. Catches durable findings you didn't surface mid-stream.
+
+For ephemeral scratch (a debugging journey in progress, a hypothesis you're testing) — write without asking. It's notes; promote or delete later.
+
+**What's worth writing:** rationale, history, gotchas, cross-system invariants, debugging journeys, RCAs, session summaries, project-local procedures, imported reference material — your call. When in doubt, save it; prune later.
+
 ## How to do things (always via mx)
 
 You are launched from the work folder, so you can **omit `-n <feature>`** — mx infers the work from

package/templates/context/INDEX.json

@@ -0,0 +1 @@
+[]