rigjs 3.0.33 → 4.0.2

package/lib/crew/vault.ts

@@ -0,0 +1,266 @@
+import fs from 'fs';
+import path from 'path';
+import { CrewEntry, CrewProject, DEFAULT_CREW_ROOT } from './config';
+import { CrewRoleDefinition, roleDefinitionsForCrew } from './role';
+
+export function crewRoot(crew: CrewEntry): string {
+  return path.join(crew.vault, crew.root || DEFAULT_CREW_ROOT);
+}
+
+export function crewPath(crew: CrewEntry, rel: string): string {
+  return path.join(crew.vault, rel);
+}
+
+export function rootPath(crew: CrewEntry, rel: string): string {
+  return path.join(crewRoot(crew), rel);
+}
+
+export function ensureCrewVault(crew: CrewEntry): void {
+  ensureDir(crew.vault);
+  ensureDir(crewPath(crew, 'tmp'));
+  writeIfMissing(crewPath(crew, 'tmp/.gitkeep'), '');
+  fs.mkdirSync(crewRoot(crew), { recursive: true });
+  writeIfMissing(rootPath(crew, 'Current-Goal.md'), '# Current Goal\n\n');
+  writeIfMissing(rootPath(crew, 'Team-Dashboard.md'), '# Team Dashboard\n\nCoding agents can run `rig crew board` to refresh this dashboard.\n');
+  writeIfMissing(rootPath(crew, 'Inbox.md'), '# Crew Inbox\n\n## Open\n\n## Resolved\n');
+
+  ensureDir(rootPath(crew, 'Shared'));
+  writeIfMissing(rootPath(crew, 'Shared/Spec.md'), '# Spec\n\n');
+  writeIfMissing(rootPath(crew, 'Shared/Decisions.md'), '# Decisions\n\n');
+  writeIfMissing(rootPath(crew, 'Shared/Glossary.md'), '# Glossary\n\n');
+  writeIfMissing(rootPath(crew, 'Shared/Context.md'), '# Context\n\n');
+  ensureDir(rootPath(crew, 'Shared/PRDs'));
+  writeIfMissing(rootPath(crew, 'Shared/PRDs/.gitkeep'), '');
+
+  const roles = roleDefinitionsForCrew(crew);
+  for (const role of roles) ensureRole(crew, role);
+  writeRoleRegistry(crew, roles);
+  ensureDir(rootPath(crew, 'Projects'));
+  for (const project of crew.projects || []) ensureProject(crew, project);
+  ensureDir(rootPath(crew, 'Logs'));
+  writeVaultAgentInstructions(crew);
+}
+
+export function ensureProject(crew: CrewEntry, project: CrewProject): void {
+  const base = rootPath(crew, path.join('Projects', project.name));
+  ensureDir(base);
+  writeProjectOwnerFile(path.join(base, 'Owner.md'), project);
+  writeIfMissing(path.join(base, 'Context.md'), `# ${project.name} Context\n\n`);
+  writeIfMissing(path.join(base, 'Tasks.md'), `# ${project.name} Tasks\n\n`);
+  writeIfMissing(path.join(base, 'Decisions.md'), `# ${project.name} Decisions\n\n`);
+  writeIfMissing(path.join(base, 'Test-Plan.md'), `# ${project.name} Test Plan\n\n`);
+  ensureDir(path.join(base, 'PRDs'));
+  writeIfMissing(path.join(base, 'PRDs', '.gitkeep'), '');
+  ensureDir(path.join(base, 'Reports'));
+  writeIfMissing(path.join(base, 'Reports', '.gitkeep'), '');
+}
+
+export function readText(file: string): string {
+  if (!fs.existsSync(file)) return '';
+  return fs.readFileSync(file, 'utf8');
+}
+
+export function writeText(file: string, content: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf8');
+}
+
+export function appendLog(crew: CrewEntry, message: string): void {
+  const d = new Date();
+  const name = d.toISOString().slice(0, 10) + '.md';
+  const file = rootPath(crew, path.join('Logs', name));
+  if (!fs.existsSync(file)) writeText(file, `# ${name.slice(0, 10)}\n\n`);
+  fs.appendFileSync(file, `- ${d.toISOString()} ${message}\n`, 'utf8');
+}
+
+function ensureRole(crew: CrewEntry, role: CrewRoleDefinition): void {
+  const folder = role.folder;
+  const base = rootPath(crew, folder);
+  ensureDir(base);
+  writeIfMissing(path.join(base, 'Tasks.md'), `# ${folder} Tasks\n\n`);
+  writeIfMissing(path.join(base, 'Notes.md'), `# ${folder} Notes\n\n`);
+  if (role.name === 'lead') {
+    ensureDir(path.join(base, 'Reports'));
+    writeIfMissing(path.join(base, 'Reports', '.gitkeep'), '');
+  }
+  if (role.name === 'pm') {
+    ensureDir(path.join(base, 'PRDs'));
+    writeIfMissing(path.join(base, 'PRDs', '.gitkeep'), '');
+    writeIfMissing(path.join(base, 'Reviews.md'), '# PM Reviews\n\n');
+  }
+  if (role.name === 'researcher') {
+    ensureDir(path.join(base, 'Reports'));
+    writeIfMissing(path.join(base, 'Reports', '.gitkeep'), '');
+    writeIfMissing(path.join(base, 'Index.md'), '# Research Index\n\n');
+  }
+  if (!role.builtIn) {
+    ensureDir(path.join(base, 'Reports'));
+    writeIfMissing(path.join(base, 'Reports', '.gitkeep'), '');
+    writeIfMissing(path.join(base, 'Role.md'), renderRoleFile(role));
+  }
+}
+
+function writeRoleRegistry(crew: CrewEntry, roles: CrewRoleDefinition[]): void {
+  const file = rootPath(crew, 'Shared/Roles.md');
+  cleanupLegacyRoleRegistry(file);
+  const rows = roles.map(role => {
+    const prompt = role.promptPath ? role.promptPath.replace(crewPathForHome(), '$RIG_HOME') : '-';
+    return `| ${role.name} | ${role.title} | ${role.agent || '-'} | ${role.defaultExecutor || '-'} | ${role.folder} | ${prompt} |`;
+  });
+  upsertManagedBlock(file, [
+    '<!-- rig-crew-roles:start -->',
+    '## Generated Role Registry',
+    '',
+    'Generated by `rig crew`. Edit global custom roles under `$RIG_HOME/crew/roles/` (`~/.rig/crew/roles/` by default). Add human notes outside this managed block.',
+    '',
+    '| Role | Title | Agent | Executor | Vault Folder | Prompt |',
+    '|---|---|---|---|---|---|',
+    ...rows,
+    '',
+    '<!-- rig-crew-roles:end -->',
+  ].join('\n'), '# Crew Role Registry\n\n');
+}
+
+function cleanupLegacyRoleRegistry(file: string): void {
+  if (!fs.existsSync(file)) return;
+  const current = readText(file);
+  if (!current.includes('Generated by `rig crew`.')) return;
+  if (!current.includes('| Role | Title | Agent | Executor | Vault Folder | Prompt |')) return;
+  const marker = '<!-- rig-crew-roles:start -->';
+  const markerIndex = current.indexOf(marker);
+  const before = markerIndex >= 0 ? current.slice(0, markerIndex) : current;
+  const after = markerIndex >= 0 ? current.slice(markerIndex) : '';
+  const lines = before.split(/\r?\n/);
+  const generated = lines.findIndex(line => line.startsWith('Generated by `rig crew`.'));
+  const table = lines.findIndex((line, i) => i > generated && line.startsWith('| Role | Title | Agent | Executor | Vault Folder | Prompt |'));
+  if (generated < 0 || table < 0) return;
+  let end = table + 1;
+  while (end < lines.length && lines[end].trim().startsWith('|')) end++;
+  while (end < lines.length && lines[end].trim() === '') end++;
+  const cleanedBefore = lines.slice(0, generated).concat(lines.slice(end)).join('\n').trimEnd();
+  const next = [cleanedBefore, after.trimStart()].filter(Boolean).join('\n\n').trimEnd() + '\n';
+  if (next !== current) writeText(file, next);
+}
+
+function renderRoleFile(role: CrewRoleDefinition): string {
+  return [
+    `# ${role.title}`,
+    '',
+    `Role: ${role.name}`,
+    `Agent: ${role.agent || '-'}`,
+    `Executor: ${role.defaultExecutor || '-'}`,
+    `Prompt: ${role.promptPath || '-'}`,
+    '',
+    role.description || '',
+    '',
+  ].join('\n');
+}
+
+function crewPathForHome(): string {
+  return process.env.RIG_HOME || path.join(process.env.HOME || '', '.rig');
+}
+
+const AGENT_RULES_START = '<!-- rig-crew:start -->';
+const AGENT_RULES_END = '<!-- rig-crew:end -->';
+
+function writeVaultAgentInstructions(crew: CrewEntry): void {
+  const targets = ['CLAUDE.md', 'AGENTS.md'].map(file => crewPath(crew, file));
+  const seen = new Set<string>();
+  for (const file of targets) {
+    const key = fs.existsSync(file) ? fs.realpathSync(file) : file;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    upsertManagedBlock(file, renderVaultAgentInstructions(crew));
+  }
+}
+
+function upsertManagedBlock(file: string, block: string, missingContent?: string): void {
+  const current = fs.existsSync(file) ? readText(file) : (missingContent || `# ${path.basename(file, '.md')}\n\n`);
+  const markers = managedMarkers(block);
+  const re = new RegExp(`${escapeRegExp(markers.start)}[\\s\\S]*?${escapeRegExp(markers.end)}`);
+  const next = re.test(current)
+    ? current.replace(re, block.trimEnd())
+    : `${current.trimEnd()}\n\n${block.trimEnd()}`;
+  if (next !== current) writeText(file, `${next.trimEnd()}\n`);
+}
+
+function managedMarkers(block: string): { start: string; end: string } {
+  const lines = block.split(/\r?\n/).map(l => l.trim());
+  const start = lines.find(l => /^<!--\s*[-a-z0-9]+:start\s*-->$/.test(l));
+  const end = lines.find(l => /^<!--\s*[-a-z0-9]+:end\s*-->$/.test(l));
+  if (!start || !end) throw new Error('managed block requires start/end markers');
+  return { start, end };
+}
+
+function renderVaultAgentInstructions(crew: CrewEntry): string {
+  const root = crew.root || DEFAULT_CREW_ROOT;
+  return [
+    AGENT_RULES_START,
+    '## Rig Crew',
+    '',
+    'This Vault uses `rig crew` as an agent-facing coordination layer. Humans talk to the current Claude/Codex coding session; the coding agent uses `rig crew` and Vault files to communicate with Crew Lead and coordinate other roles.',
+    '',
+    `- Crew root: \`${root}\``,
+    `- Dashboard: \`${root}/Team-Dashboard.md\``,
+    `- Inbox: \`${root}/Inbox.md\``,
+    `- Role registry: \`${root}/Shared/Roles.md\``,
+    `- Project owner memory: \`${root}/Projects/<project>/\``,
+    `- Custom role workspaces: \`${root}/Roles/<role>/\``,
+    '- Vault-local scratch projects belong under `tmp/<project>/`.',
+    '- User-level rules, test accounts, custom roles, and research output policy live under `~/.rig/`.',
+    '- Coordinate through Vault files; do not start or assume a separate multi-agent runtime inside a project repo.',
+    '- Do not copy secrets, auth state, production traces, or personal data into project repositories.',
+    '- When working on project code, also read that project\'s `RIG.md` or `rig.md` if present.',
+    '',
+    'Default collaboration protocol for coding agents:',
+    '',
+    '0. Do not treat `rig crew` as a human-facing command workflow. If you can run the command or update the Vault files yourself, do it instead of asking the human to run it.',
+    '1. If the user asks for planning, multi-agent coordination, PRD, research, testing strategy, project owner work, role routing, reports, or broad project changes, hand the request to Crew Lead first.',
+    `2. Preferred handoff: run \`rig crew "<user request>"\`, then read \`${root}/Team-Dashboard.md\`, \`${root}/Inbox.md\`, and \`${root}/Shared/Roles.md\`.`,
+    `3. Maintain status awareness before and after work by checking \`${root}/Team-Dashboard.md\`, \`${root}/Inbox.md\`, \`${root}/Shared/Roles.md\`, role \`Tasks.md\`, and project \`Tasks.md\` files.`,
+    `4. If the CLI is unavailable, append the request to \`${root}/Current-Goal.md\` and create/update a Lead task in \`${root}/Lead/Tasks.md\`; then refresh the dashboard when possible.`,
+    '5. Treat Crew Lead as the default orchestrator prompt/protocol, not as a required Claude/Codex subagent. Subagents may be used as optional executors for specific roles, but Vault files are the source of truth.',
+    '6. Lead communicates with other roles through Markdown tasks and delegation packets, not private chat state. Use `[role:: <role>]`, `[owner:: <owner>]`, `[project:: <project>]`, `[executor:: <executor>]`, and status fields in the relevant `Tasks.md`.',
+    `7. Worker results must be written back to the relevant role/project files under \`${root}/\`; user-facing questions go to \`${root}/Inbox.md\` for Lead to surface.`,
+    '',
+    AGENT_RULES_END,
+  ].join('\n');
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function writeProjectOwnerFile(file: string, project: CrewProject): void {
+  const owner = project.owner || `maintainer:${project.name}`;
+  const fresh = `# ${owner}\n\nProject: ${project.name}\nPath: ${project.path}\n`;
+  if (!fs.existsSync(file)) {
+    writeText(file, fresh);
+    return;
+  }
+  const current = readText(file);
+  let next = current;
+  if (!next.trim()) next = fresh;
+  else {
+    const lines = next.split(/\r?\n/);
+    if (lines[0].startsWith('# maintainer:') || lines[0] === `# ${owner}`) lines[0] = `# ${owner}`;
+    next = lines.join('\n');
+    next = upsertLine(next, /^Project:\s*.*$/m, `Project: ${project.name}`);
+    next = upsertLine(next, /^Path:\s*.*$/m, `Path: ${project.path}`);
+  }
+  if (next !== current) writeText(file, next);
+}
+
+function upsertLine(text: string, pattern: RegExp, line: string): string {
+  if (pattern.test(text)) return text.replace(pattern, line);
+  return text.endsWith('\n') ? `${text}${line}\n` : `${text}\n${line}\n`;
+}
+
+function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeIfMissing(file: string, content: string): void {
+  if (fs.existsSync(file)) return;
+  writeText(file, content);
+}

package/lib/installLocal.ts

@@ -0,0 +1,189 @@
+// `rig install-local` — build the current source tree and install it as the
+// global `rig` binary so edits become reachable as the on-PATH `rig`.
+//
+// Strategy (in order):
+//   1. Build (yarn build).
+//   2. If <npm prefix>/lib/node_modules/rigjs exists and is user-writable,
+//      do an in-place sync of the package.json `files[]` payload. This avoids
+//      EACCES on a root-owned npm prefix that already has a user-owned rigjs
+//      subdir (the common Homebrew-then-sudo-first-install pattern).
+//   3. Otherwise fall back to `npm install -g <repoRoot>`.
+//   4. Re-link the agent skill via `rig wiki install-skill --force`.
+//
+// A subsequent `npm i -g rigjs` (registry install) cleanly overwrites step 2.
+
+import fs from 'fs';
+import path from 'path';
+import { execSync, spawnSync } from 'child_process';
+import print from './print';
+
+interface InstallLocalOpts {
+	skipBuild?: boolean;
+	manager?: 'npm' | 'yarn';
+}
+
+export default function installLocal(opts: InstallLocalOpts = {}): void {
+	// `__dirname/..` would point at the *installed* rigjs dir when invoked via
+	// the global binary — that's the destination, not the source. Walk up from
+	// CWD instead, so the user gets "install whatever I'm hacking on right now".
+	const repoRoot = findSourceRoot();
+	if (!repoRoot) {
+		print.error('run `rig install-local` from inside the rigjs source tree (a dir with package.json {"name":"rigjs"}).');
+		process.exit(1);
+	}
+
+	if (!opts.skipBuild) {
+		print.start('yarn build');
+		const build = spawnSync('yarn', ['build'], { cwd: repoRoot, stdio: 'inherit' });
+		if (build.status !== 0) {
+			print.error(`yarn build exited with code ${build.status}`);
+			process.exit(build.status ?? 1);
+		}
+		print.succeed('build done');
+	}
+
+	const dest = findInstallDir();
+	if (dest && canWriteInside(dest)) {
+		syncInPlace(repoRoot, dest);
+	} else {
+		runPackageManager(repoRoot, opts.manager || 'npm');
+	}
+
+	// Always refresh the agent skill symlink so edits to RIG_WIKI_SKILL.md
+	// take effect on next Claude Code restart.
+	const link = spawnSync('rig', ['wiki', 'install-skill', '--force'], { stdio: 'inherit' });
+	if (link.status !== 0) {
+		print.warn('skill relink exited non-zero (often safe to ignore; re-run `rig wiki install-skill --force` manually if needed).');
+	}
+
+	const which = whichRig();
+	print.succeed(`installed: ${which || 'rig'} — verify with \`rig -v\` (expect ${readVersion(repoRoot)}) and \`rig -c\` (expect ${readVersionCode(repoRoot) ?? '<empty>'}).`);
+}
+
+function findSourceRoot(start: string = process.cwd()): string | null {
+	let dir = path.resolve(start);
+	while (true) {
+		const pkg = path.join(dir, 'package.json');
+		if (fs.existsSync(pkg)) {
+			try {
+				const p = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+				if (p && p.name === 'rigjs') return dir;
+			} catch { /* keep walking */ }
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+// Locate the existing global rigjs install dir without invoking npm (faster,
+// and tolerates broken npm configs).
+function findInstallDir(): string | null {
+	try {
+		const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
+		const candidate = path.join(prefix, 'lib', 'node_modules', 'rigjs');
+		return fs.existsSync(candidate) ? candidate : null;
+	} catch {
+		return null;
+	}
+}
+
+function canWriteInside(dir: string): boolean {
+	try {
+		const probe = path.join(dir, '.rig-write-probe');
+		fs.writeFileSync(probe, '');
+		fs.unlinkSync(probe);
+		return true;
+	} catch { return false; }
+}
+
+// Copy the subset that `package.json files[]` would ship into the existing
+// rigjs install dir. Uses rsync for speed + deletion of stale files inside
+// per-entry dirs. Does not touch the rigjs/node_modules tree.
+function syncInPlace(repoRoot: string, dest: string): void {
+	print.start(`sync in place -> ${dest}`);
+	const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+	const files: string[] = Array.isArray(pkg.files) ? pkg.files : [];
+
+	// Always-shipped top-level files alongside package.json
+	const alwaysFiles = ['package.json'];
+
+	// 1. top-level files
+	for (const f of [...alwaysFiles, ...files.filter(isFile(repoRoot))]) {
+		const src = path.join(repoRoot, f);
+		const dst = path.join(dest, f);
+		if (!fs.existsSync(src)) continue;
+		fs.mkdirSync(path.dirname(dst), { recursive: true });
+		fs.copyFileSync(src, dst);
+	}
+
+	// 2. directory entries -> rsync --delete (mirrors the source for that dir)
+	const dirs = files.filter(isDir(repoRoot));
+	for (const d of dirs) {
+		const src = path.join(repoRoot, d) + '/';
+		const dst = path.join(dest, d) + '/';
+		fs.mkdirSync(path.dirname(dst.replace(/\/$/, '')), { recursive: true });
+		const r = spawnSync('rsync', ['-a', '--delete', src, dst], { stdio: 'inherit' });
+		if (r.status !== 0) {
+			print.error(`rsync ${d} failed (code ${r.status})`);
+			process.exit(r.status ?? 1);
+		}
+	}
+
+	// node_modules is not in package.json `files[]` (npm install handles it
+	// for registry installs), so the in-place sync must mirror it explicitly.
+	// rsync's delta transfer keeps this cheap on incremental dep changes.
+	const srcNm = path.join(repoRoot, 'node_modules');
+	if (fs.existsSync(srcNm)) {
+		const dstNm = path.join(dest, 'node_modules');
+		const r = spawnSync('rsync', ['-a', '--delete', srcNm + '/', dstNm + '/'], { stdio: 'inherit' });
+		if (r.status !== 0) {
+			print.error(`rsync node_modules failed (code ${r.status})`);
+			process.exit(r.status ?? 1);
+		}
+	}
+
+	// Always force exec bit on the launcher — rsync preserves source mode, and
+	// repos that lost the exec bit (common after fresh clones on some setups)
+	// would leave the global `rig` un-runnable. Cheap to always re-set.
+	const launcher = path.join(dest, 'bin', 'rig.js');
+	try { fs.chmodSync(launcher, 0o755); } catch { /* not fatal */ }
+
+	print.succeed(`sync done`);
+}
+
+function isFile(repoRoot: string) {
+	return (f: string) => {
+		try { return fs.statSync(path.join(repoRoot, f)).isFile(); } catch { return false; }
+	};
+}
+
+function isDir(repoRoot: string) {
+	return (f: string) => {
+		try { return fs.statSync(path.join(repoRoot, f)).isDirectory(); } catch { return false; }
+	};
+}
+
+function runPackageManager(repoRoot: string, manager: 'npm' | 'yarn') {
+	const cmd = manager === 'yarn'
+		? ['yarn', ['global', 'add', `file:${repoRoot}`]]
+		: ['npm', ['install', '-g', repoRoot]];
+	print.start(`${cmd[0]} ${(cmd[1] as string[]).join(' ')}`);
+	const r = spawnSync(cmd[0] as string, cmd[1] as string[], { cwd: repoRoot, stdio: 'inherit' });
+	if (r.status !== 0) {
+		print.error(`${cmd[0]} exited with code ${r.status}. If this is EACCES on /usr/local, either rerun with sudo, switch the npm prefix to a user dir, or chown the rigjs subtree.`);
+		process.exit(r.status ?? 1);
+	}
+}
+
+function readVersion(repoRoot: string): string {
+	return JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).version;
+}
+function readVersionCode(repoRoot: string): number | null {
+	const v = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).versionCode;
+	return v != null ? v : null;
+}
+function whichRig(): string | null {
+	try { return execSync('command -v rig', { encoding: 'utf8' }).trim() || null; }
+	catch { return null; }
+}

package/lib/rig/index.ts

@@ -9,13 +9,22 @@ import deploy from '../deploy';
 import publish from '../publish';
 
 import sync from '../sync';
-const nodeMin = '14.0.0';
+const nodeMin = '22.0.0';
 if (semver.gte(nodeMin,process.version)){
-	print.error('NodeJS version must be at least 14.');
+	print.error('NodeJS version must be at least 22 (better-sqlite3 12.x prebuilds require it).');
 	process.exit(0);
 }
 import {Command} from 'commander';
 
+// Short-circuit `-c` / `--versioncode` before commander parses subcommands,
+// mirroring how commander handles `-v` itself.
+if (process.argv.some(a => a === '-c' || a === '--versioncode')) {
+	const pkg = require('../../package.json');
+	// eslint-disable-next-line no-console
+	console.log(pkg.versionCode ?? '');
+	process.exit(0);
+}
+
 const program = new Command();
 
 import check from '../check';
@@ -29,6 +38,14 @@ import install from '../install';
 program.command('install').action(install);
 program.command('i').action(install);
 
+import installLocal from '../installLocal';
+
+program.command('install-local')
+	.description('build the current source tree and install it as the global `rig`')
+	.option('--skip-build', 'skip `yarn build` (use existing built/index.js)')
+	.option('--manager <name>', 'npm | yarn (default: npm)')
+	.action(installLocal);
+
 program.command('preinstall').action(preinstall);
 program.command('postinstall').action(postinstall);
 import tag from '../tag';
@@ -66,10 +83,16 @@ program.command('sync')
 	.option('-f, --force <force>', 'force to overwrite files from package.rig.json5')
 	.action(sync);
 
+import { registerWikiCommands } from '../wiki';
+registerWikiCommands(program);
+
+import { registerCrewCommands } from '../crew';
+registerCrewCommands(program);
+
 import env from '../env';
 
 program.option('--env <env>', 'specify env').action(env.load);
 
 program.version(require('../../package.json').version, '-v,--version');
+program.option('-c, --versioncode', 'output the version code (YYMMDDNN)');
 program.parse(process.argv);
-

package/lib/wiki/README.md

@@ -0,0 +1,79 @@
+# lib/wiki — `rig wiki *` source map
+
+> Companion to `doc/architecture/wiki.md`. This file documents *what each source file does*; the architecture doc covers *why* and *how it fits together*.
+
+Convention: **one file per subcommand**, plus a small set of shared infra files at the top of the directory. Subcommand groups (`agent`, `daemon`) live in their own subfolder, and each sub-subcommand also gets its own file there.
+
+---
+
+## Shared infrastructure
+
+| File | Purpose |
+|---|---|
+| `index.ts` | Commander wiring. Builds the `rig wiki` subtree and attaches every action. Imported once from `lib/rig/index.ts`. |
+| `paths.ts` | Centralized filesystem paths (`~/.rig/`, launchd plist, Claude skills dir). Override with `RIG_HOME`. Also exports the launchd label. |
+| `platform.ts` | `requireMacOS()` — hard-exits with code 32 on non-Darwin platforms. v1 is macOS-only by decision; see roadmap P5. |
+| `config.ts` | JSON5 read/write for `~/.rig/config.json5` (`RigConfig`) and `~/.rig/wiki.config.json5` (`WikiConfig`). `resolveWiki()` picks the target wiki for a command (flag → CWD walk → undefined). |
+| `db.ts` | Lazy-loaded `better-sqlite3` singleton. WAL mode. Idempotent migrations on every open. Exposes `getDb()`, `recordLastRun()`, `getLastRun()`. |
+| `qmd.ts` | Detects `qmd` on PATH, wraps `qmd query --json` and `qmd embed`. All callers must handle `installed=false` gracefully — qmd is optional. |
+
+---
+
+## Subcommands (one file each)
+
+| File | Subcommand | What it does |
+|---|---|---|
+| `init.ts` | `rig wiki init [path]` | Bootstraps a fresh wiki dir: `purpose.md` + `schema.md` from templates, empty `index.md` / `overview.md` / `log.md` / `reviews.md`, `raw/` + five `wiki/<sub>/` dirs. Idempotent — never overwrites existing files. Does **not** register. |
+| `register.ts` | `rig wiki register [path]` | Adds (or `--force`-replaces) an entry in `~/.rig/wiki.config.json5`. Auto-detects path (`harness/llm-wiki` / `wiki`) walking up from CWD. Also writes a `wiki:` block back to the project's `package.rig.json5` for bidirectional consistency. |
+| `unregister.ts` | `rig wiki unregister <nameOrPath>` | Removes the entry. Disk wiki content is untouched. |
+| `list.ts` | `rig wiki list` | Prints a table: name, path, page count, last scan / ingest / lint. Banner row shows detected agent CLI, qmd status. |
+| `scan.ts` | `rig wiki scan [path]` | Walks `include` globs + `raw/`, sha256-compares against the `source_sha` table in `state.db`. Emits NEW / MODIFIED / DELETED / RAW DRIFT report. Returns exit code 10 if any RAW DRIFT (raw/ files are immutable). No agent calls. |
+| `fetch.ts` | `rig wiki fetch <url>` | (stub — P1) Agent-as-fetcher. Will WebFetch the URL via Claude adapter and write `raw/YYYY-MM-DD-<slug>.md` verbatim with frontmatter. **Never** summarizes. |
+| `ingest.ts` | `rig wiki ingest <source>` | (stub — P1) Two-step CoT (analysis → generation). Sandbox-copies the wiki dir, runs Claude adapter, then host-diffs sandbox vs original to extract writes. Filters out edits to `raw/` / `purpose.md` / `schema.md`. `--dry-run` prints diff without applying. |
+| `query.ts` | `rig wiki query "..."` | (stub — P1) Answer a question with `[[wikilink]]` citations. Prefers `qmd query --json` for retrieval; falls back to injecting `index.md` + `overview.md` + heuristic page picks. |
+| `lint.ts` | `rig wiki lint` | (stub — P1) Walks the wiki for contradictions, orphans, stale claims, broken `sources[]` refs, reviews.md backlog. Writes `lint-report-YYYY-MM-DD.md`. Non-zero exit on severe findings (code 11). |
+| `indexCmd.ts` | `rig wiki index` | qmd-only. Ensures the wiki's qmd collection exists, then runs `qmd embed`. When qmd is absent: warns and exits 0 (qmd is optional). Named `indexCmd` to avoid clashing with `index.ts`. |
+| `installSkill.ts` | `rig wiki install-skill` | Locates rig's bundled `.claude/skills/rig-wiki/` inside the rigjs install, then symlinks it into `~/.claude/skills/rig-wiki`. Lets every machine with rig installed get the slash command without manual copy. |
+| `uninstallSkill.ts` | `rig wiki uninstall-skill` | Removes the symlink. |
+
+---
+
+## `agent/` — Agent CLI adapter
+
+One adapter per agent CLI. Only Claude Code is implemented in v1; others are stubs whose `detect()` works but `run()` throws `NotImplementedError`.
+
+| File | Purpose |
+|---|---|
+| `index.ts` | Registers the `agent` Commander subtree. Re-exports `adapters` + `getAdapter` from `registry.ts` for callers that don't want to know about the registry split. |
+| `registry.ts` | Constructs the singleton `adapters` array (one of each adapter class) and exports `getAdapter(name)`. Kept separate from `index.ts` to avoid a circular import with `list.ts`. |
+| `types.ts` | The `AgentAdapter` interface and run-options/result types. All adapters obey it so the host can swap them. |
+| `claude.ts` | **Full implementation.** Spawns `claude -p` (non-interactive) with `--allowedTools` derived from `allowWrite` + requested tools. Prepends a hard-coded system-prompt header that forbids editing `raw/` / `purpose.md` / `schema.md`. |
+| `codex.ts` | Stub. Detection works; `run()` throws. Open questions on codex's permission flags live in `doc/architecture/agents.md §4`. |
+| `pi.ts` | Stub. Same shape as codex. Upstream CLI name not yet fixed. |
+| `list.ts` | `rig wiki agent list` — iterates `adapters`, calls `detect()`, prints a table. Marks the default agent with `*`. |
+| `use.ts` | `rig wiki agent use <name>` — writes `~/.rig/config.json5` `wiki.defaultAgent`. Rejects un-implemented adapters with exit code 20. |
+
+---
+
+## `daemon/` — launchd-managed background runner
+
+| File | Purpose |
+|---|---|
+| `index.ts` | Registers the `daemon` Commander subtree. |
+| `install.ts` | Writes `~/Library/LaunchAgents/ai.flashhand.rig.wiki.plist` (with discovered node + rig entry paths), then `launchctl bootout` (idempotent) + `bootstrap`. |
+| `uninstall.ts` | `launchctl bootout` + remove the plist. |
+| `start.ts` | `launchctl bootstrap` only (use after `install` if you've stopped manually). |
+| `stop.ts` | `launchctl bootout` only. |
+| `status.ts` | `launchctl print gui/<uid>/<label>`, parses `state=` and `pid=`. |
+| `logs.ts` | Tails `~/.rig/logs/wiki-daemon.log` (with optional `-f`). |
+| `runner.ts` | **The launchd entry.** `launchctl` invokes `node <rigjs>/built/index.js wiki daemon runner`. v1: heartbeat-only loop that logs every 10 min and reloads `wiki.config.json5`. P2 will add cron-based scan/lint scheduling and `auto-on-new` ingest rules. |
+
+---
+
+## Conventions
+
+- Every action default-exports a function the Commander wiring imports as `fooAction`. Subcommand groups (`agent`, `daemon`) instead expose `registerXyzCommands(parent)`.
+- Human output goes through `lib/print` (ora + chalk). Machine output is `--json` and goes to plain `console.log` (so JSON doesn't get ANSI-painted).
+- Anything that writes to disk under `~/.rig/` first calls a helper in `config.ts` that `mkdir -p`s the home dir. Subcommands don't open-code path creation.
+- The DB and qmd helpers are lazy-loaded so subcommands that don't need them (e.g. `init`, `agent list`) start instantly and don't drag in the native binary.
+- No subcommand calls another subcommand directly — they share state via `config.ts` + `db.ts`. This keeps each file a leaf.

package/lib/wiki/agent/claude.ts

@@ -0,0 +1,65 @@
+import { spawn, spawnSync } from 'child_process';
+import { AgentAdapter, AgentDetect, AgentRunOpts, AgentRunResult } from './types';
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
+
+const SYSTEM_PROMPT_HEADER = `You are the executor for \`rig wiki <op>\`.
+You MUST follow <wiki>/schema.md exactly.
+You MUST NOT edit raw/, purpose.md, schema.md. The host will reject any such patch.
+Output is consumed by a CLI; keep stdout to status updates only. Persist actual content by writing files.
+`;
+
+export class ClaudeAdapter implements AgentAdapter {
+  name = 'claude' as const;
+
+  async detect(): Promise<AgentDetect> {
+    const which = spawnSync('command', ['-v', 'claude'], { encoding: 'utf8', shell: '/bin/sh' });
+    const binPath = (which.stdout || '').trim();
+    if (which.status !== 0 || !binPath) return { installed: false };
+    const v = spawnSync('claude', ['--version'], { encoding: 'utf8' });
+    const version = (v.stdout || '').trim() || undefined;
+    return { installed: true, path: binPath, version };
+  }
+
+  async run(opts: AgentRunOpts): Promise<AgentRunResult> {
+    const args = ['-p'];
+    args.push('--allowedTools', allowedToolsCsv(opts));
+    if (opts.systemPrompt || SYSTEM_PROMPT_HEADER) {
+      args.push('--append-system-prompt', SYSTEM_PROMPT_HEADER + (opts.systemPrompt || ''));
+    }
+    args.push(opts.prompt);
+    const start = Date.now();
+    return new Promise<AgentRunResult>((resolve) => {
+      const child = spawn('claude', args, {
+        cwd: opts.cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: process.env,
+      });
+      let stdout = '', stderr = '';
+      child.stdout.on('data', (d) => { stdout += d.toString(); });
+      child.stderr.on('data', (d) => { stderr += d.toString(); });
+      const killer = setTimeout(() => child.kill('SIGTERM'),
+                                opts.timeoutMs || DEFAULT_TIMEOUT_MS);
+      child.on('close', (code) => {
+        clearTimeout(killer);
+        resolve({
+          ok: code === 0,
+          exitCode: code ?? -1,
+          stdout, stderr,
+          durationMs: Date.now() - start,
+        });
+      });
+    });
+  }
+}
+
+function allowedToolsCsv(opts: AgentRunOpts): string {
+  const tools = new Set<string>(['Read']);
+  if (opts.allowWrite) { tools.add('Write'); tools.add('Edit'); }
+  for (const t of opts.tools || []) {
+    if (t === 'webfetch') tools.add('WebFetch');
+    if (t === 'qmd') tools.add('Bash(qmd:*)');
+    if (t === 'bash') tools.add('Bash');
+  }
+  return Array.from(tools).join(',');
+}