@ag-eco/agentplate-cli 0.13.0

package/src/tools/loam/commands/move.ts

@@ -0,0 +1,323 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import { getRegistry } from "../registry/type-registry.ts";
+import type { ExpertiseRecord } from "../schemas/record.ts";
+import { getExpertiseDir, getExpertisePath, readConfig } from "../utils/config.ts";
+import {
+	findMissingDomainFields,
+	getAllowedTypes,
+	getRequiredFields,
+} from "../utils/domain-rules.ts";
+import {
+	appendRecord,
+	readExpertiseFile,
+	resolveRecordId,
+	writeExpertiseFile,
+} from "../utils/expertise.ts";
+import { getRecordSummary } from "../utils/format.ts";
+import { runHooks } from "../utils/hooks.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { withFileLock } from "../utils/lock.ts";
+import { accent, brand, isQuiet } from "../utils/palette.ts";
+
+interface MoveOptions {
+	dryRun: boolean;
+	force: boolean;
+}
+
+interface ReferenceHit {
+	domain: string;
+	id: string | null;
+	field: "relates_to" | "supersedes";
+}
+
+// Scan every other expertise file for references (relates_to / supersedes) to
+// the moved record's ID. We don't rewrite — the ID is preserved across the
+// move, so existing links still resolve. The scan exists purely as an
+// informational warning so users can audit the link graph if they care.
+async function findIncomingReferences(
+	movedId: string,
+	cwd: string,
+	skipFiles: Set<string>,
+): Promise<ReferenceHit[]> {
+	const expertiseDir = getExpertiseDir(cwd);
+	if (!existsSync(expertiseDir)) return [];
+	const entries = await readdir(expertiseDir).catch(() => [] as string[]);
+	const hits: ReferenceHit[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".jsonl")) continue;
+		const filePath = join(expertiseDir, entry);
+		if (skipFiles.has(filePath)) continue;
+		const domain = entry.slice(0, -".jsonl".length);
+		const records = await readExpertiseFile(filePath, { allowUnknownTypes: true }).catch(
+			() => [] as ExpertiseRecord[],
+		);
+		for (const r of records) {
+			if (r.relates_to?.includes(movedId)) {
+				hits.push({ domain, id: r.id ?? null, field: "relates_to" });
+			}
+			if (r.supersedes?.includes(movedId)) {
+				hits.push({ domain, id: r.id ?? null, field: "supersedes" });
+			}
+		}
+	}
+	return hits;
+}
+
+export function registerMoveCommand(program: Command): void {
+	program
+		.command("move")
+		.argument("<source-domain>", "current domain")
+		.argument("<id>", "record ID (e.g. mx-abc123, abc123, or abc)")
+		.argument("<target-domain>", "destination domain")
+		.description("Move a record from one domain to another, preserving its ID and metadata")
+		.option("--dry-run", "preview the move without making changes", false)
+		.option(
+			"--force",
+			"bypass target domain's allowed_types gate (required_fields still enforced)",
+			false,
+		)
+		.action(
+			async (sourceDomain: string, id: string, targetDomain: string, options: MoveOptions) => {
+				const jsonMode = program.opts().json === true;
+				try {
+					const config = await readConfig();
+					const availableDomains = Object.keys(config.domains);
+
+					if (sourceDomain === targetDomain) {
+						const msg = "Source and target domain are the same — nothing to move.";
+						if (jsonMode) outputJsonError("move", msg);
+						else console.error(chalk.red(`Error: ${msg}`));
+						process.exitCode = 1;
+						return;
+					}
+
+					for (const d of [sourceDomain, targetDomain]) {
+						if (!(d in config.domains)) {
+							const msg = `Domain "${d}" not found in config. Available domains: ${availableDomains.join(", ") || "(none)"}`;
+							if (jsonMode) outputJsonError("move", msg);
+							else console.error(chalk.red(`Error: ${msg}`));
+							process.exitCode = 1;
+							return;
+						}
+					}
+
+					const sourcePath = getExpertisePath(sourceDomain);
+					const targetPath = getExpertisePath(targetDomain);
+
+					// Read source under its lock to resolve the record. We release
+					// the lock before validating so we don't hold it across hooks /
+					// target lock acquisition — the record is re-fetched under lock
+					// at write time below.
+					const sourceRecords = await withFileLock(sourcePath, async () =>
+						readExpertiseFile(sourcePath),
+					);
+					const resolved = resolveRecordId(sourceRecords, id);
+					if (!resolved.ok) {
+						if (jsonMode) outputJsonError("move", resolved.error);
+						else console.error(chalk.red(`Error: ${resolved.error}`));
+						process.exitCode = 1;
+						return;
+					}
+					const record = resolved.record;
+
+					// Reject archived records. The .loam/archive/ store is walked by
+					// `lm restore` and `lm search --archived`; live expertise files
+					// shouldn't carry archived rows, but a stray status field would.
+					if (record.status === "archived") {
+						const msg = `Record ${record.id ?? id} is archived. Run \`lm restore ${record.id ?? id}\` first.`;
+						if (jsonMode) outputJsonError("move", msg);
+						else console.error(chalk.red(`Error: ${msg}`));
+						process.exitCode = 1;
+						return;
+					}
+
+					// Validate type against target allowed_types
+					const allowedTypes = getAllowedTypes(config, targetDomain);
+					if (allowedTypes && !allowedTypes.includes(record.type) && !options.force) {
+						const msg = `Type "${record.type}" is not in target domain "${targetDomain}" allowed_types (${allowedTypes.join(", ")}). Pass --force to override, or adjust loam.config.yaml.`;
+						if (jsonMode) outputJsonError("move", msg);
+						else console.error(chalk.red(`Error: ${msg}`));
+						process.exitCode = 1;
+						return;
+					}
+
+					// Validate required_fields for target
+					const requiredFields = getRequiredFields(config, targetDomain);
+					if (requiredFields) {
+						const missing = findMissingDomainFields(
+							record as unknown as Record<string, unknown>,
+							requiredFields,
+						);
+						if (missing.length > 0) {
+							const fieldList = missing.map((f) => `"${f}"`).join(", ");
+							const msg = `Record is missing field(s) required by target domain "${targetDomain}": ${fieldList}. Edit the record (\`lm edit ${record.id ?? id}\`) before moving.`;
+							if (jsonMode) outputJsonError("move", msg);
+							else console.error(chalk.red(`Error: ${msg}`));
+							process.exitCode = 1;
+							return;
+						}
+					}
+
+					// Re-validate against the JSON schema. The record is presumed
+					// valid (it was written before), but a registry change since
+					// then could have tightened the schema. This is a cheap
+					// safeguard against silently writing a stale row into the new
+					// domain.
+					const validate = getRegistry().validator;
+					if (!validate(record)) {
+						const errs = (validate.errors ?? [])
+							.map((e) => `${e.instancePath} ${e.message}`)
+							.join("; ");
+						const msg = `Record fails schema validation: ${errs}. Edit the record before moving.`;
+						if (jsonMode) outputJsonError("move", msg);
+						else console.error(chalk.red(`Error: ${msg}`));
+						process.exitCode = 1;
+						return;
+					}
+
+					// Informational scan for inbound references. Skips both source
+					// and target files (target hasn't been written yet; source
+					// references to the record itself are not interesting here).
+					const incomingRefs = await findIncomingReferences(
+						record.id ?? "",
+						process.cwd(),
+						new Set([sourcePath, targetPath]),
+					);
+
+					if (options.dryRun) {
+						if (jsonMode) {
+							outputJson({
+								success: true,
+								command: "move",
+								dryRun: true,
+								sourceDomain,
+								targetDomain,
+								record: {
+									id: record.id ?? null,
+									type: record.type,
+									summary: getRecordSummary(record),
+								},
+								incomingReferences: incomingRefs,
+							});
+						} else if (!isQuiet()) {
+							const rid = record.id ? ` ${accent(record.id)}` : "";
+							console.log(
+								`${chalk.yellow("[DRY RUN]")} ${brand(`Would move ${record.type}`)}${rid} ${brand(
+									`from ${sourceDomain} → ${targetDomain}`,
+								)}: ${getRecordSummary(record)}`,
+							);
+							if (incomingRefs.length > 0) {
+								console.log(
+									chalk.dim(
+										`  ${incomingRefs.length} inbound reference(s) detected; ID is preserved so links remain valid.`,
+									),
+								);
+							}
+						}
+						return;
+					}
+
+					// Fire pre-record against the target domain. A blocked hook
+					// aborts the move (record stays in source intact).
+					const preResult = await runHooks<{ domain: string; record: ExpertiseRecord }>(
+						"pre-record",
+						{ domain: targetDomain, record },
+					);
+					if (preResult.blocked) {
+						const reason = preResult.blockReason ?? "pre-record hook blocked the move";
+						if (jsonMode) outputJsonError("move", reason);
+						else console.error(chalk.red(`Error: ${reason}`));
+						process.exitCode = 1;
+						return;
+					}
+					let recordToWrite = record;
+					if (preResult.ranAny && preResult.payload?.record) {
+						const mutated = preResult.payload.record;
+						if (mutated !== record) {
+							if (!validate(mutated)) {
+								const errs = (validate.errors ?? [])
+									.map((e) => `${e.instancePath} ${e.message}`)
+									.join("; ");
+								const msg = `pre-record hook produced an invalid record: ${errs}`;
+								if (jsonMode) outputJsonError("move", msg);
+								else console.error(chalk.red(`Error: ${msg}`));
+								process.exitCode = 1;
+								return;
+							}
+							recordToWrite = mutated;
+						}
+					}
+
+					// Append to target, then remove from source. Locks are nested
+					// in a fixed order (target before source) to keep concurrent
+					// moves deadlock-free. If a crash lands between the append and
+					// the source rewrite, the record appears in both domains —
+					// recoverable by hand and strictly better than losing it.
+					await withFileLock(targetPath, async () => {
+						await appendRecord(targetPath, recordToWrite);
+						await withFileLock(sourcePath, async () => {
+							const currentSource = await readExpertiseFile(sourcePath);
+							const filtered = currentSource.filter((r) => r.id !== recordToWrite.id);
+							await writeExpertiseFile(sourcePath, filtered);
+						});
+					});
+
+					const postResult = await runHooks("post-record", {
+						domain: targetDomain,
+						record: recordToWrite,
+						action: "created",
+					});
+
+					const warnings = [...preResult.warnings, ...postResult.warnings];
+
+					if (jsonMode) {
+						outputJson({
+							success: true,
+							command: "move",
+							sourceDomain,
+							targetDomain,
+							record: {
+								id: recordToWrite.id ?? null,
+								type: recordToWrite.type,
+								summary: getRecordSummary(recordToWrite),
+							},
+							incomingReferences: incomingRefs,
+							...(warnings.length > 0 ? { warnings } : {}),
+						});
+					} else if (!isQuiet()) {
+						const rid = recordToWrite.id ? ` ${accent(recordToWrite.id)}` : "";
+						console.log(
+							`${brand("✓")} ${brand(`Moved ${recordToWrite.type}`)}${rid} ${brand(
+								`from ${sourceDomain} → ${targetDomain}`,
+							)}: ${getRecordSummary(recordToWrite)}`,
+						);
+						if (incomingRefs.length > 0) {
+							console.log(
+								chalk.yellow(
+									`  ${incomingRefs.length} inbound reference(s) found; ID preserved so existing links still resolve:`,
+								),
+							);
+							for (const ref of incomingRefs) {
+								console.log(chalk.dim(`    ${ref.domain}/${ref.id ?? "(no id)"} via ${ref.field}`));
+							}
+						}
+						for (const w of warnings) console.log(chalk.yellow(`  warning: ${w}`));
+					}
+				} catch (err) {
+					if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+						const msg = "No .loam/ directory found. Run `loam init` first.";
+						if (jsonMode) outputJsonError("move", msg);
+						else console.error(chalk.red(`Error: ${msg}`));
+					} else {
+						if (jsonMode) outputJsonError("move", (err as Error).message);
+						else console.error(chalk.red(`Error: ${(err as Error).message}`));
+					}
+					process.exitCode = 1;
+				}
+			},
+		);
+}

package/src/tools/loam/commands/onboard.ts

@@ -0,0 +1,374 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import chalk from "chalk";
+import type { Command } from "commander";
+import type { SessionCloseConfig } from "../schemas/config.ts";
+import { readConfig } from "../utils/config.ts";
+import { getSessionEndReminder } from "../utils/format.ts";
+import { outputJson, outputJsonError } from "../utils/json-output.ts";
+import { hasMarkerSection, replaceMarkerSection, wrapInMarkers } from "../utils/markers.ts";
+import { isQuiet } from "../utils/palette.ts";
+import { getCurrentVersion } from "../utils/version.ts";
+
+// Single marker carries both display and detection: snippets are considered
+// current iff they include the marker for the running CLI's package version.
+// Patch bumps therefore prompt re-run, which is the desired UX (the visible
+// version in CLAUDE.md should track the installed Loam).
+export function getVersionMarker(): string {
+	return `<!-- loam-onboard:v${getCurrentVersion()} -->`;
+}
+
+function buildSnippet(sessionClose?: SessionCloseConfig): string {
+	const pkgVersion = getCurrentVersion();
+	return `## Project Expertise (Loam)
+<!-- loam-onboard:v${pkgVersion} -->
+
+This project uses [Loam](https://github.com/hgoudat/loam) v${pkgVersion} for structured expertise management.
+
+**At the start of every session**, run:
+\`\`\`bash
+lm prime
+\`\`\`
+
+Injects project-specific conventions, patterns, decisions, failures, references, and guides into
+your context. Run \`lm prime --files src/foo.ts\` before editing a file to load only records
+relevant to that path (per-file framing, classification age, and confirmation scores included).
+
+For monolith projects where dumping every record wastes context, set
+\`prime.default_mode: manifest\` in \`.loam/loam.config.yaml\` (or pass \`--manifest\`) to emit a
+quick reference + domain index. Agents then scope-load with \`lm prime <domain>\` or
+\`lm prime --files <path>\`.
+
+**Before completing your task**, record insights worth preserving — conventions discovered,
+patterns applied, failures encountered, or decisions made:
+\`\`\`bash
+lm record <domain> --type <convention|pattern|failure|decision|reference|guide> --description "..."
+\`\`\`
+
+Evidence auto-populates from git (current commit + changed files). Link explicitly with
+\`--evidence-sprout <id>\` / \`--evidence-gh <id>\` / \`--evidence-linear <id>\` / \`--evidence-bead <id>\`,
+\`--evidence-commit <sha>\`, or \`--relates-to <mx-id>\`. Upserts of named records merge outcomes
+instead of replacing them; validation failures print a copy-paste retry hint with missing fields
+pre-filled.
+
+Run \`lm status\` for domain health, \`lm doctor\` to check record integrity (add \`--fix\` to strip
+broken file anchors), \`lm --help\` for the full command list. Write commands use file locking and
+atomic writes, so multiple agents can record concurrently. Expertise survives \`git worktree\`
+cleanup — \`.loam/\` resolves to the main repo.
+
+\`lm prune\` soft-archives stale records to \`.loam/archive/\` instead of deleting them; pass
+\`--hard\` for true deletion. Restore an archived record with \`lm restore <id>\`. Do not read
+\`.loam/archive/\` directly — those records are stale by definition. If you need historical
+context, run \`lm search --archived <query>\`.
+
+${getSessionEndReminder("embedded", sessionClose)}
+`;
+}
+
+const LEGACY_HEADER = "## Project Expertise (Loam)";
+const LEGACY_TAIL = 'loam validate && git add .loam/ && git commit -m "loam: record learnings"';
+
+function getSnippet(_provider: string | undefined, sessionClose?: SessionCloseConfig): string {
+	// All providers use the same standardized snippet.
+	return buildSnippet(sessionClose);
+}
+
+// `lm onboard` may run before `lm init`, so reading the config gracefully
+// degrades to "no preset configured" rather than failing the command.
+async function readSessionCloseConfig(cwd: string): Promise<SessionCloseConfig | undefined> {
+	try {
+		const config = await readConfig(cwd);
+		return config.prime?.session_close;
+	} catch {
+		return undefined;
+	}
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+interface OnboardTarget {
+	path: string;
+	fileName: string;
+	exists: boolean;
+}
+
+function hasLegacySnippet(content: string): boolean {
+	return content.includes(LEGACY_HEADER);
+}
+
+function replaceLegacySnippet(content: string, newSection: string): string {
+	const headerIdx = content.indexOf(LEGACY_HEADER);
+	if (headerIdx === -1) return content;
+
+	const tailIdx = content.indexOf(LEGACY_TAIL, headerIdx);
+
+	let endIdx: number;
+	if (tailIdx !== -1) {
+		// Find the closing ``` after the tail line
+		const afterTail = content.indexOf("```", tailIdx + LEGACY_TAIL.length);
+		if (afterTail !== -1) {
+			endIdx = afterTail + 3;
+			// Consume trailing newlines
+			while (endIdx < content.length && content[endIdx] === "\n") {
+				endIdx++;
+			}
+		} else {
+			endIdx = content.length;
+		}
+	} else {
+		// Tail not found (user edited the snippet): take from header to EOF
+		endIdx = content.length;
+	}
+
+	const before = content.substring(0, headerIdx);
+	const after = content.substring(endIdx);
+
+	return before + newSection + after;
+}
+
+function isSnippetCurrent(content: string): boolean {
+	if (!hasMarkerSection(content)) return false;
+	return content.includes(getVersionMarker());
+}
+
+async function findSnippetLocations(cwd: string): Promise<OnboardTarget[]> {
+	const candidates = [
+		{ fileName: "CLAUDE.md", path: join(cwd, "CLAUDE.md") },
+		{ fileName: ".claude/CLAUDE.md", path: join(cwd, ".claude", "CLAUDE.md") },
+		{ fileName: "AGENTS.md", path: join(cwd, "AGENTS.md") },
+	];
+
+	const results: OnboardTarget[] = [];
+	for (const c of candidates) {
+		const exists = await fileExists(c.path);
+		if (exists) {
+			const content = await readFile(c.path, "utf-8");
+			if (hasMarkerSection(content) || hasLegacySnippet(content)) {
+				results.push({ ...c, exists: true });
+			}
+		}
+	}
+	return results;
+}
+
+async function resolveTargetFile(cwd: string): Promise<{
+	target: OnboardTarget;
+	duplicates: OnboardTarget[];
+}> {
+	const withSnippet = await findSnippetLocations(cwd);
+
+	// If snippet found in one or more locations, use the first; others are duplicates
+	const [firstSnippet, ...restSnippets] = withSnippet;
+	if (firstSnippet !== undefined) {
+		return {
+			target: firstSnippet,
+			duplicates: restSnippets,
+		};
+	}
+
+	// No snippet found anywhere. Prefer existing CLAUDE.md, else AGENTS.md
+	if (await fileExists(join(cwd, "CLAUDE.md"))) {
+		return {
+			target: {
+				fileName: "CLAUDE.md",
+				path: join(cwd, "CLAUDE.md"),
+				exists: true,
+			},
+			duplicates: [],
+		};
+	}
+
+	// If AGENTS.md already exists (no snippet), append there to respect Codex-style projects.
+	// Only create a new file when neither exists — prefer CLAUDE.md over AGENTS.md in that case.
+	const agentsExists = await fileExists(join(cwd, "AGENTS.md"));
+	if (agentsExists) {
+		return {
+			target: {
+				fileName: "AGENTS.md",
+				path: join(cwd, "AGENTS.md"),
+				exists: true,
+			},
+			duplicates: [],
+		};
+	}
+
+	return {
+		target: {
+			fileName: "CLAUDE.md",
+			path: join(cwd, "CLAUDE.md"),
+			exists: false,
+		},
+		duplicates: [],
+	};
+}
+
+type OnboardAction =
+	| "created"
+	| "appended"
+	| "updated"
+	| "migrated"
+	| "up_to_date"
+	| "not_installed"
+	| "outdated"
+	| "legacy";
+
+export async function runOnboard(options: {
+	stdout?: boolean;
+	provider?: string;
+	check?: boolean;
+	cwd?: string;
+	jsonMode?: boolean;
+}): Promise<void> {
+	const cwd = options.cwd ?? process.cwd();
+	const sessionClose = await readSessionCloseConfig(cwd);
+	const snippet = getSnippet(options.provider, sessionClose);
+	const wrappedSnippet = wrapInMarkers(snippet);
+
+	if (options.stdout) {
+		process.stdout.write(wrappedSnippet);
+		return;
+	}
+
+	const { target, duplicates } = await resolveTargetFile(cwd);
+
+	// --check: read-only inspection
+	if (options.check) {
+		let action: OnboardAction;
+
+		if (!target.exists) {
+			action = "not_installed";
+		} else {
+			const content = await readFile(target.path, "utf-8");
+			if (hasMarkerSection(content)) {
+				action = isSnippetCurrent(content) ? "up_to_date" : "outdated";
+			} else if (hasLegacySnippet(content)) {
+				action = "legacy";
+			} else {
+				action = "not_installed";
+			}
+		}
+
+		if (options.jsonMode) {
+			outputJson({
+				success: true,
+				command: "onboard",
+				file: target.fileName,
+				action,
+			});
+		} else {
+			const messages: Record<string, string> = {
+				not_installed: `Loam snippet is not installed in ${target.fileName}.`,
+				up_to_date: `Loam snippet in ${target.fileName} is up to date.`,
+				outdated: `Loam snippet in ${target.fileName} is outdated. Run \`lm onboard\` to update.`,
+				legacy: `Loam snippet in ${target.fileName} uses legacy format (no markers). Run \`lm onboard\` to migrate.`,
+			};
+			const colors: Record<string, (s: string) => string> = {
+				not_installed: chalk.yellow,
+				up_to_date: chalk.green,
+				outdated: chalk.yellow,
+				legacy: chalk.yellow,
+			};
+			const colorFn = colors[action] ?? chalk.white;
+			const msg = messages[action] ?? action;
+			if (!isQuiet()) console.log(colorFn(msg));
+		}
+
+		if (duplicates.length > 0) {
+			const names = duplicates.map((d) => d.fileName).join(", ");
+			if (!options.jsonMode && !isQuiet()) {
+				console.log(chalk.yellow(`Warning: loam snippet also found in: ${names}`));
+			}
+		}
+		return;
+	}
+
+	// Write path
+	let action: OnboardAction;
+
+	if (!target.exists) {
+		// Create new file
+		await mkdir(dirname(target.path), { recursive: true });
+		await writeFile(target.path, `${wrappedSnippet}\n`, "utf-8");
+		action = "created";
+	} else {
+		const content = await readFile(target.path, "utf-8");
+
+		if (hasMarkerSection(content)) {
+			// Check if current
+			if (isSnippetCurrent(content)) {
+				action = "up_to_date";
+			} else {
+				// Replace marker section
+				const updated = replaceMarkerSection(content, wrappedSnippet);
+				if (updated !== null) {
+					await writeFile(target.path, updated, "utf-8");
+				}
+				action = "updated";
+			}
+		} else if (hasLegacySnippet(content)) {
+			// Migrate legacy snippet
+			const migrated = replaceLegacySnippet(content, `${wrappedSnippet}\n`);
+			await writeFile(target.path, migrated, "utf-8");
+			action = "migrated";
+		} else {
+			// Append to existing file
+			await writeFile(target.path, `${content.trimEnd()}\n\n${wrappedSnippet}\n`, "utf-8");
+			action = "appended";
+		}
+	}
+
+	if (options.jsonMode) {
+		outputJson({
+			success: true,
+			command: "onboard",
+			file: target.fileName,
+			action,
+		});
+	} else {
+		const messages: Record<string, string> = {
+			created: `Loam onboarding snippet written to ${target.fileName}.`,
+			appended: `Loam onboarding snippet appended to ${target.fileName}.`,
+			updated: `Loam onboarding snippet updated in ${target.fileName}.`,
+			migrated: `Loam onboarding snippet migrated to marker format in ${target.fileName}.`,
+			up_to_date: `Loam snippet in ${target.fileName} is already up to date. No changes made.`,
+		};
+		const color = action === "up_to_date" ? chalk.yellow : chalk.green;
+		if (!isQuiet()) console.log(color(messages[action]));
+	}
+
+	if (duplicates.length > 0) {
+		const names = duplicates.map((d) => d.fileName).join(", ");
+		if (!options.jsonMode && !isQuiet()) {
+			console.log(chalk.yellow(`Warning: loam snippet also found in: ${names}`));
+		}
+	}
+}
+
+export function registerOnboardCommand(program: Command): void {
+	program
+		.command("onboard")
+		.description("Generate or update a CLAUDE.md/AGENTS.md snippet pointing to lm prime")
+		.option("--stdout", "print snippet to stdout instead of writing to file")
+		.option("--provider <provider>", "customize snippet for a specific provider (e.g. claude)")
+		.option("--check", "check if onboarding snippet is installed and up to date")
+		.action(async (options: { stdout?: boolean; provider?: string; check?: boolean }) => {
+			const jsonMode = program.opts().json === true;
+			try {
+				await runOnboard({ ...options, jsonMode });
+			} catch (err) {
+				if (jsonMode) {
+					outputJsonError("onboard", (err as Error).message);
+				} else {
+					console.error(chalk.red(`Error: ${(err as Error).message}`));
+				}
+				process.exitCode = 1;
+			}
+		});
+}