greprag 5.84.0 → 5.85.1

package/dist/commands/agents.js

@@ -1,7 +1,16 @@
 "use strict";
-/** `greprag instructions` — canonical GrepRAG Instructions adoption/materialization.
+/** `greprag instructions` — render the Codex/OpenCode AGENTS.md files from
+ *  `~/.claude/CLAUDE.md`, and keep GrepRAG's read-only copy of it.
  *
- *  `greprag agents` remains as a compatibility alias. */
+ *  `~/.claude/CLAUDE.md` in the dotclaude git repo is the only source. Each
+ *  AGENTS.md is that file plus an optional per-harness addition kept beside it
+ *  in git (`~/.claude/instructions/codex.md`, `~/.claude/instructions/opencode.md`),
+ *  joined byte for byte. SessionStart runs the render; GrepRAG mirrors the
+ *  COMMITTED CLAUDE.md for search and `greprag load instructions`, and never
+ *  writes it. Repo-level CLAUDE.md/AGENTS.md are ordinary files in their repos.
+ *
+ *  `greprag agents` remains as a compatibility alias.
+ *  adr: adr/skill-ownership-git.md */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -36,857 +45,130 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectOriginalSnapshots = collectOriginalSnapshots;
-exports.bootstrapAgentDoctrine = bootstrapAgentDoctrine;
+exports.instructionSource = instructionSource;
+exports.instructionTargets = instructionTargets;
+exports.renderAgentsFile = renderAgentsFile;
+exports.renderGlobalInstructions = renderGlobalInstructions;
+exports.committedInstructionSource = committedInstructionSource;
+exports.mirrorCommittedInstructions = mirrorCommittedInstructions;
 exports.runInstructions = runInstructions;
 exports.runAgents = runAgents;
-const crypto = __importStar(require("node:crypto"));
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
-const project_anchor_1 = require("../project-anchor");
 const proc_1 = require("../proc");
-const agent_doctrine_file_1 = require("./agent-doctrine-file");
-function help(commandName) {
-    const aliasNote = commandName === 'agents'
-        ? '\n\nNOTE\n  `greprag agents` is a deprecated alias. Use `greprag instructions`.'
-        : '';
-    return `greprag ${commandName} — canonical GrepRAG Instructions for CLAUDE.md / AGENTS.md
-
-USAGE
-  greprag ${commandName} pull <file> [--scope global|repo] [--harness <name>] [--push]
-  greprag ${commandName} push [--scope global|repo|all] [--check] [--force]
-  greprag ${commandName} adopt <file> [--scope global|repo] [--harness <name>] [--no-sync]
-  greprag ${commandName} revise <file> [--scope global|repo] [--harness <name>] [--no-sync]
-  greprag ${commandName} overlay set <harness> <file> [--scope global|repo] [--no-sync]
-  greprag ${commandName} overlay derive <harness> <shared-file> <rendered-file> [--scope global|repo] [--no-sync]
-  greprag ${commandName} overlay clear <harness> [--scope global|repo] [--no-sync]
-  greprag ${commandName} snapshot create --name <name> [--scope global|repo|all] [--harness <name>] [--from-ref <git-ref>] [--force]
-  greprag ${commandName} snapshot list [--scope global|repo|all]
-  greprag ${commandName} snapshot show <name> [--scope global|repo|all]
-  greprag ${commandName} restore --snapshot <name> [--scope global|repo|all] [--harness <name>] [--check] [--force]
-  greprag ${commandName} sync [--scope global|repo|all] [--check] [--force]
-  greprag ${commandName} status [--scope global|repo|all]
-
-MODEL
-  Adopt and revise copy source bytes exactly; no model rewrites instructions.
-  The first adoption stores Original Snapshots for every managed follower.
-  Harness translations are raw additive suffixes. Pull writes disk to canon.
-  Push writes canon to disk only when the external sync baseline is clean.
-  Snapshots are named exact-byte rollback points and do not change canon.
-  Status/check never writes.${aliasNote}`;
-}
-function config(apiKeyOverride) {
-    return {
-        apiUrl: process.env.GREPRAG_API_URL || 'https://api.greprag.com',
-        apiKey: apiKeyOverride || process.env.GREPRAG_API_KEY || '',
-    };
-}
-function flag(args, name) {
-    const index = args.indexOf(name);
-    return index >= 0 ? args[index + 1] : undefined;
-}
-function repoRoot(cwd = process.cwd()) {
-    try {
-        return String((0, proc_1.safeExecSync)('git rev-parse --show-toplevel', {
-            cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-        })).trim();
-    }
-    catch {
-        return path.resolve(cwd);
-    }
-}
-function fileGitRoot(filePath) {
-    try {
-        return String((0, proc_1.safeExecFileSync)('git', ['-C', path.dirname(filePath), 'rev-parse', '--show-toplevel'], {
-            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-        })).trim();
-    }
-    catch {
-        return null;
-    }
+function instructionSource(home = os.homedir()) {
+    return path.join(home, '.claude', 'CLAUDE.md');
 }
-function gitFileAt(root, ref, relativePath) {
-    try {
-        return String((0, proc_1.safeExecFileSync)('git', ['-C', root, 'show', `${ref}:${relativePath}`], {
-            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-            maxBuffer: 1024 * 1024,
-        }));
-    }
-    catch {
-        return null;
-    }
+function instructionTargets(home = os.homedir()) {
+    const additions = path.join(home, '.claude', 'instructions');
+    return [
+        { harness: 'codex', path: path.join(home, '.codex', 'AGENTS.md'), addition: path.join(additions, 'codex.md') },
+        { harness: 'opencode', path: path.join(home, '.config', 'opencode', 'AGENTS.md'), addition: path.join(additions, 'opencode.md') },
+    ];
 }
-function firstInstructionTouch(root, relativePath) {
+function readOrNull(file) {
     try {
-        const out = String((0, proc_1.safeExecFileSync)('git', [
-            '-C', root,
-            'log',
-            '--reverse',
-            '--format=%H',
-            '--all',
-            '-G', 'Agent Doctrine|Doctrine Mirror|agent doctrine|greprag agents|greprag instructions|GrepRAG Instructions',
-            '--',
-            relativePath,
-        ], {
-            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
-            maxBuffer: 1024 * 1024,
-        })).trim();
-        return out.split(/\r?\n/).find(Boolean) || null;
+        return fs.readFileSync(file, 'utf8');
     }
     catch {
         return null;
     }
 }
-function looksManagedOrRenamed(content) {
-    return /Agent Doctrine|Doctrine Mirror|agent doctrine|greprag agents|greprag instructions|GrepRAG Instructions/i.test(content);
-}
-function relativeDirectory(root, requested) {
-    const absolute = requested
-        ? path.resolve(root, requested)
-        : path.resolve(process.cwd());
-    const relative = path.relative(root, absolute).replace(/\\/g, '/') || '.';
-    if (relative === '..' || relative.startsWith('../')) {
-        throw new Error('doctrine directory must be inside the current repo');
-    }
-    return relative;
-}
-function globalTargets() {
-    const home = os.homedir();
-    return [
-        {
-            harness: 'claude-code',
-            actualPath: path.join(home, '.claude', 'CLAUDE.md'),
-            manifestPath: '~/.claude/CLAUDE.md',
-        },
-        {
-            harness: 'codex',
-            actualPath: path.join(home, '.codex', 'AGENTS.md'),
-            manifestPath: '~/.codex/AGENTS.md',
-        },
-        {
-            harness: 'opencode',
-            actualPath: path.join(home, '.config', 'opencode', 'AGENTS.md'),
-            manifestPath: '~/.config/opencode/AGENTS.md',
-        },
-    ];
-}
-function repoTargets(root, directory) {
-    const base = directory === '.' ? root : path.join(root, ...directory.split('/'));
-    return [
-        {
-            harness: 'claude-code',
-            actualPath: path.join(base, 'CLAUDE.md'),
-            manifestPath: path.join(base, 'CLAUDE.md'),
-        },
-        {
-            harness: 'codex',
-            actualPath: path.join(base, 'AGENTS.md'),
-            manifestPath: path.join(base, 'AGENTS.md'),
-            note: 'shared AGENTS.md follower consumed by Codex and OpenCode',
-            combinedAgents: true,
-        },
-    ];
-}
-function parityUnitName(scope, projectId, directory) {
-    if (scope === 'global')
-        return 'agent-doctrine-global';
-    if (!projectId)
-        throw new Error('projectId required for repo doctrine');
-    const suffix = directory === '.'
-        ? 'root'
-        : crypto.createHash('sha256').update(directory).digest('hex').slice(0, 8);
-    return `agent-doctrine-${projectId.slice(0, 8)}-${suffix}`;
-}
-function snapshotContentHash(value) {
-    return crypto.createHash('sha256').update(value).digest('hex');
-}
-function normalizeSnapshotName(value) {
-    const name = (value || '').trim();
-    if (!/^[a-z0-9][a-z0-9._-]{0,79}$/i.test(name)) {
-        throw new Error('snapshot name must be 1-80 chars: letters, numbers, dot, underscore, or dash');
-    }
-    return name;
-}
-function snapshotNameOf(snapshot) {
-    return snapshot.snapshotName || 'original';
-}
-function originalSnapshotForTarget(target, scope, projectId, directory, capturedAt) {
-    const base = {
-        snapshotName: 'original',
-        harness: target.harness,
-        path: target.manifestPath,
-        scope,
-        projectId,
-        directory,
-        capturedAt,
-    };
-    if (!fs.existsSync(target.actualPath)) {
-        return {
-            ...base,
-            status: 'missing',
-            content: '',
-            contentHash: snapshotContentHash(''),
-            source: 'missing',
-            sourceRef: null,
-            reason: 'follower file did not exist at adoption time',
-        };
-    }
-    const diskContent = fs.readFileSync(target.actualPath, 'utf8');
-    if (looksManagedOrRenamed(diskContent)) {
-        const gitRoot = fileGitRoot(target.actualPath);
-        if (gitRoot) {
-            const rel = path.relative(gitRoot, target.actualPath).replace(/\\/g, '/');
-            const firstTouch = firstInstructionTouch(gitRoot, rel);
-            if (firstTouch) {
-                const historical = gitFileAt(gitRoot, `${firstTouch}^`, rel);
-                if (historical !== null) {
-                    return {
-                        ...base,
-                        status: 'present',
-                        content: historical,
-                        contentHash: snapshotContentHash(historical),
-                        source: 'git-history',
-                        sourceRef: `${firstTouch}^`,
-                        reason: `pre-GrepRAG-Instructions snapshot from parent of ${firstTouch.slice(0, 12)}`,
-                    };
-                }
-            }
-        }
-    }
-    return {
-        ...base,
-        status: 'present',
-        content: diskContent,
-        contentHash: snapshotContentHash(diskContent),
-        source: 'disk',
-        sourceRef: null,
-        reason: looksManagedOrRenamed(diskContent)
-            ? 'historical pre-instructions file was not recoverable; captured disk bytes'
-            : 'captured disk bytes before first GrepRAG Instructions adoption',
-    };
-}
-function diskSnapshotForTarget(target, scope, projectId, directory, snapshotName, capturedAt) {
-    const base = {
-        snapshotName,
-        harness: target.harness,
-        path: target.manifestPath,
-        scope,
-        projectId,
-        directory,
-        capturedAt,
-    };
-    if (!fs.existsSync(target.actualPath)) {
-        return {
-            ...base,
-            status: 'missing',
-            content: '',
-            contentHash: snapshotContentHash(''),
-            source: 'missing',
-            sourceRef: null,
-            reason: `snapshot ${snapshotName}: follower file did not exist`,
-        };
-    }
-    const content = fs.readFileSync(target.actualPath, 'utf8');
-    return {
-        ...base,
-        status: 'present',
-        content,
-        contentHash: snapshotContentHash(content),
-        source: 'disk',
-        sourceRef: null,
-        reason: `snapshot ${snapshotName}: captured disk bytes`,
-    };
-}
-function gitRefSnapshotForTarget(target, scope, projectId, directory, snapshotName, capturedAt, ref) {
-    const base = {
-        snapshotName,
-        harness: target.harness,
-        path: target.manifestPath,
-        scope,
-        projectId,
-        directory,
-        capturedAt,
-    };
-    const gitRoot = fileGitRoot(target.actualPath);
-    if (gitRoot) {
-        const rel = path.relative(gitRoot, target.actualPath).replace(/\\/g, '/');
-        const content = gitFileAt(gitRoot, ref, rel);
-        if (content !== null) {
-            return {
-                ...base,
-                status: 'present',
-                content,
-                contentHash: snapshotContentHash(content),
-                source: 'git-history',
-                sourceRef: ref,
-                reason: `snapshot ${snapshotName}: captured ${rel} from ${ref}`,
-            };
-        }
-    }
-    return {
-        ...base,
-        status: 'missing',
-        content: '',
-        contentHash: snapshotContentHash(''),
-        source: 'missing',
-        sourceRef: ref,
-        reason: `snapshot ${snapshotName}: no file at ${ref}`,
-    };
-}
-function collectOriginalSnapshots(targets, scope, projectId, directory) {
-    const capturedAt = new Date().toISOString();
-    return targets.map((target) => originalSnapshotForTarget(target, scope, projectId, directory, capturedAt));
-}
-function uniqueNonempty(values) {
-    const seen = new Set();
-    const out = [];
-    for (const value of values) {
-        if (!value)
-            continue;
-        if (seen.has(value))
-            continue;
-        seen.add(value);
-        out.push(value);
-    }
-    return out;
-}
-function renderForTarget(doc, target) {
-    if (target.combinedAgents) {
-        return doc.shared + uniqueNonempty([doc.overlays.codex, doc.overlays.opencode]).join('');
-    }
-    return doc.shared + (doc.overlays[target.harness] || '');
-}
-async function apiJson(pathname, init, apiKeyOverride) {
-    const cfg = config(apiKeyOverride);
-    if (!cfg.apiKey)
-        throw new Error('GREPRAG_API_KEY not set — run `greprag init` first.');
-    const response = await fetch(`${cfg.apiUrl}${pathname}`, {
-        ...init,
-        headers: {
-            'Authorization': `Bearer ${cfg.apiKey}`,
-            ...(init?.body ? { 'Content-Type': 'application/json' } : {}),
-            ...(init?.headers || {}),
-        },
+/** AGENTS.md = CLAUDE.md + the harness addition, raw concatenation. PURE. */
+function renderAgentsFile(source, addition) {
+    return source + (addition || '');
+}
+/** Write each AGENTS.md that differs from its render; `check` only reports. */
+function renderGlobalInstructions(opts = {}) {
+    const home = opts.home || os.homedir();
+    const source = readOrNull(instructionSource(home));
+    return instructionTargets(home).map(target => {
+        if (source === null)
+            return { path: target.path, status: 'no-source' };
+        const next = renderAgentsFile(source, readOrNull(target.addition));
+        if (readOrNull(target.path) === next)
+            return { path: target.path, status: 'current' };
+        if (opts.check)
+            return { path: target.path, status: 'stale' };
+        fs.mkdirSync(path.dirname(target.path), { recursive: true });
+        fs.writeFileSync(target.path, next, 'utf8');
+        return { path: target.path, status: 'written' };
     });
-    const body = await response.json().catch(() => ({}));
-    if (!response.ok)
-        throw new Error(body.error || `HTTP ${response.status}`);
-    return body;
-}
-function context(scope, args) {
-    const root = repoRoot();
-    if (scope === 'global') {
-        return { projectId: null, directory: '.', root, targets: globalTargets() };
-    }
-    const anchor = (0, project_anchor_1.readAnchor)(root);
-    const directory = relativeDirectory(root, flag(args, '--directory'));
-    return {
-        projectId: anchor.projectId,
-        directory,
-        root,
-        targets: repoTargets(root, directory),
-    };
-}
-async function fetchDocument(scope, projectId, directory, apiKey) {
-    const params = new URLSearchParams({ scope, directory, harness: 'all' });
-    if (projectId)
-        params.set('projectId', projectId);
-    try {
-        const body = await apiJson(`/v1/agents?${params.toString()}`, undefined, apiKey);
-        return body.documents[0] || null;
-    }
-    catch (error) {
-        if (error instanceof Error && /not found/.test(error.message))
-            return null;
-        throw error;
-    }
 }
-async function fetchFollowerBaselines(unitName, apiKey) {
+/** The committed bytes of `~/.claude/CLAUDE.md` (HEAD of the dotclaude repo). */
+function committedInstructionSource(home = os.homedir()) {
+    const dir = path.join(home, '.claude');
     try {
-        const body = await apiJson('/v1/parity/list', undefined, apiKey);
-        const unit = body.units.find((candidate) => candidate.name === unitName);
-        const baselines = new Map();
-        for (const follower of unit?.followers || []) {
-            if (!follower.path)
-                continue;
-            baselines.set(`${follower.harness}\0${follower.path}`, {
-                syncedRevision: follower.syncedRevision,
-                syncedHash: follower.syncedHash,
-                syncedAt: follower.syncedAt,
-                dirtyAt: follower.dirtyAt,
-            });
-        }
-        return baselines;
+        return String((0, proc_1.safeExecFileSync)('git', ['-C', dir, 'show', 'HEAD:CLAUDE.md'], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 4 * 1024 * 1024,
+        }));
     }
     catch {
-        return new Map();
-    }
-}
-function inferHarness(file, explicit) {
-    if (explicit === 'claude-code' || explicit === 'codex' || explicit === 'opencode')
-        return explicit;
-    return file && path.basename(file).toUpperCase() === 'CLAUDE.MD' ? 'claude-code' : 'codex';
-}
-function parseOptionalHarness(explicit) {
-    if (!explicit)
-        return undefined;
-    if (explicit === 'claude-code' || explicit === 'codex' || explicit === 'opencode')
-        return explicit;
-    throw new Error('--harness must be claude-code, codex, or opencode');
-}
-function inferScope(file, explicit) {
-    if (explicit === 'global' || explicit === 'repo')
-        return explicit;
-    if (file) {
-        const absolute = path.resolve(file).toLowerCase();
-        if (globalTargets().some((target) => target.actualPath.toLowerCase() === absolute))
-            return 'global';
-    }
-    return 'repo';
-}
-async function reportSync(unitName, target, revision, renderHash, apiKey) {
-    await apiJson('/v1/agents/sync', {
-        method: 'POST',
-        body: JSON.stringify({
-            unitName,
-            harness: target.harness,
-            path: target.manifestPath,
-            revision,
-            renderHash,
-        }),
-    }, apiKey);
-}
-function targetMatchesHarness(target, harness) {
-    if (!harness || target.harness === harness)
-        return true;
-    return harness === 'opencode' && target.combinedAgents === true;
-}
-async function syncOne(params) {
-    const ctx = context(params.scope, params.args);
-    const doc = await fetchDocument(params.scope, ctx.projectId, ctx.directory, params.apiKey);
-    if (!doc) {
-        if (!params.quiet)
-            console.log(`${params.scope}: no canonical doctrine`);
-        return { canonical: false, current: 0, changed: 0, enrolled: 0, blocked: 0, drift: 0 };
-    }
-    const unitName = parityUnitName(params.scope, ctx.projectId, ctx.directory);
-    const baselines = await fetchFollowerBaselines(unitName, params.apiKey);
-    const stats = { canonical: true, current: 0, changed: 0, enrolled: 0, blocked: 0, drift: 0 };
-    for (const target of ctx.targets.filter(t => targetMatchesHarness(t, params.harness))) {
-        const source = fs.existsSync(target.actualPath)
-            ? fs.readFileSync(target.actualPath, 'utf8')
-            : '';
-        const rendered = renderForTarget(doc, target);
-        const outcome = (0, agent_doctrine_file_1.planDoctrineFollowerWrite)(source, {
-            scopeKey: doc.scopeKey,
-            harness: target.harness,
-            revision: doc.revision,
-            body: rendered,
-        }, baselines.get(`${target.harness}\0${target.manifestPath}`), { force: params.force });
-        const current = outcome.action === 'current';
-        if (current)
-            stats.current++;
-        else
-            stats.drift++;
-        const detail = 'reason' in outcome ? ` — ${outcome.reason}` : '';
-        if (!params.quiet) {
-            console.log(`  ${current ? 'fresh' : outcome.action.padEnd(9)} ${target.actualPath}${detail}`);
-        }
-        const seedOnlyBlocked = params.seedOnly && !current && outcome.action !== 'seed';
-        if (outcome.action === 'conflict' || outcome.action === 'local-change'
-            || outcome.action === 'unmanaged' || seedOnlyBlocked) {
-            stats.blocked++;
-            continue;
-        }
-        if (params.check)
-            continue;
-        if (current) {
-            if (outcome.shouldReportSync) {
-                await reportSync(unitName, target, doc.revision, outcome.renderHash, params.apiKey);
-                stats.enrolled++;
-            }
-            continue;
-        }
-        fs.mkdirSync(path.dirname(target.actualPath), { recursive: true });
-        fs.writeFileSync(target.actualPath, outcome.content, 'utf8');
-        await reportSync(unitName, target, doc.revision, outcome.renderHash, params.apiKey);
-        stats.changed++;
-    }
-    return stats;
-}
-async function exactSourceCommand(args, mode) {
-    const from = args[0] && !args[0].startsWith('-') ? args[0] : undefined;
-    if (!from)
-        throw new Error(`${mode} requires a source file`);
-    const sourcePath = path.resolve(from);
-    if (!fs.existsSync(sourcePath))
-        throw new Error(`source file not found: ${sourcePath}`);
-    const scope = inferScope(sourcePath, flag(args, '--scope'));
-    const harness = inferHarness(sourcePath, flag(args, '--harness'));
-    const ctx = context(scope, args);
-    const current = mode === 'adopt' ? null : await fetchDocument(scope, ctx.projectId, ctx.directory);
-    const endpointMode = mode === 'pull'
-        ? current ? 'revise' : 'adopt'
-        : mode;
-    const fileContent = fs.readFileSync(sourcePath, 'utf8');
-    const content = (0, agent_doctrine_file_1.stripLegacyGrepRagConventionBlocks)((0, agent_doctrine_file_1.extractDoctrineFollowerBody)(fileContent) ?? fileContent);
-    const body = await apiJson(`/v1/agents/${endpointMode}`, {
-        method: 'POST',
-        body: JSON.stringify({
-            scope,
-            projectId: ctx.projectId,
-            directory: ctx.directory,
-            sourceHarness: harness,
-            sourcePath,
-            content,
-            expectedRevision: endpointMode === 'revise' ? current?.revision ?? null : null,
-            originalSnapshots: endpointMode === 'adopt'
-                ? collectOriginalSnapshots(ctx.targets, scope, ctx.projectId, ctx.directory)
-                : undefined,
-            followers: ctx.targets.map((target) => ({
-                harness: target.harness,
-                path: target.manifestPath,
-                note: target.note,
-            })),
-        }),
-    });
-    const verb = mode === 'pull' ? 'Pulled' : mode === 'adopt' ? 'Adopted' : 'Revised';
-    console.log(`${verb} ${body.document.scopeKey} revision ${body.document.revision}.`);
-    if (endpointMode === 'adopt' && body.document.originalSnapshots?.length) {
-        const historical = body.document.originalSnapshots.filter((s) => s.source === 'git-history').length;
-        console.log(`Original Snapshots stored: ${body.document.originalSnapshots.length} (${historical} from git history).`);
-    }
-    const shouldPush = mode === 'pull'
-        ? args.includes('--push')
-        : !args.includes('--no-sync');
-    if (shouldPush) {
-        await syncOne({
-            scope,
-            args,
-            check: false,
-            force: args.includes('--force'),
-        });
+        return null;
     }
 }
-async function overlayCommand(args) {
-    const action = args[0];
-    const harnessRaw = args[1];
-    if (action !== 'set' && action !== 'clear' && action !== 'derive') {
-        throw new Error('overlay requires set, derive, or clear');
-    }
-    const harness = inferHarness(undefined, harnessRaw);
-    if (harnessRaw !== harness)
-        throw new Error('overlay harness must be claude-code, codex, or opencode');
-    const file = action === 'set' ? args[2] : undefined;
-    if (action === 'set' && !file)
-        throw new Error('overlay set requires a source file');
-    const sharedFile = action === 'derive' ? args[2] : undefined;
-    const renderedFile = action === 'derive' ? args[3] : undefined;
-    if (action === 'derive' && (!sharedFile || !renderedFile)) {
-        throw new Error('overlay derive requires <shared-file> <rendered-file>');
-    }
-    const sourcePath = file ? path.resolve(file) : null;
-    if (sourcePath && !fs.existsSync(sourcePath))
-        throw new Error(`source file not found: ${sourcePath}`);
-    const sharedPath = sharedFile ? path.resolve(sharedFile) : null;
-    const renderedPath = renderedFile ? path.resolve(renderedFile) : null;
-    if (sharedPath && !fs.existsSync(sharedPath))
-        throw new Error(`shared file not found: ${sharedPath}`);
-    if (renderedPath && !fs.existsSync(renderedPath))
-        throw new Error(`rendered file not found: ${renderedPath}`);
-    const scope = inferScope(undefined, flag(args, '--scope'));
-    const ctx = context(scope, args);
-    const current = await fetchDocument(scope, ctx.projectId, ctx.directory);
-    if (!current)
-        throw new Error('canonical doctrine does not exist; adopt it first');
-    let content = '';
-    if (sourcePath) {
-        content = fs.readFileSync(sourcePath, 'utf8');
-    }
-    else if (sharedPath && renderedPath) {
-        const shared = fs.readFileSync(sharedPath, 'utf8');
-        const rendered = fs.readFileSync(renderedPath, 'utf8');
-        if (!rendered.startsWith(shared)) {
-            throw new Error('rendered file does not start with shared file bytes; cannot derive exact suffix');
-        }
-        content = rendered.slice(shared.length);
-    }
-    const body = await apiJson('/v1/agents/overlay', {
+/** Keep GrepRAG's read-only copy equal to the committed CLAUDE.md. One GET;
+ *  a write only when the commit moved. Returns what happened. */
+async function mirrorCommittedInstructions(params) {
+    const home = params.home || os.homedir();
+    const content = committedInstructionSource(home);
+    if (!content || !content.trim())
+        return 'no-source';
+    const headers = { 'Authorization': `Bearer ${params.apiKey}`, 'Content-Type': 'application/json' };
+    const query = new URLSearchParams({ scope: 'global', directory: '.', harness: 'all' });
+    const res = await fetch(`${params.apiUrl}/v1/agents?${query.toString()}`, { headers, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok && res.status !== 404)
+        throw new Error(`instructions mirror read failed: HTTP ${res.status}`);
+    const current = res.ok
+        ? (await res.json()).documents?.[0]
+        : undefined;
+    if (current && current.shared === content)
+        return 'current';
+    const mode = current ? 'revise' : 'adopt';
+    const write = await fetch(`${params.apiUrl}/v1/agents/${mode}`, {
         method: 'POST',
+        headers,
         body: JSON.stringify({
-            scope,
-            projectId: ctx.projectId,
-            directory: ctx.directory,
-            sourceHarness: harness,
-            sourcePath: renderedPath || sourcePath,
+            scope: 'global',
+            directory: '.',
+            sourceHarness: 'claude-code',
+            sourcePath: instructionSource(home),
             content,
-            overlayHarness: harness,
-            expectedRevision: current.revision,
-            followers: ctx.targets.map((target) => ({
-                harness: target.harness,
-                path: target.manifestPath,
-                note: target.note,
-            })),
-        }),
-    });
-    const verb = action === 'set' ? 'Set' : action === 'derive' ? 'Derived' : 'Cleared';
-    console.log(`${verb} ${harness} overlay at revision ${body.document.revision}.`);
-    if (!args.includes('--no-sync')) {
-        await syncOne({ scope, args, check: false, force: args.includes('--force') });
-    }
-}
-function originalSnapshotForRenderTarget(doc, target, scope, projectId, directory, snapshotName) {
-    const snapshots = doc.originalSnapshots || [];
-    return snapshots.find((snapshot) => snapshot.harness === target.harness
-        && snapshotNameOf(snapshot) === snapshotName
-        && snapshot.path === target.manifestPath
-        && snapshot.scope === scope
-        && (scope === 'global' || snapshot.projectId === projectId)
-        && snapshot.directory === directory) || null;
-}
-async function restoreOne(params) {
-    const ctx = context(params.scope, params.args);
-    const doc = await fetchDocument(params.scope, ctx.projectId, ctx.directory);
-    if (!doc) {
-        console.log(`${params.scope}: no canonical doctrine`);
-        return { canonical: false, current: 0, changed: 0, blocked: 0 };
-    }
-    const stats = { canonical: true, current: 0, changed: 0, blocked: 0 };
-    for (const target of ctx.targets.filter(t => targetMatchesHarness(t, params.harness))) {
-        const snapshot = originalSnapshotForRenderTarget(doc, target, params.scope, ctx.projectId, ctx.directory, params.snapshotName);
-        if (!snapshot) {
-            console.log(`  blocked  ${target.actualPath} — no snapshot '${params.snapshotName}' stored for this follower`);
-            stats.blocked++;
-            continue;
-        }
-        const exists = fs.existsSync(target.actualPath);
-        const source = exists ? fs.readFileSync(target.actualPath, 'utf8') : '';
-        const alreadyOriginal = snapshot.status === 'missing'
-            ? !exists
-            : exists && source === snapshot.content;
-        if (alreadyOriginal) {
-            console.log(`  current  ${target.actualPath}`);
-            stats.current++;
-            continue;
-        }
-        const currentRender = renderForTarget(doc, target);
-        const cleanManagedFollower = !exists || source === currentRender;
-        if (!cleanManagedFollower && !params.force) {
-            console.log(`  blocked  ${target.actualPath} — local edits differ from the current GrepRAG render; rerun with --force only after saving them`);
-            stats.blocked++;
-            continue;
-        }
-        const action = snapshot.status === 'missing' ? 'remove' : 'restore';
-        const sourceNote = snapshot.source === 'git-history' && snapshot.sourceRef
-            ? `${snapshot.source}:${snapshot.sourceRef}`
-            : snapshot.source;
-        console.log(`  ${params.check ? `would-${action}` : action} ${target.actualPath} — snapshot '${params.snapshotName}' from ${sourceNote}`);
-        stats.changed++;
-        if (params.check)
-            continue;
-        if (snapshot.status === 'missing') {
-            if (exists)
-                fs.rmSync(target.actualPath);
-        }
-        else {
-            fs.mkdirSync(path.dirname(target.actualPath), { recursive: true });
-            fs.writeFileSync(target.actualPath, snapshot.content, 'utf8');
-        }
-    }
-    return stats;
-}
-async function restoreCommand(args) {
-    const snapshotName = normalizeSnapshotName(flag(args, '--snapshot'));
-    const requested = flag(args, '--scope') || 'all';
-    if (!['global', 'repo', 'all'].includes(requested)) {
-        throw new Error('--scope must be global|repo|all');
-    }
-    const harness = parseOptionalHarness(flag(args, '--harness'));
-    const scopes = requested === 'all' ? ['global', 'repo'] : [requested];
-    const check = args.includes('--check');
-    let changed = 0;
-    let blocked = 0;
-    for (const scope of scopes) {
-        console.log(`${scope}:`);
-        const stats = await restoreOne({
-            scope,
-            args,
-            check,
-            force: args.includes('--force'),
-            snapshotName,
-            harness,
-        });
-        changed += stats.changed;
-        blocked += stats.blocked;
-    }
-    if (changed > 0 && !check) {
-        console.log('Restored snapshot bytes. Canon is unchanged; run `greprag instructions pull <file>` to promote restored bytes back into canon.');
-    }
-    if (check && changed > 0) {
-        console.error(`${changed} follower(s) would be restored.`);
-        process.exitCode = 1;
-    }
-    if (blocked > 0)
-        process.exitCode = 1;
-}
-function snapshotSummary(doc) {
-    const out = new Map();
-    for (const snapshot of doc.originalSnapshots || []) {
-        const name = snapshotNameOf(snapshot);
-        const rows = out.get(name) || [];
-        rows.push(snapshot);
-        out.set(name, rows);
-    }
-    return out;
-}
-async function snapshotCreateOne(params) {
-    const ctx = context(params.scope, params.args);
-    const doc = await fetchDocument(params.scope, ctx.projectId, ctx.directory);
-    if (!doc) {
-        console.log(`${params.scope}: no canonical doctrine`);
-        return 0;
-    }
-    const targets = ctx.targets.filter(t => targetMatchesHarness(t, params.harness));
-    const capturedAt = new Date().toISOString();
-    const snapshots = targets.map((target) => params.fromRef
-        ? gitRefSnapshotForTarget(target, params.scope, ctx.projectId, ctx.directory, params.snapshotName, capturedAt, params.fromRef)
-        : diskSnapshotForTarget(target, params.scope, ctx.projectId, ctx.directory, params.snapshotName, capturedAt));
-    const body = await apiJson('/v1/agents/snapshot', {
-        method: 'POST',
-        body: JSON.stringify({
-            scope: params.scope,
-            projectId: ctx.projectId,
-            directory: ctx.directory,
-            snapshotName: params.snapshotName,
-            snapshots,
-            replace: params.force,
-            expectedRevision: doc.revision,
+            expectedRevision: current ? current.revision : null,
+            originalSnapshots: [],
+            followers: [{ harness: 'claude-code', path: '~/.claude/CLAUDE.md', note: 'git source; GrepRAG holds a read-only copy' }],
         }),
+        signal: AbortSignal.timeout(10_000),
     });
-    const present = snapshots.filter((snapshot) => snapshot.status === 'present').length;
-    console.log(`${params.scope}: stored snapshot '${params.snapshotName}' for ${snapshots.length} follower(s) (${present} present) at revision ${body.document.revision}.`);
-    return snapshots.length;
-}
-async function snapshotListOne(scope, args) {
-    const ctx = context(scope, args);
-    const doc = await fetchDocument(scope, ctx.projectId, ctx.directory);
-    if (!doc) {
-        console.log(`${scope}: no canonical doctrine`);
-        return;
-    }
-    console.log(`${scope}: ${doc.scopeKey} revision ${doc.revision}`);
-    const groups = snapshotSummary(doc);
-    if (groups.size === 0) {
-        console.log('  no snapshots');
-        return;
-    }
-    for (const [name, rows] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-        const present = rows.filter((row) => row.status === 'present').length;
-        const capturedAt = rows.map((row) => row.capturedAt).sort()[0] || '(unknown)';
-        console.log(`  ${name}: ${rows.length} follower(s), ${present} present, first captured ${capturedAt}`);
-    }
-}
-async function snapshotShowOne(scope, args, snapshotName) {
-    const ctx = context(scope, args);
-    const doc = await fetchDocument(scope, ctx.projectId, ctx.directory);
-    if (!doc) {
-        console.log(`${scope}: no canonical doctrine`);
-        return;
-    }
-    const rows = (doc.originalSnapshots || [])
-        .filter((snapshot) => snapshotNameOf(snapshot) === snapshotName);
-    console.log(`${scope}: ${doc.scopeKey} revision ${doc.revision}`);
-    if (rows.length === 0) {
-        console.log(`  snapshot '${snapshotName}' not found`);
-        return;
-    }
-    for (const row of rows) {
-        const ref = row.sourceRef ? ` ${row.sourceRef}` : '';
-        console.log(`  ${row.harness} ${row.path}`);
-        console.log(`    ${row.status} ${row.source}${ref} ${row.contentHash}`);
-        if (row.reason)
-            console.log(`    ${row.reason}`);
-    }
-}
-async function snapshotCommand(args) {
-    const action = args[0];
-    const requested = flag(args, '--scope') || 'all';
-    if (!['global', 'repo', 'all'].includes(requested)) {
-        throw new Error('--scope must be global|repo|all');
-    }
-    const scopes = requested === 'all' ? ['global', 'repo'] : [requested];
-    if (action === 'create') {
-        const snapshotName = normalizeSnapshotName(flag(args, '--name'));
-        const harness = parseOptionalHarness(flag(args, '--harness'));
-        const fromRef = flag(args, '--from-ref');
-        let count = 0;
-        for (const scope of scopes) {
-            count += await snapshotCreateOne({
-                scope,
-                args,
-                snapshotName,
-                fromRef,
-                force: args.includes('--force'),
-                harness,
-            });
-        }
-        if (count > 0)
-            console.log('Snapshot storage only changed rollback metadata; canon render bytes are unchanged.');
-        return;
-    }
-    if (action === 'list') {
-        for (const scope of scopes)
-            await snapshotListOne(scope, args);
-        return;
-    }
-    if (action === 'show') {
-        const snapshotName = normalizeSnapshotName(args[1] && !args[1].startsWith('-') ? args[1] : flag(args, '--name'));
-        for (const scope of scopes)
-            await snapshotShowOne(scope, args, snapshotName);
-        return;
-    }
-    throw new Error('snapshot requires create, list, or show');
+    if (!write.ok)
+        throw new Error(`instructions mirror write failed: HTTP ${write.status}`);
+    return 'mirrored';
 }
-async function syncCommand(args, checkOverride = false) {
-    const requested = flag(args, '--scope') || 'all';
-    if (!['global', 'repo', 'all'].includes(requested)) {
-        throw new Error('--scope must be global|repo|all');
-    }
-    const scopes = requested === 'all' ? ['global', 'repo'] : [requested];
-    const check = checkOverride || args.includes('--check');
-    let drift = 0;
-    for (const scope of scopes) {
-        console.log(`${scope}:`);
-        const stats = await syncOne({ scope, args, check, force: args.includes('--force') });
-        drift += stats.drift;
-    }
-    if (check && drift > 0) {
-        console.error(`${drift} follower(s) need sync or reconciliation.`);
-        process.exitCode = 1;
-    }
-    else if (check) {
-        console.log('All materialized followers are current.');
-    }
+function help(commandName) {
+    const aliasNote = commandName === 'agents'
+        ? '\n\nNOTE\n  `greprag agents` is a deprecated alias. Use `greprag instructions`.'
+        : '';
+    return `greprag ${commandName} — AGENTS.md files rendered from ~/.claude/CLAUDE.md
+
+USAGE
+  greprag ${commandName} render [--check]   Rewrite ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md,
+                                     then refresh GrepRAG's read-only copy of the committed CLAUDE.md
+  greprag ${commandName} status             Report whether each AGENTS.md matches its render (no writes)
+
+MODEL
+  ~/.claude/CLAUDE.md in the dotclaude git repo is the only source. Edit it there
+  and commit. Each AGENTS.md is CLAUDE.md plus an optional addition kept in git
+  at ~/.claude/instructions/<codex|opencode>.md. Session start runs the render.
+  Repo CLAUDE.md/AGENTS.md files are ordinary files in their repos.
+
+REMOVED
+  pull, push, sync, adopt, revise, overlay, snapshot and restore refuse: GrepRAG
+  no longer holds instruction canon.${aliasNote}`;
 }
-/** Init-time seed for the active harness. No canon is a clean no-op; only a
- * missing/empty follower is written. Every existing nonmatching file requires
- * an explicit `instructions push` or `instructions pull`. */
-async function bootstrapAgentDoctrine(apiKey, harness) {
-    const result = {
-        canonicalScopes: [], currentFollowers: 0, changedFollowers: 0, blockedFollowers: 0,
-    };
-    for (const scope of ['global', 'repo']) {
-        const stats = await syncOne({
-            scope, args: [], check: false, force: false, apiKey, harness, quiet: true, seedOnly: true,
-        });
-        if (stats.canonical)
-            result.canonicalScopes.push(scope);
-        result.currentFollowers += stats.current;
-        result.changedFollowers += stats.changed;
-        result.blockedFollowers += stats.blocked;
-    }
-    return result;
+function printResults(results) {
+    for (const r of results)
+        console.log(`  ${r.status.padEnd(9)} ${r.path}`);
 }
 async function runInstructionsCommand(args, commandName) {
     const sub = args[0];
@@ -894,28 +176,25 @@ async function runInstructionsCommand(args, commandName) {
         console.log(help(commandName));
         return;
     }
-    if (sub === 'pull')
-        return exactSourceCommand(args.slice(1), 'pull');
-    if (sub === 'push')
-        return syncCommand(args.slice(1));
-    if (sub === 'adopt')
-        return exactSourceCommand(args.slice(1), 'adopt');
-    if (sub === 'revise')
-        return exactSourceCommand(args.slice(1), 'revise');
-    if (sub === 'overlay')
-        return overlayCommand(args.slice(1));
-    if (sub === 'snapshot')
-        return snapshotCommand(args.slice(1));
-    if (sub === 'restore')
-        return restoreCommand(args.slice(1));
-    if (sub === 'optimize') {
-        throw new Error(`${commandName} optimize was removed: use lossless ${commandName} pull or explicit ${commandName} overlay`);
+    if (sub === 'status' || (sub === 'render' && args.includes('--check'))) {
+        const results = renderGlobalInstructions({ check: true });
+        printResults(results);
+        if (results.some(r => r.status === 'stale'))
+            process.exitCode = 1;
+        return;
+    }
+    if (sub === 'render') {
+        printResults(renderGlobalInstructions());
+        const apiKey = process.env.GREPRAG_API_KEY || '';
+        if (apiKey) {
+            const apiUrl = process.env.GREPRAG_API_URL || 'https://api.greprag.com';
+            console.log(`  mirror    ${await mirrorCommittedInstructions({ apiUrl, apiKey })}`);
+        }
+        return;
     }
-    if (sub === 'sync')
-        return syncCommand(args.slice(1));
-    if (sub === 'status')
-        return syncCommand(args.slice(1), true);
-    throw new Error(`unknown ${commandName} command: ${sub}`);
+    throw new Error(`\`greprag ${commandName} ${sub}\` was removed: ~/.claude/CLAUDE.md in the dotclaude git repo is the source. `
+        + `Edit it there and commit; \`greprag ${commandName} render\` rewrites the AGENTS.md files `
+        + '(per-harness additions live in ~/.claude/instructions/<codex|opencode>.md).');
 }
 async function runInstructions(args) {
     return runInstructionsCommand(args, 'instructions');