@nazty_labs/common-ground 0.5.1

package/dist/access.js

@@ -0,0 +1,175 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { relativePath } from './model.js';
+import { same } from './store.js';
+import { page } from './paging.js';
+import { reviewDocuments } from './review-files.js';
+import { queryTerms, queryPath, termWeights, matchFields, termMatch } from './matching.js';
+import { isSourceSearchPathAllowed } from './source-search.js';
+const within = (file, scope) => file === scope || file.startsWith(`${scope}/`);
+const overlaps = (a, b) => within(a, b) || within(b, a);
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const tracks = (fact, file) => fact.sourceScope.some(s => within(file, s)) || fact.evidence.some(e => e.path === file);
+const paging = { cursor: z.string().optional(), limit: z.number().int().min(1).max(20).optional() };
+export const Lookup = z.object({ path: relativePath.optional(), query: z.string().trim().min(1).optional(), verify: z.boolean().default(false), verbose: z.boolean().default(false), cursor: paging.cursor, limit: z.number().int().min(1).max(5).default(5) }).strict();
+export const Assess = z.object({ paths: z.array(relativePath), review: z.boolean().default(false), ...paging }).strict();
+async function registryOrSetup(store) {
+    try {
+        return await store.read();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return undefined;
+    }
+}
+const setup = { state: 'knowledge-unavailable', writesKnowledge: false, items: [], next: 'Continue from source. Run cground init and review setup when appropriate; lookup requires no task context.' };
+/** Explicit verification is fact-scoped. A cache lives for this call only, never across reads/publication. */
+async function verifySelected(store, registry, selected) {
+    const index = new Map(store.facts(registry).map(entry => [entry.key, entry]));
+    const required = [...new Set(selected.flatMap(key => [key, ...store.upstreamFacts(registry, key, index)]))];
+    const cache = new Map();
+    const checked = new Map();
+    for (const key of required) {
+        const { chapter, fact } = index.get(key);
+        const errors = [];
+        let changedPaths = [];
+        try {
+            await store.validateFacts({ paths: chapter.paths, facts: [fact] });
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+        try {
+            const current = await store.snapshot({ paths: chapter.paths, facts: [fact] }, cache);
+            const baseline = Object.fromEntries(Object.entries(chapter.sources).filter(([file]) => tracks(fact, file)));
+            changedPaths = [...new Set([...Object.keys(current), ...Object.keys(baseline)])].filter(file => current[file] !== baseline[file]).sort();
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
+        checked.set(key, { changedPaths, errors });
+    }
+    return new Map(selected.map(key => {
+        const { chapter, chapterId } = index.get(key), own = checked.get(key);
+        const fingerprints = store.dependencyFingerprints(registry, chapterId);
+        const dependencyIssues = store.upstreamFacts(registry, key, index).filter(dep => {
+            const check = checked.get(dep);
+            return check.errors.length || check.changedPaths.length || chapter.dependencyFingerprints[dep] !== fingerprints[dep];
+        });
+        return [key, { status: own.errors.length || own.changedPaths.length || dependencyIssues.length ? 'needs-review' : 'evidence-unchanged', changedPaths: own.changedPaths.slice(0, 10), changedPathCount: own.changedPaths.length, errors: own.errors.slice(0, 3), errorCount: own.errors.length, dependencyIssues: dependencyIssues.slice(0, 5), dependencyIssueCount: dependencyIssues.length }];
+    }));
+}
+/** Cheap navigation: registry reads only unless live verification is explicitly requested. */
+export async function lookup(store, input) {
+    const args = Lookup.parse(input);
+    if (!args.path && !args.query)
+        throw new Error('Supply a lookup query or --path.');
+    const registry = await registryOrSetup(store);
+    if (!registry)
+        return { summary: 'No direct answer found.', ...setup, coverage: { status: 'unavailable' }, sourceSearch: { status: 'not-run', next: 'Choose source paths and run cground source-search QUERY --path PATH; this reads live source without requiring stored knowledge.' } };
+    const entries = store.facts(registry), candidatePath = queryPath(args.query);
+    const inferredPath = !args.path && candidatePath && store.chapters(registry).some(({ chapter }) => [...chapter.paths, ...chapter.facts.flatMap(f => f.evidence.map(e => e.path))].some(p => overlaps(candidatePath, p))) ? candidatePath : undefined;
+    const requestedPath = args.path ?? inferredPath, terms = queryTerms(args.query ?? '');
+    const { weights, commonTerms, distinctiveTerms } = termWeights(terms, entries.map(({ key, fact }) => `${key} ${fact.statement} ${fact.evidence.map(e => e.path).join(' ')}`));
+    const matches = entries.map(entry => {
+        const { fact, chapter } = entry;
+        const pathScore = !requestedPath ? 0 : fact.evidence.some(e => overlaps(requestedPath, e.path)) ? 100 : fact.sourceScope.some(s => overlaps(requestedPath, s)) ? 50 : chapter.paths.some(s => overlaps(requestedPath, s)) ? 1 : 0;
+        const sourceText = fact.evidence.map(e => e.path).join(' ');
+        const lexical = matchFields(terms, `${entry.key} ${sourceText}`, fact.statement, weights);
+        const direct = pathScore !== 1 && (inferredPath || !terms.length ? pathScore === 100 : distinctiveTerms.length > 0 && distinctiveTerms.every(term => termMatch(`${fact.statement} ${sourceText}`, term) > 0));
+        return { entry, pathScore, direct, ...lexical };
+    }).filter(m => requestedPath ? m.pathScore > 0 : m.matchedTerms.length > 0)
+        .sort((a, b) => b.pathScore - a.pathScore || b.weight - a.weight || b.matchedTerms.length - a.matchedTerms.length || a.entry.key.localeCompare(b.entry.key));
+    const direct = matches.some(m => m.direct);
+    const records = matches.map(({ entry, pathScore, matchedTerms, direct }) => ({ factId: entry.key, statement: entry.fact.statement, sourcePaths: [...new Set(entry.fact.evidence.map(e => e.path))],
+        relevance: pathScore === 1 ? 'ownership-only' : terms.length && matchedTerms.length < terms.length ? 'partial-query' : direct ? 'matched' : 'weak-match',
+        ...(args.verbose ? { chapterId: entry.chapterId, matchReason: pathScore === 100 ? 'direct-evidence' : pathScore === 50 ? 'source-scope' : pathScore === 1 ? 'ownership-suggestion' : 'query-terms',
+            matchedTerms, unmatchedTerms: terms.filter(t => !matchedTerms.includes(t)), queryCoverage: terms.length ? { matched: matchedTerms.length, total: terms.length } : null,
+            matchedPaths: requestedPath ? (pathScore === 100 ? entry.fact.evidence.map(e => e.path) : pathScore === 50 ? entry.fact.sourceScope : entry.chapter.paths).filter(p => overlaps(requestedPath, p)) : [] } : {}),
+    }));
+    const selected = page(records, args.cursor, args.limit, digest({ registry, path: args.path, query: args.query, verify: args.verify, verbose: args.verbose }), 6000);
+    const verified = args.verify ? await verifySelected(store, registry, selected.items.map(item => item.factId)) : undefined;
+    if (args.verify && !same(registry, await store.read()))
+        throw new Error('Knowledge changed during lookup; retry.');
+    // Navigation remains separate from facts and does not scan or hash the filesystem.
+    const routes = store.chapters(registry).map(({ key, pillar, chapter }) => {
+        const paths = [...new Set([...chapter.paths, ...Object.keys(chapter.sources).filter(file => chapter.paths.some(scope => within(file, scope)))])];
+        const lexical = matchFields(terms, `${key} ${pillar.title} ${chapter.title} ${paths.join(' ')}`, `${pillar.scope} ${chapter.scope}`, weights);
+        const pathMatch = !!requestedPath && chapter.paths.some(scope => overlaps(requestedPath, scope));
+        const ranked = paths.sort((a, b) => Number(!!requestedPath && overlaps(requestedPath, b)) - Number(!!requestedPath && overlaps(requestedPath, a))
+            || terms.reduce((n, t) => n + (termMatch(b, t) - termMatch(a, t)) * (weights.get(t) ?? 1), 0) || a.localeCompare(b));
+        return { chapterId: key, title: chapter.title, paths: ranked.slice(0, 5), pathCount: paths.length, pathsTruncated: paths.length > 5,
+            matchedTerms: lexical.matchedTerms, pathMatch, weight: lexical.weight };
+    }).filter(route => requestedPath ? route.pathMatch : route.matchedTerms.length > 0)
+        .sort((a, b) => b.weight - a.weight || b.matchedTerms.length - a.matchedTerms.length || a.chapterId.localeCompare(b.chapterId));
+    const navigation = { kind: 'ownership-navigation', freshness: 'not-checked', items: routes.slice(0, 3).map(({ pathMatch, weight, matchedTerms, pathCount, pathsTruncated, ...route }) => ({ ...route, ...(args.verbose ? { matchedTerms, pathCount, pathsTruncated } : {}) })), total: routes.length, truncated: routes.length > 3 };
+    const fallbackPaths = [...new Set(requestedPath ? [requestedPath] : [
+            ...matches.slice(0, 5).flatMap(({ entry }) => entry.fact.evidence.map(e => e.path)),
+            ...routes.slice(0, 3).flatMap(r => r.paths),
+        ])].filter(isSourceSearchPathAllowed).slice(0, 5);
+    const fallbackTerms = distinctiveTerms.length ? distinctiveTerms : terms;
+    const resultItems = selected.items.map(item => {
+        const freshness = verified?.get(item.factId) ?? { status: 'not-checked' };
+        return { ...item, freshness: !args.verbose && freshness.status === 'evidence-unchanged' ? { status: freshness.status } : freshness };
+    });
+    return { summary: direct ? 'Relevant stored facts found.' : 'No direct answer found.', state: records.length ? 'matches' : 'no-matches', writesKnowledge: false,
+        coverage: { status: direct ? 'direct-match' : records.length ? 'weak' : 'none', ...(args.verbose ? { terms, downweightedTerms: commonTerms, distinctiveTerms } : {}) },
+        // With weak coverage, navigation precedes stored partial matches in serialized output.
+        ...(!direct ? { navigation } : {}), items: resultItems, total: selected.total, nextCursor: selected.nextCursor, ...(direct ? { navigation } : {}),
+        ...(!direct ? { sourceSearch: { status: 'not-run', operation: 'source-search', ...(fallbackPaths.length ? { args: { query: fallbackTerms.join(' ') || args.query || requestedPath, paths: fallbackPaths } } : {}),
+                next: fallbackPaths.length ? 'Run this separate operation to inspect live source evidence; adjust the suggested paths and query first if needed.' : 'Choose eligible source paths before running cground source-search QUERY --path PATH. Read any excluded configuration paths directly.' } } : {}),
+        caveat: 'Stored matches are lexical navigation, not proof of an answer or complete coverage. Read source. Navigation paths are unverified; --verify checks only selected facts and dependencies.',
+        next: direct ? 'Read the cited source before relying on these claims.' : 'Read source using the navigation hints or the separate source-search fallback.',
+    };
+}
+/** Compare only task-touched portions of candidate fact scopes, including additions/deletions. */
+export async function changedFacts(store, registry, paths) {
+    const candidates = store.facts(registry).filter(({ fact }) => paths.some(p => fact.sourceScope.some(s => overlaps(p, s)) || fact.evidence.some(e => overlaps(p, e.path))));
+    const cache = new Map(), observations = [];
+    const changed = [];
+    for (const entry of candidates) {
+        const { fact, chapter } = entry;
+        const errors = [];
+        let changedPaths = [];
+        const sourceScope = [...new Set(fact.sourceScope.flatMap(scope => paths.filter(p => overlaps(p, scope)).map(p => within(p, scope) ? p : scope)))];
+        const evidence = fact.evidence.filter(e => paths.some(p => overlaps(p, e.path)));
+        try {
+            const current = await store.snapshot({ paths: chapter.paths, facts: [{ ...fact, sourceScope, evidence }] }, cache);
+            const baseline = Object.fromEntries(Object.entries(chapter.sources).filter(([file]) => tracks(fact, file) && paths.some(p => overlaps(p, file))));
+            changedPaths = [...new Set([...Object.keys(current), ...Object.keys(baseline)])].filter(p => current[p] !== baseline[p]).sort();
+            observations.push({ key: entry.key, current });
+        }
+        catch (error) {
+            errors.push(error.message);
+            observations.push({ key: entry.key, errors });
+        }
+        if (changedPaths.length || errors.length)
+            changed.push({ entry, changedPaths, errors });
+    }
+    return { candidates, candidateFactCount: candidates.length, changed, fingerprint: digest(observations) };
+}
+/** Read-only change assessment. Review records are created only by subsequent preparation. */
+export async function assessChanges(store, input) {
+    const { paths: raw, cursor, limit, review } = Assess.parse(input), paths = [...new Set(raw)].sort();
+    const registry = await registryOrSetup(store);
+    if (!registry)
+        return setup;
+    const impact = await changedFacts(store, registry, paths);
+    const scopes = review ? [...new Set(impact.candidates.map(entry => entry.chapterId))].sort().map(chapterId => ({ kind: 'review-scope', chapterId, requiredChapterIds: store.related(registry, chapterId) })) : [];
+    const keys = [...new Set(scopes.flatMap(scope => scope.requiredChapterIds))].sort();
+    // Whole chapters are required only on the branch that might revise knowledge.
+    const files = keys.length ? await store.reviewFiles(registry, keys, paths) : { sourceFiles: [], documentFiles: await reviewDocuments(store, paths, 'focused') };
+    const entries = [...impact.changed.map(({ entry, changedPaths, errors }) => ({ kind: 'affected-fact', factId: entry.key, statement: entry.fact.statement, sourcePaths: [...new Set(entry.fact.evidence.map(e => e.path))], changedPaths: changedPaths.slice(0, 10), changedPathCount: changedPaths.length, errors })),
+        ...scopes, ...keys.flatMap(chapterId => {
+            const chapter = store.chapter(registry, chapterId);
+            return [{ kind: 'chapter', chapterId, expectedRevision: chapter.revision, factCount: chapter.facts.length },
+                ...chapter.facts.map(fact => ({ kind: 'fact', chapterId, fact }))];
+        }), ...files.sourceFiles.map(path => ({ kind: 'source', path })), ...files.documentFiles.map(path => ({ kind: 'document', path }))];
+    if (!same(registry, await store.read()))
+        throw new Error('Knowledge changed during assessment; retry.');
+    return { state: keys.length ? 'review-required' : impact.changed.length ? 'source-review-required' : 'no-fact-review', writesKnowledge: false, createsTask: false,
+        candidateFactCount: impact.candidateFactCount, affectedFactCount: impact.changed.length,
+        ...page(entries, cursor, limit, digest({ registry, paths, review, observations: impact.fingerprint }), 12000),
+        next: keys.length ? 'Read every package page and its source/documentation. Prepare each initiating review-scope with its exact required chapters; do not combine unrelated scopes. prepare-patch accepts no taskId; commit only after verification. Source drift alone does not prove a claim false.' : impact.changed.length ? 'Verify affected claims against source. If a correction is needed, rerun assess with --review for the complete chapter/source package. No task start or finish is needed.' : 'Review the listed local documentation and source relevant to the edit. No task start or finish is needed. Path matching cannot rule out semantic connections discovered in source.' };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { parseCommand, helpText, payloadExamples } from './commands.js';
+import { version } from './version.js';
+const list = (value) => value ? String(value).split(',') : [];
+async function json(file) {
+    try {
+        if (file === '-') {
+            process.stdin.setEncoding('utf8');
+            let text = '';
+            for await (const chunk of process.stdin)
+                text += chunk;
+            return JSON.parse(text);
+        }
+        return JSON.parse(await fs.readFile(path.resolve(file), 'utf8'));
+    }
+    catch (error) {
+        const { GroundError } = await import('./errors.js');
+        const code = error.code;
+        throw new GroundError(code === 'ENOENT' ? 'INPUT_NOT_FOUND' : error instanceof SyntaxError ? 'INVALID_JSON' : 'INPUT_UNREADABLE', `Cannot read JSON from ${file}: ${error.message}`, [file], code === 'ENOENT' ? 'Check the input filename, or supply the payload with --stdin.' : error instanceof SyntaxError ? 'Correct the JSON syntax; inspect cground schema <operation>.' : 'Check the input file permissions and ensure it is a readable regular file.');
+    }
+}
+// Adapt shell arguments to the same structured operations used by MCP.
+async function input(name, args, values) {
+    const [first, second, third] = args;
+    const paging = { cursor: values.cursor, limit: values.limit === undefined ? undefined : Number(values.limit) };
+    switch (name) {
+        case 'init': return { skipHook: values['skip-hook'] ?? false };
+        case 'lookup': return { path: values.path, query: args.join(' ') || undefined, verify: values.verify ?? false, verbose: values.verbose ?? false, ...paging };
+        case 'source-search': return { paths: list(values.path), query: args.join(' '), limit: paging.limit };
+        case 'assess': return { paths: list(values.touched), review: values.review ?? false, ...paging };
+        case 'schema': return { operation: first, both: values.both ?? false };
+        case 'scan': return { exclude: list(values.exclude) };
+        case 'bootstrap':
+        case 'seed-batch': return { ...await json(first), dryRun: values['dry-run'] ?? false, approved: values.approve, preflight: values.preflight };
+        case 'approve': return { pillars: (await json(first)).pillars, approved: values.approve, verbose: values.verbose, standaloneReason: values['standalone-reason'] };
+        case 'approve-chapters': return { pillarId: first, chapters: (await json(second)).chapters, approved: values.approve, verbose: values.verbose };
+        case 'seed':
+        case 'admit': return { chapterId: first, facts: await json(second), approved: values.approve, verbose: values.verbose };
+        case 'migrate': return { approved: values.approve };
+        case 'task start': return { paths: list(values.touched), signal: values.signal };
+        case 'task assess': return { taskId: first, paths: list(values.touched), ...paging };
+        case 'task finish': return { taskId: first, ...paging };
+        case 'read-knowledge':
+        case 'prepare-patch':
+        case 'prepare': return json(first);
+        case 'propose-facts': return { taskId: first, chapterId: second, facts: await json(third) };
+        case 'drop-facts': return { taskId: first, factKeys: args.slice(1) };
+        case 'accept-facts': return { taskId: first, review: await json(second), approved: values.approve };
+        case 'start':
+        case 'owners': return { path: values.path, signal: values.signal ?? (args.join(' ') || undefined), ...paging };
+        case 'graph': return { pillarId: first, ...paging };
+        case 'check':
+        case 'validate': return { target: first ?? 'all', cleanup: String(values.cleanup).toLowerCase() === 'y', allResults: values['all-results'] ?? false, ...paging };
+        case 'review': return { target: first ?? 'all', staged: values.staged ?? false, evidence: values.evidence ?? false, ...paging };
+        case 'tidy': return { target: first, ...paging };
+        case 'review-checklist': return { chapterIds: args, touchedPaths: list(values.touched), ...paging };
+        case 'list': return paging;
+        case 'chapters': return { pillarId: first, ...paging };
+        case 'read': return { chapterId: first, ...paging };
+        case 'fact': return { chapterId: first, factId: second };
+        case 'review-plan': return { chapterId: first, factIds: values.facts === undefined ? undefined : list(values.facts) };
+        case 'search': return { query: args.join(' '), chapterId: values.chapter, limit: paging.limit };
+        case 'commit': return { proposalId: first };
+        default: return {};
+    }
+}
+function initText(result, root) {
+    const link = (file) => `[${file}](${path.resolve(root, file)})`;
+    return [result.setup.status === 'complete-with-warnings' ? 'Common Ground initialized with setup warnings.' : 'Common Ground initialized.', result.hook,
+        'existingRegistry' in result
+            ? `Ask your agent to summarize knowledge changes with cground review before sharing.`
+            : `Ask your agent to summarize the proposed responsibility map and verify its facts.\nPublish with content approval or explicit developer delegation to save the initial map within scope.`,
+        `Local Markdown: ${link(result.markdown.path)}`].join('\n');
+}
+function checkText(result) {
+    const lines = [`${result.target}: ${result.valid ? 'knowledge checks passed' : 'knowledge needs review'}.`,
+        `${result.summary.selectedFacts} selected facts; ${result.summary.needsReview} need review.`];
+    if (result.summary.unpopulatedChapters.length)
+        lines.push(`Empty chapters: ${result.summary.unpopulatedChapters.join(', ')}. Complete approved setup with your agent.`);
+    if (!result.summary.selectedFacts)
+        lines.push('No facts recorded. Complete setup with your agent.');
+    for (const item of result.items) {
+        lines.push(`${item.factId}: ${item.status}`);
+        for (const error of item.errors)
+            lines.push(`  ${error}`);
+        if (item.changedPaths.length)
+            lines.push(`  Changed: ${item.changedPaths.join(', ')}`);
+    }
+    if (result.nextCursor)
+        lines.push(`More results: rerun with --cursor ${result.nextCursor}`);
+    if (result.cleanup)
+        lines.push(`Cleanup plan: ${result.cleanup.tidyId}`, 'Ask your agent to review the affected source and apply verified corrections.');
+    lines.push(`Review changes with your agent: cground review`, `Markdown: ${result.markdown.path}`);
+    return lines.join('\n');
+}
+async function main() {
+    const parsed = parseCommand(process.argv.slice(2));
+    if (parsed.help) {
+        console.log(helpText(parsed.command, parsed.group));
+        return;
+    }
+    const { command, values, positionals } = parsed;
+    if (!command) {
+        console.log(values.json ? JSON.stringify({ version }) : version);
+        return;
+    }
+    if (['bootstrap', 'seed-batch'].includes(command.name) && values['dry-run'] === true) {
+        const { Store } = await import('./store.js');
+        const { runOperation } = await import('./operations.js');
+        console.log(JSON.stringify(await runOperation(new Store(String(values.root ?? process.cwd())), command.operation, await input(command.name, positionals, values)), null, 2));
+        return;
+    }
+    if (command.flags.includes('approve') && values.approve !== true)
+        throw new Error('Developer approval required: inspect the proposal, then pass --approve.');
+    const root = String(values.root ?? process.cwd());
+    const { Store } = await import('./store.js');
+    const store = new Store(root);
+    if (command.name === 'serve') {
+        const { serve } = await import('./server.js');
+        await serve(store, values.profile);
+        return;
+    }
+    const { runOperation } = await import('./operations.js');
+    let output = await runOperation(store, command.operation, await input(command.name, positionals, values));
+    if (command.name === 'schema') {
+        output = { ...output, example: payloadExamples[positionals[0]], note: 'cliPayloadSchema describes the CLI JSON payload; --both includes inputSchema for MCP arguments. CLI seed/admit/propose-facts payloads contain only the facts array; approval is supplied with --approve.' };
+    }
+    if (['check', 'validate'].includes(command.name)) {
+        let result = output;
+        if (result.cleanupPrompt) {
+            const { staleMessage, checkKnowledge } = await import('./maintenance.js');
+            console.error(staleMessage(result));
+            console.error('Source drift requires review; it does not prove the stored claim is false.');
+            if (values.cleanup === undefined && process.stdin.isTTY && process.stdout.isTTY && process.stderr.isTTY && !values.json) {
+                const prompt = createInterface({ input: process.stdin, output: process.stderr });
+                let answer;
+                try {
+                    answer = await prompt.question('Start automatic cleanup? [y/N] ');
+                }
+                finally {
+                    prompt.close();
+                }
+                if (['y', 'yes'].includes(answer.trim().toLowerCase()))
+                    result = await checkKnowledge(store, result.target, true, values.cursor, values.limit === undefined ? undefined : Number(values.limit), result.affected, values['all-results'] === true);
+            }
+            else if (values.cleanup === undefined)
+                console.error('Start automatic cleanup? Use --cleanup y or --cleanup n (agent verification required).');
+        }
+        if (!result.valid)
+            process.exitCode = 1;
+        output = process.stdout.isTTY && !values.json ? checkText(result) : result;
+    }
+    if (command.name === 'review' && !values.json) {
+        const { reviewText } = await import('./review.js');
+        output = reviewText(output);
+    }
+    if (command.name === 'doctor' && !output.valid)
+        process.exitCode = 1;
+    if (process.stdout.isTTY && !values.json) {
+        if (command.name === 'doctor') {
+            const result = output;
+            const missing = Object.entries(result).filter(([, value]) => value === 'missing').map(([file]) => file);
+            output = result.valid ? 'Common Ground setup checks passed.' : `Common Ground setup needs attention.\n${missing.map(file => `Missing: ${file}`).join('\n')}${result.registryError ? `\nRegistry: ${result.registryError}` : ''}\nGuidance: ${result.guidance.status}. Run cground refresh-guidance for stale instructions; run cground init for missing setup. Review any registry errors with your agent.`;
+        }
+        if (command.name === 'export') {
+            const result = output;
+            output = `Markdown ${result.changed ? 'refreshed' : 'already current'}: ${path.resolve(root, result.path)}`;
+        }
+        if (command.name === 'tidy') {
+            const result = output;
+            output = [`Cleanup scope: ${result.target} (${result.requiredChapterCount} chapters).`, ...result.chapters.items.map(chapter => `  ${chapter.chapterId}`), ...('tidyId' in result && result.tidyId ? [`Tidy ID: ${result.tidyId}`] : []), ...(result.chapters.nextCursor ? [`More chapters: rerun with --cursor ${result.chapters.nextCursor}`] : []), 'Ask your agent to read all required chapters and source, then submit verified corrections.'].join('\n');
+        }
+    }
+    if (command.name === 'hook check' && !values.json) {
+        const { message } = output;
+        if (message)
+            console.error(message);
+        return;
+    }
+    if (command.name === 'init' && !values.json)
+        output = initText(output, root);
+    console.log(typeof output === 'string' && !values.json ? output : JSON.stringify(output, null, 2));
+}
+main().catch(async (error) => {
+    // Schema issues are useful, but a raw Zod stack/dump is not a CLI explanation.
+    const message = Array.isArray(error.issues) ? error.issues.map((issue) => `${issue.path.join('.') || 'input'}: ${issue.message}`).join('; ') : error.message;
+    const args = process.argv.slice(2), end = args.indexOf('--');
+    if ((end < 0 ? args : args.slice(0, end)).includes('--json')) {
+        const { errorPayload } = await import('./errors.js');
+        console.error(JSON.stringify({ error: errorPayload(error) }));
+    }
+    else
+        console.error(`Common Ground: ${message}\nRun cground <command> --help for usage.`);
+    process.exitCode = 1;
+});

package/dist/commands.d.ts

@@ -0,0 +1,189 @@
+export declare const options: {
+    readonly 'skip-hook': {
+        readonly type: "boolean";
+        readonly label: "--skip-hook";
+        readonly description: "Finish repository setup without installing the advisory Git hook; install it later with cground hook install";
+    };
+    readonly both: {
+        readonly type: "boolean";
+        readonly label: "--both";
+        readonly description: "Include both CLI payload and MCP operation schemas";
+    };
+    readonly exclude: {
+        readonly type: "string";
+        readonly label: "--exclude <paths>";
+        readonly description: "Comma-separated repository-relative paths to exclude from discovery";
+    };
+    readonly verify: {
+        readonly type: "boolean";
+        readonly label: "--verify";
+        readonly description: "Check selected facts and upstream source freshness";
+    };
+    readonly review: {
+        readonly type: "boolean";
+        readonly label: "--review";
+        readonly description: "Include complete chapters and source/documentation paths before knowledge correction";
+    };
+    readonly stdin: {
+        readonly type: "boolean";
+        readonly label: "--stdin";
+        readonly description: "Read the JSON payload from stdin instead of a file";
+    };
+    readonly example: {
+        readonly type: "boolean";
+        readonly label: "--example";
+        readonly description: "Show a copyable JSON payload with help";
+    };
+    readonly verbose: {
+        readonly type: "boolean";
+        readonly label: "--verbose";
+        readonly description: "Include lookup matching diagnostics or complete mutation objects";
+    };
+    readonly 'all-results': {
+        readonly type: "boolean";
+        readonly label: "--all-results";
+        readonly description: "Include passing validation rows";
+    };
+    readonly 'dry-run': {
+        readonly type: "boolean";
+        readonly label: "--dry-run";
+        readonly description: "Preflight without writing knowledge or requiring approval";
+    };
+    readonly preflight: {
+        readonly type: "string";
+        readonly label: "--preflight <token>";
+        readonly description: "Token from the reviewed dry run; rejects source or payload changes";
+    };
+    readonly help: {
+        readonly type: "boolean";
+        readonly short: "h";
+        readonly label: "-h, --help";
+        readonly description: "Show help without running the command";
+    };
+    readonly version: {
+        readonly type: "boolean";
+        readonly short: "V";
+        readonly label: "-V, --version";
+        readonly description: "Show the installed version";
+    };
+    readonly root: {
+        readonly type: "string";
+        readonly label: "--root <path>";
+        readonly description: "Repository root (default: current directory)";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly label: "--json";
+        readonly description: "Return JSON; never prompt for input";
+    };
+    readonly cursor: {
+        readonly type: "string";
+        readonly label: "--cursor <token>";
+        readonly description: "Continue a paginated result";
+    };
+    readonly limit: {
+        readonly type: "string";
+        readonly label: "--limit <1..20>";
+        readonly description: "Maximum records per page (default: 10; search: 8)";
+    };
+    readonly staged: {
+        readonly type: "boolean";
+        readonly label: "--staged";
+        readonly description: "Review staged knowledge instead of the working file";
+    };
+    readonly evidence: {
+        readonly type: "boolean";
+        readonly label: "--evidence";
+        readonly description: "Include exact changed evidence quotes in the review";
+    };
+    readonly cleanup: {
+        readonly type: "string";
+        readonly label: "--cleanup <y|n>";
+        readonly description: "Start or decline agent-led cleanup when stale";
+    };
+    readonly approve: {
+        readonly type: "boolean";
+        readonly label: "--approve";
+        readonly description: "Declare explicit developer approval of the proposed content";
+    };
+    readonly path: {
+        readonly type: "string";
+        readonly label: "--path <path>";
+        readonly description: "Repository-relative source path for ownership routing";
+    };
+    readonly signal: {
+        readonly type: "string";
+        readonly label: "--signal <text>";
+        readonly description: "Short symptom or routing hint";
+    };
+    readonly touched: {
+        readonly type: "string";
+        readonly label: "--touched <paths>";
+        readonly description: "Comma-separated paths touched by this task; empty means none";
+    };
+    readonly chapter: {
+        readonly type: "string";
+        readonly label: "--chapter <id>";
+        readonly description: "Restrict search to pillar/chapter";
+    };
+    readonly facts: {
+        readonly type: "string";
+        readonly label: "--facts <ids>";
+        readonly description: "Comma-separated fact IDs to review";
+    };
+    readonly profile: {
+        readonly type: "string";
+        readonly label: "--profile <compact|full>";
+        readonly description: "MCP tool profile (default: compact)";
+    };
+    readonly 'standalone-reason': {
+        readonly type: "string";
+        readonly label: "--standalone-reason <text>";
+        readonly description: "Why an additional pillar owns an uncovered responsibility";
+    };
+};
+type Flag = keyof typeof options;
+type Group = 'Everyday' | 'Navigation' | 'Agent workflows';
+export type CommandSpec = {
+    name: string;
+    operation: string;
+    arguments: string;
+    description: string;
+    flags: Flag[];
+    example: string;
+    group: Group;
+};
+export declare const commands: CommandSpec[];
+export declare const factExample: {
+    id: string;
+    statement: string;
+    evidence: {
+        path: string;
+        quote: string;
+    }[];
+    sourceScope: string[];
+    dependsOn: never[];
+};
+export declare const payloadExamples: Record<string, unknown>;
+export type Values = Partial<Record<Flag, string | boolean>>;
+export declare function parseCommand(argv: string[]): {
+    values: Partial<Record<"path" | "evidence" | "facts" | "chapter" | "preflight" | "limit" | "verify" | "verbose" | "cursor" | "review" | "skip-hook" | "both" | "exclude" | "stdin" | "example" | "all-results" | "dry-run" | "help" | "version" | "root" | "json" | "staged" | "cleanup" | "approve" | "signal" | "touched" | "profile" | "standalone-reason", string | boolean>>;
+    help: boolean;
+    command: undefined;
+    positionals: never[];
+    group: undefined;
+} | {
+    values: Partial<Record<"path" | "evidence" | "facts" | "chapter" | "preflight" | "limit" | "verify" | "verbose" | "cursor" | "review" | "skip-hook" | "both" | "exclude" | "stdin" | "example" | "all-results" | "dry-run" | "help" | "version" | "root" | "json" | "staged" | "cleanup" | "approve" | "signal" | "touched" | "profile" | "standalone-reason", string | boolean>>;
+    help: boolean;
+    command: undefined;
+    positionals: never[];
+    group: string;
+} | {
+    values: Partial<Record<"path" | "evidence" | "facts" | "chapter" | "preflight" | "limit" | "verify" | "verbose" | "cursor" | "review" | "skip-hook" | "both" | "exclude" | "stdin" | "example" | "all-results" | "dry-run" | "help" | "version" | "root" | "json" | "staged" | "cleanup" | "approve" | "signal" | "touched" | "profile" | "standalone-reason", string | boolean>>;
+    help: boolean;
+    command: CommandSpec;
+    positionals: string[];
+    group: undefined;
+};
+export declare function helpText(command?: CommandSpec, group?: string): string;
+export {};