@jossuealcala/madre 0.2.3 → 0.3.1

package/src/event-store.mjs

@@ -1,4 +1,4 @@
-import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -120,6 +120,34 @@ export class EventStore {
     throw new Error(`Timed out waiting for event store lock: ${this.#file}`);
   }
 
+  // Rewrites every event through `transform` (which returns the event to keep, changed or
+  // not), atomically, under the lock, in the same order and with the same sequences. The
+  // ledger is append-only for the room; this is the human's hand on it, used by the privacy
+  // purge. Appends queued behind it see the new file.
+  rewrite(transform) {
+    const operation = async () => {
+      const release = await this.#acquireLock();
+      try {
+        const existing = await this.#readAllUnlocked();
+        let changed = 0;
+        const next = existing.map((event) => {
+          const out = transform(event) ?? event;
+          if (out !== event) changed += 1;
+          return out;
+        });
+        const temp = `${this.#file}.rewrite-${process.pid}`;
+        await writeFile(temp, next.map((event) => JSON.stringify(event)).join('\n') + (next.length ? '\n' : ''));
+        await rename(temp, this.#file);
+        this.#nextSequence = (next.at(-1)?.sequence ?? 0) + 1;
+        return { total: next.length, changed };
+      } finally {
+        await release();
+      }
+    };
+    this.#writeQueue = this.#writeQueue.then(operation, operation);
+    return this.#writeQueue;
+  }
+
   append(type, payload) {
     const operation = async () => {
       const release = await this.#acquireLock();

package/src/extensions.mjs

@@ -1,227 +1,27 @@
-import { execFile, spawn } from 'node:child_process';
-import { access, readFile, realpath } from 'node:fs/promises';
-import { delimiter, join, resolve } from 'node:path';
-import { promisify } from 'node:util';
-
-const execFileAsync = promisify(execFile);
-
-// Optional room modules. Built-ins only change MADRE's local configuration;
-// the external AHP+ installer can write into the selected project, so it
-// requires explicit confirmation and records that action in the durable log.
-
-async function readJson(path) {
-  try {
-    return JSON.parse(await readFile(path, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-// AHP+ platform names for the agents MADRE knows about. Gemini has no AHP+
-// adapter yet, so it is simply not requested.
-const AHP_PLATFORMS = { codex: 'codex', claude: 'claude', opencode: 'opencode' };
-
-// Where does git think this project lives? AHP+ pins itself to the git root,
-// so a project inside a bigger repository (or a home directory that was
-// accidentally `git init`ed) would receive .ahp/ somewhere else entirely.
-export async function gitToplevel(projectRoot) {
-  try {
-    const { stdout } = await execFileAsync('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel'], { timeout: 5000 });
-    return await realpath(stdout.trim()).catch(() => stdout.trim());
-  } catch {
-    return null;
-  }
-}
-
-export async function findOnPath(name, envPath = process.env.PATH ?? '') {
-  for (const directory of envPath.split(delimiter).filter(Boolean)) {
-    const candidate = join(directory, name);
-    if (await access(candidate).then(() => true, () => false)) return candidate;
-  }
-  return null;
-}
-
-export const EXTENSIONS = [
-  {
-    id: 'ahp',
-    name: 'AHP+',
-    vendor: 'Agent Handoff Protocol Plus',
-    package: '@jossuealcala/ahp-plus',
-    version: '1.4.1',
-    summary: 'Verified project state, checkpoints and handoffs between AI sessions, stored in .ahp/ next to your code.',
-    creates: ['.ahp/ with manifest, sessions, handoffs and evidence', 'a project-local pin of @jossuealcala/ahp-plus', 'IDE adapter files for the detected agents'],
-    async detect(projectRoot) {
-      const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));
-      if (!manifest) return { installed: false };
-      const pinned = await readJson(join(projectRoot, 'node_modules', '@jossuealcala', 'ahp-plus', 'package.json'));
-      return {
-        installed: true,
-        version: pinned?.version ?? null,
-        protocolVersion: manifest.protocol_version ?? null,
-        projectId: manifest.project_id ?? null,
-        detail: [pinned?.version ? `cli ${pinned.version}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
-      };
-    },
-    // Refuses before anything is written when the outcome would be wrong.
-    async preflight(projectRoot, { toplevel = gitToplevel, npx = findOnPath } = {}) {
-      const root = await realpath(projectRoot).catch(() => resolve(projectRoot));
-      const problems = [];
-      if (!(await npx('npx'))) problems.push('npx is not on PATH for the MADRE server; start MADRE from a terminal where `npx --version` works.');
-      const top = await toplevel(root);
-      if (!top) {
-        problems.push('The project is not a git repository. AHP+ pins itself to the git root: run `git init` in the project first.');
-      } else if (top !== root) {
-        problems.push(`The project's git root is ${top}, not the project itself. AHP+ would install there. Run \`git init\` inside the project, or remove the stray repository at ${top}.`);
-      }
-      return { ok: problems.length === 0, problems, gitRoot: top };
-    },
-    installCommand({ agents = [] }) {
-      const platforms = agents
-        .filter((agent) => agent.detected && AHP_PLATFORMS[agent.id])
-        .map((agent) => AHP_PLATFORMS[agent.id]);
-      const args = ['--yes', `${this.package}@${this.version}`, 'setup', '.'];
-      if (platforms.length) args.push('--platforms', platforms.join(','));
-      return { command: 'npx', args, platforms, display: ['npx', ...args].join(' ') };
-    },
-  },
-];
-
-// Built-in module: no project write, no npm. "Installing" it enables MADRE's own
-// MCP image server for the CLIs that cannot generate images natively.
-export const IMAGE_STUDIO = {
-  id: 'image-studio',
-  kind: 'builtin',
-  name: 'Image Studio',
-  vendor: 'MADRE · Gemini API',
-  package: null,
-  version: '0.1.0',
-  summary: 'Gives Gemini CLI, Claude Code and OpenCode an image-generation tool through a MADRE-owned MCP server on the Gemini API image models, using your own Gemini key and credits. Attached only inside a creation lease with the image scope on.',
-  creates: ['nothing in the project: images land in the lease directory like any artifact', 'an "image-studio" entry in ~/.pulse/config.json', 'an MCP server process per turn, started and stopped by the CLI'],
-  requires: ['a Gemini API key with credits (the key the Gemini CLI stores, or GEMINI_API_KEY)'],
-  models: ['gemini-2.5-flash-image', 'gemini-3.1-flash-image', 'gemini-3-pro-image'],
-};
-EXTENSIONS.push(IMAGE_STUDIO);
-
-// Git Pulse: read-only repository facts in the room via /git. Nothing to
-// install; it is on wherever the project is a git repository.
-export const GIT_PULSE = {
-  id: 'git-pulse',
-  kind: 'builtin',
-  name: 'Git Pulse',
-  vendor: 'MADRE',
-  package: null,
-  version: '0.1.0',
-  summary: 'Type /git in the composer to bring the repository\'s branch, uncommitted changes, recent commits or diff stats into the room as a shared fact card, without spending an agent turn.',
-  creates: ['nothing: read-only git commands run inside the project'],
-  requires: ['the project is a git repository'],
-  models: [],
-  commands: ['/git status', '/git log [n]', '/git diff', '/git branches'],
-};
-EXTENSIONS.push(GIT_PULSE);
-
-export const ASHCODE = {
-  id: 'ashcode',
-  kind: 'builtin',
-  name: 'AshCode',
-  vendor: 'MADRE · ORDER 937',
-  package: null,
-  version: '0.1.0-beta',
-  summary: 'Opt-in Spanish/English prompt and reply abbreviation. Keeps the original visible; may change meaning. Shorter characters do not guarantee fewer provider tokens.',
-  creates: ['nothing in the project', 'an ashCode switch in ~/.pulse/config.json', 'original and abbreviated text in the room event log when applied'],
-  requires: [],
-  models: [],
-};
-EXTENSIONS.push(ASHCODE);
-
-// RIPLEY: the file viewer renders HTML, SVG and Markdown instead of showing
-// their source, inside a sealed frame. A switch in config.json, nothing else.
-export const RIPLEY = {
-  id: 'ripley',
-  kind: 'builtin',
-  name: 'RIPLEY',
-  vendor: 'MADRE · PREVIEW',
-  package: null,
-  version: '0.1.0',
-  summary: 'Renders HTML, SVG and Markdown from the project and from .pulse/out in the file viewer, inside a sealed frame: no scripts, no network, no storage. Nothing leaves the room.',
-  creates: ['nothing in the project', 'a ripley switch in ~/.pulse/config.json'],
-  requires: [],
-  models: [],
-};
-EXTENSIONS.push(RIPLEY);
-
-export const extensionById = (id) => EXTENSIONS.find((extension) => extension.id === id) ?? null;
-
-export async function listExtensions({ projectRoot, agents = [], config = {}, imageKey = async () => null }) {
-  return Promise.all(EXTENSIONS.map(async (extension) => {
-    if (extension.id === 'git-pulse') {
-      const isRepo = await gitToplevel(projectRoot);
-      return {
-        id: extension.id, kind: 'builtin', name: extension.name, vendor: extension.vendor, package: null, version: extension.version,
-        summary: extension.summary, creates: extension.creates, requires: extension.requires, models: [], commands: extension.commands,
-        status: { installed: Boolean(isRepo), detail: isRepo ? 'on · project is a git repository' : 'not a git repository' },
-        preflight: isRepo ? { ok: true, problems: [] } : { ok: false, problems: ['Run `git init` in the project to use /git.'] },
-        install: { display: '/git in the composer', platforms: [] },
-        fixed: true,
-      };
-    }
-    if (extension.id === 'ashcode') {
-      const enabled = Boolean(config.modules?.ashCode?.enabled);
-      return {
-        id: extension.id, kind: 'builtin', name: extension.name, vendor: extension.vendor, package: null, version: extension.version,
-        summary: extension.summary, creates: extension.creates, requires: [], models: [],
-        status: { installed: enabled, detail: enabled ? 'on · beta · ORDER 937 available' : 'off · beta' },
-        preflight: { ok: true, problems: [] },
-        install: { display: enabled ? 'disable AshCode' : 'enable AshCode (config.json)', platforms: [] },
-        warning: 'Beta: abbreviation may alter meaning or introduce errors. Review the original. Character reduction is not verified token savings.',
-      };
-    }
-    if (extension.id === 'ripley') {
-      const enabled = Boolean(config.modules?.ripley?.enabled);
-      return {
-        id: extension.id, kind: 'builtin', name: extension.name, vendor: extension.vendor, package: null, version: extension.version,
-        summary: extension.summary, creates: extension.creates, requires: [], models: [],
-        status: { installed: enabled, detail: enabled ? 'on · PREVIEW in the file viewer' : 'off · files show as source' },
-        preflight: { ok: true, problems: [] },
-        install: { display: enabled ? 'disable RIPLEY' : 'enable RIPLEY (config.json)', platforms: [] },
-        fixed: false,
-      };
-    }
-    if (extension.kind === 'builtin') {
-      const enabled = Boolean(config.modules?.imageStudio?.enabled);
-      const key = await imageKey();
-      return {
-        id: extension.id,
-        kind: 'builtin',
-        name: extension.name,
-        vendor: extension.vendor,
-        package: null,
-        version: extension.version,
-        summary: extension.summary,
-        creates: extension.creates,
-        requires: extension.requires,
-        models: extension.models,
-        model: config.modules?.imageStudio?.model ?? extension.models[0],
-        status: { installed: enabled, detail: enabled ? `on · ${config.modules?.imageStudio?.model ?? extension.models[0]}${key ? '' : ' · no Gemini key found'}` : key ? 'key found' : 'no Gemini key found' },
-        preflight: key ? { ok: true, problems: [] } : { ok: false, problems: ['No Gemini API key: sign in with the Gemini CLI (/auth → API key) or set GEMINI_API_KEY. Image models bill against that key\'s AI Studio credits.'] },
-        install: { display: enabled ? 'disable Image Studio' : 'enable Image Studio (config.json)', platforms: ['gemini', 'claude', 'opencode'] },
-      };
-    }
-    const status = await extension.detect(projectRoot);
-    const plan = extension.installCommand({ agents });
-    const preflight = extension.preflight ? await extension.preflight(projectRoot) : { ok: true, problems: [] };
-    return {
-      id: extension.id,
-      name: extension.name,
-      vendor: extension.vendor,
-      package: extension.package,
-      version: extension.version,
-      summary: extension.summary,
-      creates: extension.creates,
-      status,
-      preflight,
-      install: { display: plan.display, platforms: plan.platforms },
-    };
-  }));
+import { spawn } from 'node:child_process';
+import { MODULES, moduleById, describeModules } from './modules/index.mjs';
+export { gitToplevel, findOnPath } from './modules/helpers.mjs';
+
+// Compatibility over the module registry (src/modules/): the same names the
+// server and the tests have always used, now answered by one file per module.
+export const EXTENSIONS = MODULES;
+export const AHP = moduleById('ahp');
+export const IMAGE_STUDIO = moduleById('image-studio');
+export const GIT_PULSE = moduleById('git-pulse');
+export const ASHCODE = moduleById('ashcode');
+export const RIPLEY = moduleById('ripley');
+export const OLLAMA = moduleById('ollama');
+export const extensionById = moduleById;
+
+// Lists every module as MODULES shows it. `ollama` is the server's probe state;
+// `services` may add what a server offers (imageKey, ollama wiring).
+export async function listExtensions({ projectRoot, agents = [], config = {}, imageKey = async () => null, ollama = null, services = {}, env = process.env } = {}) {
+  const ctx = {
+    projectRoot, config, agents, env, room: null,
+    readConfig: async () => config, updateConfig: async () => {}, record: async () => {},
+    services: { imageKey, ollama: ollama ? { state: () => ollama, wire: async () => ollama, pull: async () => ({ ok: false, error: 'not available here' }) } : null, ...services },
+  };
+  return describeModules(ctx);
 }
 
 // Runs one installer inside the project, streaming output lines. `runner`

package/src/memory.mjs

@@ -74,6 +74,7 @@ export class RoomMemory {
   #meta;
   #setMeta;
   #embedder = null;
+  #privacy = null;
 
   constructor(file) {
     this.#file = file;
@@ -172,6 +173,62 @@ export class RoomMemory {
   /* ---------- embeddings ---------- */
 
   attachEmbedder(embedder) { this.#embedder = embedder ?? null; return this; }
+
+  // Private terms never enter the index or the notes, whoever wrote them.
+  attachPrivacy(privacy) { this.#privacy = privacy ?? null; return this; }
+  #guard(text) { return this.#privacy ? this.#privacy.redact(text).text : text; }
+
+  // What the archive still carries: entries and notes with a private term, for MU/TH/UR.
+  exposure() {
+    if (!this.#privacy?.enabled) return { entries: 0, memories: 0 };
+    let entries = 0;
+    for (const row of this.#db.prepare('SELECT text FROM entries').iterate()) if (this.#privacy.hits(row.text)) entries += 1;
+    let memories = 0;
+    for (const row of this.#db.prepare('SELECT text FROM memories').iterate()) if (this.#privacy.hits(row.text)) memories += 1;
+    return { entries, memories };
+  }
+
+  // Replaces private terms in every entry and note already kept. FTS tables are external
+  // content with insert/delete triggers only, so a changed row is deleted and re-inserted
+  // with its own rowid; its vector goes with it and is recomputed later. Distilled flags stay.
+  purge() {
+    if (!this.#privacy?.enabled) return { entries: 0, memories: 0 };
+    const counts = { entries: 0, memories: 0 };
+    const entryRows = this.#db.prepare('SELECT sequence, event_id, timestamp, type, role, sender, target, message_id, text, distilled FROM entries').all();
+    const memoryRows = this.#db.prepare('SELECT id, created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, message_id FROM memories').all();
+    const deleteEntry = this.#db.prepare('DELETE FROM entries WHERE sequence = ?');
+    const deleteEntryVector = this.#db.prepare('DELETE FROM entry_vectors WHERE sequence = ?');
+    const insertEntry = this.#db.prepare('INSERT INTO entries (sequence, event_id, timestamp, type, role, sender, target, message_id, text, distilled) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    const deleteMemory = this.#db.prepare('DELETE FROM memories WHERE id = ?');
+    const deleteMemoryVector = this.#db.prepare('DELETE FROM memory_vectors WHERE id = ?');
+    const insertMemory = this.#db.prepare('INSERT INTO memories (id, created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, message_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    this.#db.exec('BEGIN');
+    try {
+      for (const row of entryRows) {
+        const { text, hits } = this.#privacy.redact(row.text);
+        if (!hits) continue;
+        deleteEntryVector.run(row.sequence);
+        deleteEntry.run(row.sequence);
+        insertEntry.run(row.sequence, row.event_id, row.timestamp, row.type, row.role, row.sender, row.target, row.message_id, text, row.distilled);
+        counts.entries += 1;
+      }
+      for (const row of memoryRows) {
+        const { text, hits } = this.#privacy.redact(row.text);
+        if (!hits) continue;
+        deleteMemoryVector.run(row.id);
+        deleteMemory.run(row.id);
+        // Two notes may collapse into the same redacted sentence: the later one is dropped.
+        const clash = this.#db.prepare('SELECT id FROM memories WHERE norm = ?').get(normalizeMemory(text));
+        if (!clash) insertMemory.run(row.id, row.created, row.kind, text, normalizeMemory(text), row.from_sequence, row.through_sequence, row.sources, row.agent, row.origin, row.message_id);
+        counts.memories += 1;
+      }
+      this.#db.exec('COMMIT');
+    } catch (error) {
+      this.#db.exec('ROLLBACK');
+      throw error;
+    }
+    return counts;
+  }
   get embedder() { return this.#embedder; }
 
   // Entries and notes without a vector for the current model, oldest first.
@@ -296,7 +353,7 @@ export class RoomMemory {
     this.#db.exec('BEGIN');
     try {
       for (const memory of list) {
-        const text = String(memory.text ?? '').trim();
+        const text = this.#guard(String(memory.text ?? '').trim());
         if (!text) continue;
         const kind = MEMORY_KINDS.includes(memory.kind) ? memory.kind : 'fact';
         const sources = (Array.isArray(memory.sources) ? memory.sources : []).filter((n) => Number.isInteger(n));
@@ -390,7 +447,8 @@ export class RoomMemory {
   // weighted, like entries) and, when few match, the most recent decisions and
   // preferences, all from before `beforeSequence` so they add to the window
   // rather than repeat it, within a character budget.
-  recallMemories(text, { beforeSequence = Number.MAX_SAFE_INTEGER, limit = 6, maxChars = 1200, queryVector = null, semanticFloor = 0.45 } = {}) {
+  // `fallback` fills a thin match with the latest decisions and preferences; @madre turns it off to stay honest.
+  recallMemories(text, { beforeSequence = Number.MAX_SAFE_INTEGER, limit = 6, maxChars = 1200, queryVector = null, semanticFloor = 0.45, fallback = true } = {}) {
     if (!this.#db) return [];
     const total = this.memoryCount();
     if (!total) return [];
@@ -406,7 +464,7 @@ export class RoomMemory {
       for (const { id } of rows) scores.set(id, (scores.get(id) ?? 0) + weight);
     }
     const ids = RoomMemory.fuse(scores, semantic).map(([id]) => id);
-    if (ids.length < 2) {
+    if (fallback && ids.length < 2) {
       const recent = this.#db.prepare("SELECT id FROM memories WHERE through_sequence < ? AND kind IN ('decision', 'preference') ORDER BY id DESC LIMIT ?").all(beforeSequence, limit);
       for (const { id } of recent) if (!ids.includes(id)) ids.push(id);
     }
@@ -442,9 +500,11 @@ export class RoomMemory {
       for (const event of events) {
         if (!event || event.ghost || !Number.isInteger(event.sequence)) continue;
         if (event.sequence > last) last = event.sequence;
+        // MADRE's canned replies are not the room's knowledge; they never enter the archive.
+        if (event.payload?.synthetic) continue;
         const entry = messageEntry(event);
         if (!entry) continue;
-        const result = this.#insert.run(event.sequence, event.id ?? `seq-${event.sequence}`, event.timestamp ?? null, event.type, entry.role, entry.sender, entry.target ?? null, entry.messageId ?? null, entry.text);
+        const result = this.#insert.run(event.sequence, event.id ?? `seq-${event.sequence}`, event.timestamp ?? null, event.type, entry.role, entry.sender, entry.target ?? null, entry.messageId ?? null, this.#guard(entry.text));
         added += Number(result.changes ?? 0);
       }
       this.#setMeta.run('last_sequence', String(last));

package/src/modules/ahp.mjs

@@ -0,0 +1,64 @@
+// AHP+: the one module that writes into the project, through a confirmed npx
+// command. Verified project state, checkpoints and handoffs in .ahp/.
+
+import { join, resolve } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { defineModule } from './sdk.mjs';
+import { readJson, gitToplevel, findOnPath } from './helpers.mjs';
+
+// AHP+ platform names for the agents MADRE knows about. Gemini has no AHP+
+// adapter yet, so it is simply not requested.
+const AHP_PLATFORMS = { codex: 'codex', claude: 'claude', opencode: 'opencode' };
+const PACKAGE = '@jossuealcala/ahp-plus';
+const VERSION = '1.4.1';
+
+async function detect(projectRoot) {
+  const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));
+  if (!manifest) return { installed: false };
+  const pinned = await readJson(join(projectRoot, 'node_modules', '@jossuealcala', 'ahp-plus', 'package.json'));
+  return {
+    installed: true,
+    version: pinned?.version ?? null,
+    protocolVersion: manifest.protocol_version ?? null,
+    projectId: manifest.project_id ?? null,
+    detail: [pinned?.version ? `cli ${pinned.version}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
+  };
+}
+
+// Refuses before anything is written when the outcome would be wrong.
+async function preflight(projectRoot, { toplevel = gitToplevel, npx = findOnPath } = {}) {
+  const root = await realpath(projectRoot).catch(() => resolve(projectRoot));
+  const problems = [];
+  if (!(await npx('npx'))) problems.push('npx is not on PATH for the MADRE server; start MADRE from a terminal where `npx --version` works.');
+  const top = await toplevel(root);
+  if (!top) {
+    problems.push('The project is not a git repository. AHP+ pins itself to the git root: run `git init` in the project first.');
+  } else if (top !== root) {
+    problems.push(`The project's git root is ${top}, not the project itself. AHP+ would install there. Run \`git init\` inside the project, or remove the stray repository at ${top}.`);
+  }
+  return { ok: problems.length === 0, problems, gitRoot: top };
+}
+
+function installCommand({ agents = [] }) {
+  const platforms = agents.filter((agent) => agent.detected && AHP_PLATFORMS[agent.id]).map((agent) => AHP_PLATFORMS[agent.id]);
+  const args = ['--yes', `${PACKAGE}@${VERSION}`, 'setup', '.'];
+  if (platforms.length) args.push('--platforms', platforms.join(','));
+  return { command: 'npx', args, platforms, display: ['npx', ...args].join(' ') };
+}
+
+export default defineModule({
+  id: 'ahp',
+  kind: 'installer',
+  name: 'AHP+',
+  vendor: 'Agent Handoff Protocol Plus',
+  package: PACKAGE,
+  version: VERSION,
+  summary: 'Verified project state, checkpoints and handoffs between AI sessions, stored in .ahp/ next to your code.',
+  creates: ['.ahp/ with manifest, sessions, handoffs and evidence', 'a project-local pin of @jossuealcala/ahp-plus', 'IDE adapter files for the detected agents'],
+  detect, preflight, installCommand,
+  async status(ctx) {
+    const status = await detect(ctx.projectRoot);
+    const plan = installCommand({ agents: ctx.agents });
+    return { status, preflight: await preflight(ctx.projectRoot), install: { display: plan.display, platforms: plan.platforms } };
+  },
+});

package/src/modules/ashcode.mjs

@@ -0,0 +1,28 @@
+// AshCode: opt-in abbreviation of prompts and replies. Beta, so the switch asks
+// for confirmation and the room says so every time it turns on.
+
+import { defineModule } from './sdk.mjs';
+
+const WARNING = 'Beta: abbreviation may alter meaning or introduce errors. Review the original. Character reduction is not verified token savings.';
+
+export default defineModule({
+  id: 'ashcode',
+  configKey: 'ashCode',
+  name: 'AshCode',
+  vendor: 'MADRE · ORDER 937',
+  version: '0.1.0-beta',
+  summary: 'Opt-in Spanish/English prompt and reply abbreviation. Keeps the original visible; may change meaning. Shorter characters do not guarantee fewer provider tokens.',
+  creates: ['nothing in the project', 'an ashCode switch in ~/.pulse/config.json', 'original and abbreviated text in the room event log when applied'],
+  card: 'ashcode',
+  confirm: 'AshCode is beta and can change meaning. Send { "confirm": true } to enable it.',
+  toggledEvent: { beta: true },
+  toggledBody: () => ({ beta: true, warning: 'AshCode beta may alter meaning; review the original. Character reduction is not verified token savings.' }),
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? 'on · beta · ORDER 937 available' : 'off · beta' },
+      install: { display: ctx.settings.enabled ? 'disable AshCode' : 'enable AshCode (config.json)', platforms: [] },
+      warning: WARNING,
+    };
+  },
+  async onToggle(ctx, enabled) { ctx.room.setAshCode(enabled); return null; },
+});

package/src/modules/git-pulse.mjs

@@ -0,0 +1,26 @@
+// Git Pulse: /git in the composer brings the repository's facts into the room.
+// Nothing to switch: it is on wherever the project is a git repository.
+
+import { defineModule } from './sdk.mjs';
+import { gitToplevel } from './helpers.mjs';
+
+export default defineModule({
+  id: 'git-pulse',
+  name: 'Git Pulse',
+  vendor: 'MADRE',
+  summary: 'Type /git in the composer to bring the repository\'s branch, uncommitted changes, recent commits or diff stats into the room as a shared fact card, read-only, without spending an agent turn.',
+  creates: ['nothing: read-only git commands run inside the project'],
+  requires: ['the project is a git repository'],
+  commands: ['/git status', '/git log [n]', '/git diff', '/git branches'],
+  card: 'fixed',
+  async status(ctx) {
+    const isRepo = await gitToplevel(ctx.projectRoot);
+    return {
+      status: { installed: Boolean(isRepo), detail: isRepo ? 'on · project is a git repository' : 'not a git repository' },
+      preflight: isRepo ? { ok: true, problems: [] } : { ok: false, problems: ['Run `git init` in the project to use /git.'] },
+      install: { display: '/git in the composer', platforms: [] },
+      fixed: true,
+    };
+  },
+  async toggle() { return { status: 405, body: { error: 'Git Pulse has no switch: it is on wherever the project is a git repository.' } }; },
+});

package/src/modules/helpers.mjs

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+import { access, readFile, realpath } from 'node:fs/promises';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export async function readJson(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); } catch { return null; }
+}
+
+// Where does git think this project lives? AHP+ pins itself to the git root,
+// so a project inside a bigger repository (or a home directory that was
+// accidentally `git init`ed) would receive .ahp/ somewhere else entirely.
+export async function gitToplevel(projectRoot) {
+  try {
+    const { stdout } = await execFileAsync('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel'], { timeout: 5000 });
+    return await realpath(stdout.trim()).catch(() => stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+export async function findOnPath(name, envPath = process.env.PATH ?? '') {
+  for (const directory of envPath.split(delimiter).filter(Boolean)) {
+    const candidate = join(directory, name);
+    if (await access(candidate).then(() => true, () => false)) return candidate;
+  }
+  return null;
+}

package/src/modules/image-studio.mjs

@@ -0,0 +1,39 @@
+// Image Studio: MADRE's own MCP image server on the Gemini image models, for
+// the CLIs that cannot draw natively. A switch and a model in config.json.
+
+import { defineModule } from './sdk.mjs';
+
+const MODELS = ['gemini-2.5-flash-image', 'gemini-3.1-flash-image', 'gemini-3-pro-image'];
+
+export default defineModule({
+  id: 'image-studio',
+  configKey: 'imageStudio',
+  name: 'Image Studio',
+  vendor: 'MADRE · Gemini API',
+  summary: 'Gives Gemini CLI, Claude Code and OpenCode an image-generation tool through a MADRE-owned MCP server on the Gemini API image models, using your own Gemini key and credits. Attached only inside a creation lease with the image scope on.',
+  creates: ['nothing in the project: images land in the lease directory like any artifact', 'an "image-studio" entry in ~/.pulse/config.json', 'an MCP server process per turn, started and stopped by the room'],
+  requires: ['a Gemini API key with credits (the key the Gemini CLI stores, or GEMINI_API_KEY)'],
+  models: MODELS,
+  settings: { enabled: false, model: MODELS[0] },
+  card: 'image-studio',
+  async status(ctx) {
+    const key = await ctx.services.imageKey();
+    const model = ctx.settings.model ?? MODELS[0];
+    return {
+      model,
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? `on · ${model}${key ? '' : ' · no Gemini key found'}` : key ? 'key found' : 'no Gemini key found' },
+      preflight: key ? { ok: true, problems: [] } : { ok: false, problems: ['No Gemini API key: sign in with the Gemini CLI (/auth → API key) or set GEMINI_API_KEY. Image models bill against that key.'] },
+      install: { display: ctx.settings.enabled ? 'disable Image Studio' : 'enable Image Studio (config.json)', platforms: ['gemini', 'claude', 'opencode'] },
+    };
+  },
+  async toggle(ctx, payload) {
+    const enabled = !ctx.settings.enabled;
+    const key = await ctx.services.imageKey();
+    if (enabled && !key) return { status: 412, body: { error: 'No Gemini API key found. Sign in with the Gemini CLI (/auth → API key) or set GEMINI_API_KEY, then enable Image Studio.' } };
+    const model = typeof payload?.model === 'string' && payload.model ? payload.model : (ctx.settings.model ?? MODELS[0]);
+    await ctx.updateConfig({ modules: { ...(ctx.config.modules ?? {}), imageStudio: { enabled, model } } });
+    ctx.services.setImageModule({ enabled, model });
+    await ctx.record('extension.toggled', { id: 'image-studio', name: 'Image Studio', enabled, model });
+    return { status: 200, body: { enabled, model, capabilities: ctx.room.capabilities() } };
+  },
+});

package/src/modules/index.mjs

@@ -0,0 +1,21 @@
+// The registry. Order is the order MODULES shows.
+import ahp from './ahp.mjs';
+import imageStudio from './image-studio.mjs';
+import gitPulse from './git-pulse.mjs';
+import ashcode from './ashcode.mjs';
+import ripley from './ripley.mjs';
+import ollama from './ollama.mjs';
+import { matchRoute } from './sdk.mjs';
+
+export const MODULES = [ahp, imageStudio, gitPulse, ashcode, ripley, ollama];
+export const moduleById = (id) => MODULES.find((module) => module.id === id) ?? null;
+export function describeModules(ctx) { return Promise.all(MODULES.map((module) => module.describe(ctx))); }
+// One flat list of every route a module serves, with the module attached.
+export function findModuleRoute(method, pathname) {
+  for (const module of MODULES) {
+    const hit = matchRoute(module.routes, method, pathname);
+    if (hit) return { module, ...hit };
+  }
+  return null;
+}
+export { defineModule } from './sdk.mjs';