aio-connect 1.1.0

package/src/rollback.js

@@ -0,0 +1,41 @@
+// rollback.js — `aio rollback`: surgically undo everything setup did (FR7)
+import path from 'node:path';
+import os from 'node:os';
+import { stripBlock, removeMcpAdditions, backup } from './write.js';
+import { BACKUP_DIR } from './paths.js';
+
+export function runRollback() {
+  const home = os.homedir();
+  const targets = [
+    { label: 'opencode', file: path.join(home, '.config', 'opencode', 'AGENTS.md') },
+    { label: 'claude', file: path.join(home, '.claude', 'CLAUDE.md') },
+    { label: 'kimi', file: path.join(home, '.kimi-code', 'AGENTS.md') },
+    { label: 'jcode', file: path.join(home, '.jcode', 'AGENTS.md') },
+    { label: 'codex', file: path.join(home, '.codex', 'AGENTS.md') },
+    { label: 'gemini', file: path.join(home, '.gemini', 'GEMINI.md') },
+    { label: 'global', file: path.join(home, 'AGENTS.md') },
+  ];
+
+  console.log('aio rollback');
+  console.log('─'.repeat(76));
+
+  console.log('\nContext block');
+  let removed = 0;
+  for (const t of targets) {
+    const st = stripBlock(t.file);
+    if (st === 'removed') removed++;
+    console.log(`  [${st === 'removed' ? 'x' : ' '}] ${t.label.padEnd(26)} ${st} — ${t.file}`);
+  }
+
+  console.log('\nMCP additions (only entries aio itself added)');
+  const mcp = removeMcpAdditions();
+  if (!mcp.length) console.log('  [x] none on record — nothing to remove');
+  for (const r of mcp) {
+    console.log(`  [${r.status === 'removed' ? 'x' : ' '}] ${r.target.padEnd(26)} ${r.status}`);
+  }
+
+  console.log(`\nRemoved ${removed} context block(s).`);
+  console.log(`File backups (kept as safety net): ${BACKUP_DIR}`);
+  console.log('Local data (ai-tools.db, TOOLS-INDEX.md, TRACKING.md) was never touched.');
+  console.log('');
+}

package/src/scan.js

@@ -0,0 +1,177 @@
+// scan.js — read-only machine scan: agents, repos, tools, skills, MCP binary
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// Agent spec: PATH binary OR instruction-parent dir present (codex/gemini may be
+// configured without a shell wrapper).
+const AGENTS = [
+  { name: 'opencode', dirHint: '.config/opencode' },
+  { name: 'claude', dirHint: '.claude' },
+  { name: 'kimi', dirHint: '.kimi-code' },
+  { name: 'jcode', dirHint: '.jcode' },
+  { name: 'freebuff', dirHint: null },
+  { name: 'hermes', dirHint: null },
+  { name: 'codex', dirHint: '.codex' },
+  { name: 'gemini', dirHint: '.gemini' },
+];
+export const AGENT_NAMES = AGENTS.map((a) => a.name);
+
+function pathDirs() {
+  return (process.env.PATH || '')
+    .split(path.delimiter)
+    .map((d) => d.trim().replace(/^"|"$/g, ''))
+    .filter(Boolean);
+}
+
+function findOnPath(name) {
+  const exts = ['', ...(process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean), '.PS1'];
+  for (const dir of pathDirs()) {
+    for (const ext of exts) {
+      const p = path.join(dir, name + ext);
+      try {
+        if (fs.existsSync(p)) return p;
+      } catch {
+        /* unreadable PATH entry — keep scanning */
+      }
+    }
+  }
+  return null;
+}
+
+/** Detect the known agent CLIs: on PATH, or by their instruction directory. */
+export function detectAgents() {
+  const home = os.homedir();
+  return AGENTS.map(({ name, dirHint }) => {
+    const bin = findOnPath(name);
+    const configured = Boolean(dirHint && fs.existsSync(path.join(home, dirHint)));
+    return {
+      name,
+      found: Boolean(bin) || configured,
+      bin: bin || (configured ? `(configured: ~/${dirHint})` : null),
+    };
+  });
+}
+
+/** Detect an auxiliary binary (e.g. codebase-memory-mcp) on PATH. */
+export function detectBinary(name) {
+  return findOnPath(name);
+}
+
+/** Scan a directory of cloned git repos; URL comes from each real .git/config. */
+export function scanRepos(reposDir) {
+  if (!reposDir || !fs.existsSync(reposDir)) return [];
+  const out = [];
+  for (const ent of fs.readdirSync(reposDir, { withFileTypes: true })) {
+    if (!ent.isDirectory()) continue;
+    const full = path.join(reposDir, ent.name);
+    let url = '';
+    try {
+      const cfg = fs.readFileSync(path.join(full, '.git', 'config'), 'utf8');
+      const m = cfg.match(/url\s*=\s*(\S+)/);
+      if (m) url = m[1].replace(/\.git$/, '');
+    } catch {
+      /* not a git repo — listed as local-only */
+    }
+    out.push({ name: ent.name, url, path: full });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function stripMd(s) {
+  return s.replace(/[`*_]/g, '').trim();
+}
+
+/** Parse TOOLS-INDEX.md markdown tables → tool rows (fallback when no DB). */
+export function parseToolsIndex(file) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  const out = [];
+  let section = '';
+  for (const line of lines) {
+    const h = line.match(/^##\s+(\d+[a-z]?)\.?\s+(.*)$/i);
+    if (h) {
+      section = h[2].replace(/\s*\(.*\)$/, '').trim();
+      continue;
+    }
+    if (!line.trim().startsWith('|')) continue;
+    const raw = line.split('|');
+    const cells = raw.slice(1, raw.length - 1).map((c) => c.trim());
+    if (cells.length < 2) continue;
+    if (/^:?-{3,}:?$/.test(cells[0])) continue; // separator row
+    const c0 = stripMd(cells[0]);
+    if (/^(command|tool|catatan|layanan|akses|fungsi|item|skill|name)$/i.test(c0)) continue; // header
+    out.push({
+      name: c0,
+      category: section,
+      access: stripMd(cells[0]),
+      version: '',
+      url: '',
+      description: cells.slice(1).map(stripMd).filter(Boolean).join(' · '),
+      status: '',
+      source: 'TOOLS-INDEX.md',
+    });
+  }
+  return out;
+}
+
+/**
+ * Tool catalog: prefer ai-tools.db (SQLite via node:sqlite, optional),
+ * fall back to TOOLS-INDEX.md parse, else empty (graceful on other machines).
+ */
+export async function loadTools(dataDir) {
+  if (!dataDir) return [];
+  const dbPath = path.join(dataDir, 'ai-tools.db');
+  if (fs.existsSync(dbPath)) {
+    try {
+      const { DatabaseSync } = await import('node:sqlite');
+      const db = new DatabaseSync(dbPath, { readOnly: true });
+      const rows = db
+        .prepare(
+          'SELECT name, category, access, version, url, description, status FROM tools ORDER BY id'
+        )
+        .all();
+      db.close();
+      if (rows.length) return rows.map((r) => ({ ...r, source: 'ai-tools.db' }));
+    } catch (e) {
+      console.error(`[aio] note: could not read ai-tools.db (${e.message}) — falling back`);
+    }
+  }
+  const mdPath = path.join(dataDir, 'TOOLS-INDEX.md');
+  if (fs.existsSync(mdPath)) {
+    try {
+      return parseToolsIndex(mdPath);
+    } catch (e) {
+      console.error(`[aio] note: could not parse TOOLS-INDEX.md (${e.message})`);
+    }
+  }
+  return [];
+}
+
+/** Count/list global agent skill directories (follows symlinked skills). */
+export function scanSkills() {
+  const home = os.homedir();
+  const locations = [path.join(home, '.agents', 'skills'), path.join(home, '.claude', 'skills')];
+  return locations.map((loc) => {
+    let names = [];
+    try {
+      names = fs
+        .readdirSync(loc, { withFileTypes: true })
+        .filter((d) => {
+          if (d.isDirectory()) return true;
+          if (d.isSymbolicLink()) {
+            try {
+              return fs.statSync(path.join(loc, d.name)).isDirectory();
+            } catch {
+              return false;
+            }
+          }
+          return false;
+        })
+        .map((d) => d.name)
+        .sort();
+    } catch {
+      /* location absent */
+    }
+    return { location: loc, count: names.length, names };
+  });
+}

package/src/setup.js

@@ -0,0 +1,119 @@
+// setup.js — the `aio` default command: scan → generate → inject → ensure → report
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { resolveDataDir, resolveReposDir, writeState, BACKUP_DIR, STATE_DIR } from './paths.js';
+import { detectAgents, detectBinary, scanRepos, loadTools, scanSkills } from './scan.js';
+import { buildBlock, injectBlock, genContext, ensureMcp, fixPaths, backup } from './write.js';
+import { getVersion } from './banner.js';
+
+function targetFiles(home) {
+  return [
+    { label: 'opencode', file: path.join(home, '.config', 'opencode', 'AGENTS.md') },
+    { label: 'claude', file: path.join(home, '.claude', 'CLAUDE.md') },
+    { label: 'kimi', file: path.join(home, '.kimi-code', 'AGENTS.md') },
+    { label: 'jcode', file: path.join(home, '.jcode', 'AGENTS.md') },
+    { label: 'codex', file: path.join(home, '.codex', 'AGENTS.md') },
+    { label: 'gemini', file: path.join(home, '.gemini', 'GEMINI.md') },
+    { label: 'global', file: path.join(home, 'AGENTS.md') },
+  ];
+}
+
+function row(tag, name, detail) {
+  console.log(`  [${tag}] ${name.padEnd(26)} ${detail}`);
+}
+
+export async function runSetup(opts = {}) {
+  const version = getVersion();
+  const home = os.homedir();
+
+  if (Number(process.versions.node.split('.')[0]) < 22) {
+    console.error(`[aio] warning: Node ${process.versions.node} detected — Node >= 22 recommended`);
+  }
+
+  const dataDir = resolveDataDir(opts.home);
+  const reposDir = resolveReposDir(opts.repos);
+  if (!dataDir) {
+    console.log('[aio] note: no local data dir found (ai-tools.db / TOOLS-INDEX.md).');
+    console.log('[aio]      Install location registry first, or run with --home <dir>.');
+  }
+  if (!reposDir) {
+    console.log('[aio] note: repos dir not found. Pass --repos <dir> or set AIO_REPOS_DIR.');
+  }
+
+  const agents = detectAgents();
+  const repos = scanRepos(reposDir);
+  const tools = await loadTools(dataDir);
+  const skills = scanSkills();
+  const mcpBin = detectBinary('codebase-memory-mcp');
+
+  const manifestPath = dataDir
+    ? path.join(dataDir, 'aio-context.md')
+    : path.join(STATE_DIR, 'aio-context.md');
+  genContext({ version, dataDir, reposDir, repos, tools, skills, agents }, manifestPath);
+
+  const body = buildBlock({ version, manifestPath, dataDir });
+  const targets = targetFiles(home);
+  const blockResults = targets.map((t) => {
+    if (!fs.existsSync(path.dirname(t.file))) {
+      return { ...t, status: 'skipped (agent not installed)' };
+    }
+    return { ...t, ...injectBlock(t.file, body, `inject-${t.label}`) };
+  });
+
+  const mcpResults = mcpBin
+    ? ensureMcp(mcpBin)
+    : [{ target: 'codebase-memory-mcp', status: 'binary not on PATH — skipped' }];
+
+  const pathResults = fixPaths();
+
+  writeState({
+    version,
+    dataDir,
+    reposDir,
+    manifestPath,
+    lastRun: new Date().toISOString(),
+  });
+
+  /* ---- report ---- */
+  console.log('');
+  console.log(`aio setup v${version}`);
+  console.log('─'.repeat(76));
+
+  console.log('\nAgents');
+  for (const a of agents) {
+    const cover = {
+      opencode: '→ .config/opencode/AGENTS.md',
+      claude: '→ .claude/CLAUDE.md',
+      kimi: '→ .kimi-code/AGENTS.md',
+      jcode: '→ .jcode/AGENTS.md',
+      codex: '→ .codex/AGENTS.md',
+      gemini: '→ .gemini/GEMINI.md',
+      hermes: '→ ~/AGENTS.md',
+      freebuff: '→ ~/AGENTS.md (fallback)',
+    }[a.name] || '';
+    row(a.found ? 'x' : ' ', a.name, `${a.found ? 'detected' : 'not installed'}  ${cover}`);
+  }
+
+  console.log('\nContext block (auto-use rules + usage disclosure)');
+  for (const r of blockResults) row(r.status.includes('skip') ? ' ' : 'x', path.basename(r.file), `${r.status} — ${r.file}`);
+
+  console.log('\nMCP (codebase-memory-mcp)');
+  if (!mcpResults.length) console.log('  [ ] none — no config files found');
+  for (const r of mcpResults) row(r.status.includes('skip') ? ' ' : 'x', r.target, r.status);
+
+  console.log('\nStale path repair (folder rename)');
+  if (!pathResults.length) console.log('  [x] clean — no broken "AI tutorial" references');
+  for (const r of pathResults) row('x', path.basename(r.target), r.status);
+
+  const skillTotal = skills.reduce((n, s) => n + s.count, 0);
+  console.log('\nManifest');
+  row('x', 'aio-context.md', `REPOS ${repos.length} · TOOLS ${tools.length} · SKILLS ${skillTotal}`);
+  console.log(`  ${manifestPath}`);
+  console.log('');
+  console.log(`Backups: ${BACKUP_DIR}`);
+  console.log('Done. Open any agent directly (opencode / claude / kimi / ...) — it now knows');
+  console.log('your repos, tools & skills. No slash-commands needed. Usage is disclosed as:');
+  console.log('  [aio] Using <name> (<type>) — <function>');
+  console.log('');
+}

package/src/update.js

@@ -0,0 +1,26 @@
+// update.js — `aio update`: self-update from the public GitHub repo, then re-run setup
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+export function runUpdate({ binPath }) {
+  const pkg = 'aio-connect';
+
+  console.log(`[aio] Updating ${pkg} from npm ...`);
+  const install = spawnSync('npm', ['install', '-g', pkg], {
+    shell: true,
+    stdio: 'inherit',
+    cwd: os.homedir(),
+  });
+  if (install.error) {
+    console.error(`[aio] update failed: ${install.error.message}`);
+    process.exit(1);
+  }
+  if (install.status !== 0) {
+    console.error(`[aio] update failed: npm install exited with code ${install.status}`);
+    process.exit(install.status ?? 1);
+  }
+
+  console.log('[aio] Package updated — re-running setup with the new version ...');
+  const fresh = spawnSync(process.execPath, [binPath], { stdio: 'inherit' });
+  process.exit(fresh.status ?? 0);
+}

package/src/write.js

@@ -0,0 +1,298 @@
+// write.js — backups, block injection, context manifest, MCP ensure, path repair
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { BACKUP_DIR, STATE_DIR } from './paths.js';
+
+export const BLOCK_START = '<!-- aio:auto-config:v1:start -->';
+export const BLOCK_END = '<!-- aio:auto-config:v1:end -->';
+const BLOCK_RE = /<!-- aio:auto-config:v1:start -->[\s\S]*?<!-- aio:auto-config:v1:end -->/;
+
+export function backup(file, label) {
+  if (!fs.existsSync(file)) return null;
+  fs.mkdirSync(BACKUP_DIR, { recursive: true });
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const safe = String(label).replace(/[^a-z09_-]/gi, '_');
+  const dest = path.join(BACKUP_DIR, `${safe}__${ts}__${path.basename(file)}`);
+  fs.copyFileSync(file, dest);
+  return dest;
+}
+
+/** Build the auto-use rule block (FR2 + FR6: usage disclosure format). */
+export function buildBlock({ version, manifestPath, dataDir }) {
+  const lines = [
+    `### AIO AUTO-CONTEXT (generated by aio v${version} — do not edit; re-run \`aio\` to refresh)`,
+    '',
+    `- Context manifest (auto-generated): \`${manifestPath}\``,
+  ];
+  if (dataDir) {
+    if (fs.existsSync(path.join(dataDir, 'TOOLS-INDEX.md'))) {
+      lines.push(`- Tools registry: \`${path.join(dataDir, 'TOOLS-INDEX.md')}\``);
+    }
+    if (fs.existsSync(path.join(dataDir, 'ai-tools.db'))) {
+      lines.push(`- Local tools DB (SQLite): \`${path.join(dataDir, 'ai-tools.db')}\``);
+    }
+  }
+  lines.push(
+    '',
+    'Auto-use rules (plain-language prompts only — NO slash-commands required):',
+    '1. USAGE DISCLOSURE (MANDATORY — never skip): the moment you read, list, cite, or act on ANY entry from the manifest above, the FIRST line of that part of your reply must be exactly:',
+    '   [aio] Using <name> (<type>) — <function>',
+    '   where <type> = repo | cli | service | skill, and <function> = the manifest entry\'s one-line description.',
+    '   Example: [aio] Using Stirling-PDF (repo) — HTML/CSS/JS to PDF converter',
+    '   Emit the line BEFORE the related answer text, in every response that touches the manifest — not optional, not a recap, no rewording.',
+    '2. When a prompt involves a local repository, tool, service, or skill, read the manifest above and route yourself to the matching entry on your own — never ask the user to type `/command` for routing.',
+    '3. Prefer manifest entries (already installed locally) over proposing new installs.',
+    '4. If the user mentions a repo/tool that is not in the manifest, tell them to run `aio` again to rescan.',
+    '5. Reply in the user’s language.'
+  );
+  return lines.join('\n');
+}
+
+/** Idempotent marker injection: first run appends, later runs replace in place. */
+export function injectBlock(file, body, label) {
+  const existed = fs.existsSync(file);
+  const current = existed ? fs.readFileSync(file, 'utf8') : '';
+  const had = BLOCK_RE.test(current);
+  const block = `${BLOCK_START}\n${body}\n${BLOCK_END}`;
+  const next = had
+    ? current.replace(BLOCK_RE, block)
+    : (current ? current.replace(/\s*$/, '\n\n') : '') + block + '\n';
+  if (next === current) return { status: 'unchanged', file };
+  if (existed) backup(file, label);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  return { status: had ? 'updated' : 'injected', file };
+}
+
+/** Surgically remove the block (rollback, FR7). Returns 'removed' | 'absent'. */
+export function stripBlock(file) {
+  if (!fs.existsSync(file)) return 'absent';
+  const current = fs.readFileSync(file, 'utf8');
+  if (!BLOCK_RE.test(current)) return 'absent';
+  backup(file, 'rollback');
+  const next = current.replace(BLOCK_RE, '').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+  fs.writeFileSync(file, next);
+  return 'removed';
+}
+
+/** Generate the context manifest (FR3): REPOS + TOOLS + SKILLS. */
+export function genContext({ version, dataDir, reposDir, repos, tools, skills, agents }, outPath) {
+  const now = new Date().toISOString();
+  const L = [
+    `<!-- AUTO-GENERATED by aio v${version} on ${now} — do not edit; run \`aio\` to refresh -->`,
+    '',
+    '# AIO Context Manifest',
+    '',
+    `> Repos dir: \`${reposDir || '(not configured — pass --repos <dir> or set AIO_REPOS_DIR)'}\``,
+    dataDir ? `> Data dir: \`${dataDir}\`` : '> Data dir: (none — tools registry / DB not found)',
+    '',
+    `## REPOS (${repos.length})`,
+    '',
+    repos.length
+      ? ['| # | Repository | URL | Local path |', '|---|---|---|---|']
+          .concat(repos.map((r, i) => `| ${i + 1} | ${r.name} | ${r.url || '— (local only)'} | \`${r.path}\` |`))
+          .join('\n')
+      : '_No cloned repositories found._',
+    '',
+    `## TOOLS (${tools.length})`,
+    '',
+    tools.length
+      ? ['| Tool | What it does | Access / command | Version | Link |', '|---|---|---|---|---|']
+          .concat(
+            tools.map(
+              (t) =>
+                `| ${t.name} | ${t.description || '—'} | \`${(t.access || '').replace(/\|/g, '\\|')}\` | ${t.version || '—'} | ${t.url || '—'} |`
+            )
+          )
+          .join('\n')
+      : '_No tools catalog found (ai-tools.db / TOOLS-INDEX.md)._',
+    '',
+    `## SKILLS (${skills.reduce((n, s) => n + s.count, 0)})`,
+    '',
+  ];
+  for (const loc of skills) {
+    L.push(`- \`${loc.location}\` — ${loc.count} skills`);
+    if (loc.count) L.push(`  - ${loc.names.join(', ')}`);
+  }
+  L.push('', '## AGENTS DETECTED', '');
+  for (const a of agents) L.push(`- ${a.name}: ${a.found ? `found (\`${a.bin}\`)` : 'not installed'}`);
+  L.push('');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, L.join('\n'));
+  return outPath;
+}
+
+/* ---------------- MCP ensure (FR1) ---------------- */
+
+const LEDGER = path.join(STATE_DIR, 'mcp-ledger.json');
+const MCP_KEY = 'codebase-memory-mcp';
+
+function ledgerRead() {
+  try {
+    return JSON.parse(fs.readFileSync(LEDGER, 'utf8'));
+  } catch {
+    return [];
+  }
+}
+function ledgerAdd(file, key) {
+  const l = ledgerRead();
+  if (!l.some((e) => e.file === file && e.key === key)) {
+    l.push({ file, key });
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(LEDGER, JSON.stringify(l, null, 2));
+  }
+}
+export function ledgerList() {
+  return ledgerRead();
+}
+
+export function ensureJsonEntry(file, key, entry, label, rootKey, create = false) {
+  let obj = {};
+  if (fs.existsSync(file)) {
+    try {
+      obj = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (e) {
+      return { target: path.basename(file), status: `parse error: ${e.message}` };
+    }
+  } else if (create && fs.existsSync(path.dirname(file))) {
+    obj = {}; // agent config dir present → bootstrap the file (gemini settings.json)
+  } else {
+    return { target: path.basename(file), status: 'file not found — skipped' };
+  }
+  const holder = rootKey ? (obj[rootKey] ||= {}) : obj;
+  if (holder[key]) return { target: path.basename(file), status: 'present' };
+  backup(file, label);
+  holder[key] = entry;
+  const text = JSON.stringify(obj, null, 2) + '\n';
+  JSON.parse(text); // verify before write
+  fs.writeFileSync(file, text);
+  ledgerAdd(file, key);
+  return { target: path.basename(file), status: 'added' };
+}
+
+/** codex config.toml: append [mcp_servers.<key>] only when absent. */
+export function ensureTomlEntry(file, key, entry, label) {
+  if (!fs.existsSync(file)) return { target: path.basename(file), status: 'file not found — skipped' };
+  const txt = fs.readFileSync(file, 'utf8');
+  const header = `[mcp_servers.${key}]`;
+  if (txt.includes(header) || txt.includes(`[mcp_servers."${key}"]`)) {
+    return { target: path.basename(file), status: 'present' };
+  }
+  backup(file, label);
+  const body = Object.entries(entry)
+    .map(([k, v]) => `${k} = ${JSON.stringify(v)}`)
+    .join('\n');
+  fs.writeFileSync(file, txt.replace(/\s*$/, '') + `\n\n${header}\n${body}\n`);
+  ledgerAdd(file, key);
+  return { target: path.basename(file), status: 'added' };
+}
+
+/** opencode.jsonc is JSONC (comments must survive) → textual insert. */
+function ensureOpencodeJsonc(key, entry) {
+  const file = path.join(os.homedir(), '.config', 'opencode', 'opencode.jsonc');
+  if (!fs.existsSync(file)) return { target: 'opencode.jsonc', status: 'file not found — skipped' };
+  const txt = fs.readFileSync(file, 'utf8');
+  if (txt.includes(`"${key}"`)) return { target: 'opencode.jsonc', status: 'present' };
+  const marker = '"mcp": {';
+  const idx = txt.indexOf(marker);
+  if (idx === -1) return { target: 'opencode.jsonc', status: 'no "mcp" block — skipped' };
+  backup(file, 'opencode-jsonc');
+  const after = txt.slice(idx + marker.length);
+  const empty = /^\s*\}/.test(after);
+  const insert = `${marker}\n    ${JSON.stringify(key)}: ${JSON.stringify(entry)}${empty ? '' : ','}`;
+  const next = txt.slice(0, idx) + insert + after;
+  fs.writeFileSync(file, next);
+  ledgerAdd(file, key);
+  return { target: 'opencode.jsonc', status: 'added' };
+}
+
+/** Ensure codebase-memory-mcp exists in opencode / claude / kimi / jcode / codex / gemini configs. */
+export function ensureMcp(binary) {
+  const entry = { command: binary };
+  const home = os.homedir();
+  const results = [];
+  results.push(ensureOpencodeJsonc(MCP_KEY, { type: 'local', command: binary }));
+  results.push(
+    ensureJsonEntry(path.join(home, '.claude.json'), MCP_KEY, entry, 'claude-json', 'mcpServers')
+  );
+  results.push(
+    ensureJsonEntry(path.join(home, '.kimi-code', 'mcp.json'), MCP_KEY, entry, 'kimi-mcp', 'mcpServers')
+  );
+  results.push(
+    ensureJsonEntry(path.join(home, '.jcode', 'mcp.json'), MCP_KEY, entry, 'jcode-mcp', 'servers')
+  );
+  results.push(
+    ensureJsonEntry(path.join(home, '.gemini', 'settings.json'), MCP_KEY, entry, 'gemini-settings', 'mcpServers', true)
+  );
+  results.push(ensureTomlEntry(path.join(home, '.codex', 'config.toml'), MCP_KEY, entry, 'codex-toml'));
+  return results;
+}
+
+/** Reverse exactly what ensureMcp added (recorded in the ledger). */
+export function removeMcpAdditions() {
+  const out = [];
+  for (const { file, key } of ledgerRead()) {
+    if (!fs.existsSync(file)) {
+      out.push({ target: path.basename(file), status: 'missing' });
+      continue;
+    }
+    const txt = fs.readFileSync(file, 'utf8');
+    if (!txt.includes(key)) {
+      out.push({ target: path.basename(file), status: 'already gone' });
+      continue;
+    }
+    backup(file, 'rollback-mcp');
+    if (file.endsWith('.toml')) {
+      const esc = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const re = new RegExp(`\\n?\\[mcp_servers\\."?${esc}"?\\][^\\[]*`, 'g');
+      fs.writeFileSync(file, txt.replace(re, ''));
+    } else if (file.endsWith('.jsonc')) {
+      const re = new RegExp(`${JSON.stringify(key).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:\\s*\\{[^{}]*\\},?\\s*`, 'g');
+      fs.writeFileSync(file, txt.replace(re, ''));
+    } else {
+      const obj = JSON.parse(txt);
+      for (const rk of ['mcpServers', 'servers']) {
+        if (obj[rk] && typeof obj[rk] === 'object' && key in obj[rk]) {
+          delete obj[rk][key];
+          break;
+        }
+      }
+      if (key in obj) delete obj[key];
+      fs.writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+    }
+    out.push({ target: path.basename(file), status: 'removed' });
+  }
+  fs.writeFileSync(LEDGER, '[]');
+  return out;
+}
+
+/* ---------------- stale path repair ---------------- */
+
+const STALE_FROM = 'AI tutorial';
+const STALE_TO = 'all-in-one-repo';
+
+/** Repair registry pointers broken by the folder rename. Returns per-file results. */
+export function fixPaths() {
+  const home = os.homedir();
+  const targets = [
+    path.join(home, 'AGENTS.md'),
+    path.join(home, '.claude', 'CLAUDE.md'),
+    path.join(home, '.config', 'opencode', 'AGENTS.md'),
+    path.join(home, '.kimi-code', 'AGENTS.md'),
+    path.join(home, '.jcode', 'AGENTS.md'),
+    path.join(home, '.codex', 'AGENTS.md'),
+    path.join(home, '.gemini', 'GEMINI.md'),
+  ];
+  const results = [];
+  for (const file of targets) {
+    if (!fs.existsSync(file)) continue;
+    const txt = fs.readFileSync(file, 'utf8');
+    if (!txt.includes(STALE_FROM)) continue;
+    const count = txt.split(STALE_FROM).length - 1;
+    backup(file, 'pathfix');
+    fs.writeFileSync(file, txt.split(STALE_FROM).join(STALE_TO));
+    results.push({ target: file, status: `repaired ${count} path reference(s)` });
+  }
+  return results;
+}