yarramate 0.3.3 → 0.5.0

package/README.md

@@ -106,6 +106,7 @@ npm install --global yarramate
 yarramate --help
 
 npx yarramate check .yarramate/workspace.yaml
+npx yarramate status .yarramate/workspace.yaml --json
 ```
 
 When developing the repository, build and invoke the same executable surface:

package/dist/adapters/graphify-cli.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { adapterMappingEntryLocation, adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { compileWorkspace } from '../compiler.js';
-import { diagnosticJson, isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
+import { diagnosticJson, isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
 import { observeGraphify, } from './graphify.js';
 const usage = 'Usage:\n' +
     '  yarramate-graphify observe <graph.json> <mapping.yaml> <workspace-or-source...> --id <evidence-id> --version <major.minor>\n';
@@ -35,6 +35,9 @@ const parseOptions = (options) => {
 };
 export function runGraphifyCli(args, cwd = process.cwd()) {
     const [command, ...options] = args;
+    if (command === '--version') {
+        return versionResult('yarramate-graphify');
+    }
     const parsed = command === 'observe' ? parseOptions(options) : undefined;
     if (parsed === undefined ||
         !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(parsed.id) ||

package/dist/adapters/likec4-cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { isMap, isSeq, parseDocument } from 'yaml';
-import { isMainModule, resolveCliWorkspaceSources, } from '../cli-support.js';
+import { isMainModule, resolveCliWorkspaceSources, versionResult, } from '../cli-support.js';
 import { compileWorkspace } from '../compiler.js';
 import { adapterMappingLocation, loadAdapterMapping, validateAdapterMapping, } from '../adapter-mapping.js';
 import { locateSourcePath } from '../source-document.js';
@@ -88,6 +88,33 @@ const checkJson = (ok, diagnostics) => `${JSON.stringify({
     ok,
     diagnostics,
 }, null, 2)}\n`;
+const unmappedSubjectPreviewLength = 3;
+const summarizeUnmappedConcepts = (diagnostics) => {
+    const unmapped = diagnostics.filter((diagnostic) => diagnostic.code === 'YMLC102');
+    if (unmapped.length <= unmappedSubjectPreviewLength)
+        return diagnostics;
+    const preview = unmapped
+        .slice(0, unmappedSubjectPreviewLength)
+        .map((diagnostic) => 'subject' in diagnostic && diagnostic.subject !== undefined
+        ? `"${diagnostic.subject}"`
+        : `"${diagnostic.path}:${diagnostic.line}"`)
+        .join(', ');
+    const summary = {
+        ...unmapped[0],
+        message: `${unmapped.length} projected concepts have no LikeC4 mapping ` +
+            `(first: ${preview}); run "yarramate-likec4 map --sync" to add ` +
+            'the missing mappings',
+    };
+    let summarized = false;
+    return diagnostics.flatMap((diagnostic) => {
+        if (diagnostic.code !== 'YMLC102')
+            return [diagnostic];
+        if (summarized)
+            return [];
+        summarized = true;
+        return [summary];
+    });
+};
 const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
 const lowerCamel = (value) => value.replaceAll(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
 const runLikeC4MapSync = (args, cwd) => {
@@ -371,6 +398,9 @@ const publishGeneratedProject = (cwd, outputDirectory, input) => {
     };
 };
 export function runLikeC4Cli(args, cwd = process.cwd()) {
+    if (args[0] === '--version') {
+        return versionResult('yarramate-likec4');
+    }
     if (args[0] === 'map') {
         return runLikeC4MapSync(args.slice(1), cwd);
     }
@@ -460,7 +490,11 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
         sourcePaths.some((argument) => argument.startsWith('-'))) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
-    const diagnosticOutput = (diagnostics) => (json ? checkJson(false, diagnostics) : diagnosticJson(diagnostics));
+    const diagnosticOutput = (diagnostics) => json
+        ? checkJson(false, diagnostics)
+        : diagnosticJson(command === 'check'
+            ? summarizeUnmappedConcepts(diagnostics)
+            : diagnostics);
     try {
         const resolved = resolveCliWorkspaceSources(sourcePaths, cwd);
         if (!resolved.ok) {
@@ -487,6 +521,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                     stderr: '',
                 };
             }
+            const projectDirectory = dirname(resolve(cwd, projectionPath));
             const referencedSources = new Map();
             const referenceDiagnostics = [];
             const readProjectReference = (path, label, yamlPath, pointer) => {
@@ -496,7 +531,7 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 try {
                     const source = {
                         path,
-                        source: readFileSync(resolve(cwd, path), 'utf8'),
+                        source: readFileSync(resolve(projectDirectory, path), 'utf8'),
                     };
                     referencedSources.set(path, source);
                     return source;

package/dist/adapters/mcp-cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id?: number | string | null;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export declare const handleRequest: (request: JsonRpcRequest) => void;
+export {};

package/dist/adapters/mcp-cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline';
+import { isMainModule, packageVersion, versionResult, } from '../cli-support.js';
+import { runCli } from '../cli.js';
+const workspaceProperty = {
+    workspace: {
+        type: 'string',
+        description: 'Path to the explicit workspace manifest, for example .yarramate/workspace.yaml',
+    },
+};
+const tools = [
+    {
+        name: 'yarramate_status',
+        description: 'One-call workspace orientation: check verdict, reconciliation summary, and a titled inventory of documents, states, projections, evidence, and contracts.',
+        inputSchema: {
+            type: 'object',
+            required: ['workspace'],
+            properties: workspaceProperty,
+        },
+        arguments: (input) => ['status', String(input.workspace), '--json'],
+    },
+    {
+        name: 'yarramate_check',
+        description: 'Deterministic correctness check of a workspace; returns the machine-readable check result. Never a quality or completeness judgement.',
+        inputSchema: {
+            type: 'object',
+            required: ['workspace'],
+            properties: workspaceProperty,
+        },
+        arguments: (input) => ['check', String(input.workspace), '--json'],
+    },
+    {
+        name: 'yarramate_reconcile',
+        description: 'Compare declared architecture with evaluated evidence; returns the reconciliation report with contradicted, unknown, and not-observed findings.',
+        inputSchema: {
+            type: 'object',
+            required: ['workspace'],
+            properties: workspaceProperty,
+        },
+        arguments: (input) => ['reconcile', String(input.workspace)],
+    },
+    {
+        name: 'yarramate_context',
+        description: 'Bounded architecture context. Provide either a projection path or one or more globally qualified subjects (document-id#local-id) for an ad-hoc connected neighbourhood. Optional token budget switches to a compact ranked rendering.',
+        inputSchema: {
+            type: 'object',
+            required: ['workspace'],
+            properties: {
+                ...workspaceProperty,
+                projection: {
+                    type: 'string',
+                    description: 'Path to an authored projection definition',
+                },
+                subjects: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Globally qualified subject identities for ad-hoc context',
+                },
+                budget: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Approximate token budget for the compact rendering',
+                },
+            },
+        },
+        arguments: (input) => {
+            const budget = typeof input.budget === 'number'
+                ? ['--budget', String(input.budget)]
+                : [];
+            if (typeof input.projection === 'string') {
+                return [
+                    'context',
+                    input.projection,
+                    String(input.workspace),
+                    ...budget,
+                ];
+            }
+            const subjects = Array.isArray(input.subjects)
+                ? input.subjects.flatMap((subject) => [
+                    '--subject',
+                    String(subject),
+                ])
+                : [];
+            return ['context', ...subjects, String(input.workspace), ...budget];
+        },
+    },
+];
+const respond = (id, result) => {
+    process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
+};
+const respondError = (id, code, message) => {
+    process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } })}\n`);
+};
+export const handleRequest = (request) => {
+    const id = request.id ?? null;
+    if (request.method === 'initialize') {
+        respond(id, {
+            protocolVersion: '2025-06-18',
+            capabilities: { tools: {} },
+            serverInfo: { name: 'yarramate', version: packageVersion },
+            instructions: 'Read-only architecture context for YarraMate workspaces. The native documents in the repository remain canonical; this server never mutates them.',
+        });
+        return;
+    }
+    if (request.method === 'tools/list') {
+        respond(id, {
+            tools: tools.map(({ name, description, inputSchema }) => ({
+                name,
+                description,
+                inputSchema,
+            })),
+        });
+        return;
+    }
+    if (request.method === 'tools/call') {
+        const params = request.params ?? {};
+        const name = typeof params.name === 'string' ? params.name : '';
+        const tool = tools.find((candidate) => candidate.name === name);
+        if (tool === undefined) {
+            respondError(id, -32602, `Unknown tool "${name}"`);
+            return;
+        }
+        const input = typeof params.arguments === 'object' && params.arguments !== null
+            ? params.arguments
+            : {};
+        const result = runCli([...tool.arguments(input)], process.cwd());
+        respond(id, {
+            content: [
+                {
+                    type: 'text',
+                    text: result.exitCode === 0
+                        ? result.stdout
+                        : result.stdout || result.stderr,
+                },
+            ],
+            isError: result.exitCode !== 0,
+        });
+        return;
+    }
+    if (request.id !== undefined) {
+        respondError(id, -32601, `Method "${request.method}" not found`);
+    }
+};
+if (isMainModule(import.meta.url, process.argv[1])) {
+    if (process.argv[2] === '--version') {
+        const result = versionResult('yarramate-mcp');
+        process.stdout.write(result.stdout);
+        process.exitCode = result.exitCode;
+    }
+    else {
+        const lines = createInterface({ input: process.stdin });
+        lines.on('line', (line) => {
+            const text = line.trim();
+            if (text.length === 0)
+                return;
+            let request;
+            try {
+                request = JSON.parse(text);
+            }
+            catch {
+                respondError(null, -32700, 'Parse error');
+                return;
+            }
+            try {
+                handleRequest(request);
+            }
+            catch (error) {
+                respondError(request.id ?? null, -32603, error instanceof Error ? error.message : String(error));
+            }
+        });
+    }
+}

package/dist/cli-support.d.ts

@@ -5,7 +5,9 @@ export interface CliResult {
     readonly stderr: string;
 }
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
-export declare const usage = "Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
+export declare const packageVersion: string;
+export declare const versionResult: (binary: string) => CliResult;
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;

package/dist/cli-support.js

@@ -3,6 +3,9 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { loadWorkspaceManifest } from './workspace.js';
+import packageManifest from '../package.json' with {
+    type: 'json'
+};
 export const isMainModule = (moduleUrl, entrypoint) => {
     if (entrypoint === undefined)
         return false;
@@ -14,7 +17,13 @@ export const isMainModule = (moduleUrl, entrypoint) => {
         return false;
     }
 };
-export const usage = 'Usage:\n  yarramate init <directory>\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n';
+export const packageVersion = packageManifest.version;
+export const versionResult = (binary) => ({
+    exitCode: 0,
+    stdout: `${binary} ${packageVersion}\n`,
+    stderr: '',
+});
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate add <document.yaml> --id <id> --kind <kind> --name <name> [--status <status>] [--description <text>] [--owner <ref>] [--constraint <id>=<ref> ...] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate connect <document.yaml> --id <id> --kind <kind> --from <ref> --to <ref> [--name <name>] [--description <text>] [--status <status>] [--mode <mode>] [--content <text>] [--reference <id>=<ref> ...] [--present-in <state-ref> ...] [--source <source.yaml> ...]\n  yarramate check <source.yaml> [source.yaml ...] [--json]\n  yarramate new projection <projection.yaml> --id <id> [--version <v>] [--title <text>] [--description <text>] [--document <id> ...] [--subject <ref> ...] [--kind <qualified-kind> ...] [--relationships <mode>]\n  yarramate status <workspace.yaml> [--json]\n  yarramate compile <source.yaml> [source.yaml ...]\n  yarramate context <projection.yaml> <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate context --subject <document-id>#<local-id> [--subject ...] <source.yaml> [source.yaml ...] [--budget <tokens>]\n  yarramate view <projection.yaml> <source.yaml> [source.yaml ...]\n  yarramate compare <from-state> <to-state> <source.yaml> [source.yaml ...]\n  yarramate evidence <evidence.yaml> <source.yaml> [source.yaml ...]\n  yarramate reconcile <workspace.yaml>\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/cli.js

@@ -5,17 +5,45 @@ import { isSeq, parseDocument } from 'yaml';
 import { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
 import { compareArchitectureStates } from './architecture-state.js';
 import { serializeSemanticGraph } from './graph.js';
-import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, } from './cli-support.js';
+import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, versionResult, } from './cli-support.js';
 import { runCheckCommand } from './check-command.js';
+import { runNewCommand } from './new-command.js';
+import { runStatusCommand } from './status-command.js';
 import { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
 import { loadWorkspaceManifest } from './workspace.js';
-import { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
+import { evaluateProjection, loadProjection, renderBudgetedContext, renderProjectionMarkdown, } from './projection.js';
+const extractBudget = (options) => {
+    const rest = [];
+    let budget;
+    for (let index = 0; index < options.length; index += 1) {
+        const option = options[index];
+        if (option === '--budget') {
+            const value = options[index + 1];
+            if (value === undefined ||
+                budget !== undefined ||
+                !/^[1-9][0-9]*$/.test(value)) {
+                return { ok: false };
+            }
+            budget = Number(value);
+            index += 1;
+            continue;
+        }
+        if (option !== undefined)
+            rest.push(option);
+    }
+    return budget === undefined ? { ok: true, rest } : { ok: true, budget, rest };
+};
 const runProjection = (options, cwd, output) => {
-    const [projectionPath, ...paths] = options;
+    const extracted = output === 'json' ? extractBudget(options) : { ok: true, rest: options };
+    if (!extracted.ok) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const budget = 'budget' in extracted ? extracted.budget : undefined;
+    const [projectionPath, ...paths] = extracted.rest;
     if (projectionPath === undefined ||
         paths.length === 0 ||
-        options.some((option) => option.startsWith('-'))) {
+        extracted.rest.some((option) => option.startsWith('-'))) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -53,7 +81,9 @@ const runProjection = (options, cwd, output) => {
         return {
             exitCode: 0,
             stdout: output === 'json'
-                ? `${JSON.stringify(result, null, 2)}\n`
+                ? budget === undefined
+                    ? `${JSON.stringify(result, null, 2)}\n`
+                    : renderBudgetedContext(result, budget)
                 : renderProjectionMarkdown(result),
             stderr: '',
         };
@@ -63,6 +93,95 @@ const runProjection = (options, cwd, output) => {
         return { exitCode: 2, stdout: '', stderr: `${message}\n` };
     }
 };
+const runAdHocContext = (options, cwd) => {
+    const extracted = extractBudget(options);
+    if (!extracted.ok) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const budget = 'budget' in extracted ? extracted.budget : undefined;
+    const subjects = [];
+    const paths = [];
+    for (let index = 0; index < extracted.rest.length; index += 1) {
+        const option = extracted.rest[index];
+        if (option === '--subject') {
+            const value = extracted.rest[index + 1];
+            if (value === undefined || value.startsWith('-')) {
+                return { exitCode: 2, stdout: '', stderr: usage };
+            }
+            subjects.push(value);
+            index += 1;
+            continue;
+        }
+        if (option === undefined || option.startsWith('-')) {
+            return { exitCode: 2, stdout: '', stderr: usage };
+        }
+        paths.push(option);
+    }
+    if (subjects.length === 0 || paths.length === 0) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const unqualified = subjects.filter((subject) => !subject.includes('#'));
+    if (unqualified.length > 0) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: 'Ad-hoc context subjects must be globally qualified as ' +
+                `"<document-id>#<local-id>": ${unqualified.join(', ')}\n`,
+        };
+    }
+    try {
+        const resolved = resolveCliWorkspaceSources(paths, cwd);
+        if (!resolved.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(resolved.diagnostics),
+                stderr: '',
+            };
+        }
+        const compilation = compileWorkspaceWithProfileContext(resolved.paths.map((path) => ({
+            path,
+            source: readFileSync(resolve(cwd, path), 'utf8'),
+        })));
+        if (!compilation.ok) {
+            return {
+                exitCode: 1,
+                stdout: diagnosticJson(compilation.diagnostics),
+                stderr: '',
+            };
+        }
+        const known = new Set(compilation.graph.subjects.map(({ id }) => id));
+        const unknown = subjects.filter((subject) => !known.has(subject));
+        if (unknown.length > 0) {
+            return {
+                exitCode: 1,
+                stdout: '',
+                stderr: `Unknown subject ${unknown.length === 1 ? 'identity' : 'identities'}: ` +
+                    `${unknown.join(', ')} (the compiled workspace declares ${known.size} subjects)\n`,
+            };
+        }
+        const result = evaluateProjection(compilation.graph, {
+            format: 'yarramate/projection/v1',
+            id: 'ad-hoc-context',
+            version: '0.0',
+            query: { subjects, relationships: 'connected' },
+            presentation: {
+                title: 'Ad-hoc context',
+                description: `Connected neighbourhood of ${subjects.join(', ')}`,
+            },
+        }, compilation.profileContext);
+        return {
+            exitCode: 0,
+            stdout: budget === undefined
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : renderBudgetedContext(result, budget),
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+};
 const runEvidence = (options, cwd) => {
     const [evidencePath, ...paths] = options;
     if (evidencePath === undefined ||
@@ -178,7 +297,7 @@ const runReconciliation = (options, cwd) => {
         }
         return {
             exitCode: 0,
-            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports), null, 2)}\n`,
+            stdout: `${JSON.stringify(reconcileEvidenceReports(loadedWorkspace.workspace.id, evaluation.reports, compilation.graph), null, 2)}\n`,
             stderr: '',
         };
     }
@@ -234,8 +353,10 @@ const runStateComparison = (options, cwd) => {
     }
 };
 const runInit = (options, cwd) => {
-    const target = options[0];
-    if (options.length !== 1 ||
+    const positional = options.filter((option) => option !== '--no-pointer');
+    const writePointer = positional.length === options.length;
+    const target = positional[0];
+    if (positional.length !== 1 ||
         target === undefined ||
         target.startsWith('-')) {
         return { exitCode: 2, stdout: '', stderr: usage };
@@ -270,9 +391,46 @@ const runInit = (options, cwd) => {
         'projections: []\n' +
         'adapterMappings: []\n' +
         'evidence: []\n', 'utf8');
+    const pointerMarker = '## YarraMate architecture';
+    const pointerBlock = `${pointerMarker}\n` +
+        '\n' +
+        'This repository declares its architecture as canonical, versioned\n' +
+        'YarraMate documents in `.yarramate/`. When prose documentation and the\n' +
+        'model disagree, the model is authoritative.\n' +
+        '\n' +
+        '- Orient first: `yarramate status .yarramate/workspace.yaml --json`\n' +
+        '- Validate changes: `yarramate check .yarramate/workspace.yaml --json`\n' +
+        '- Bounded task context: `yarramate context <projection.yaml> .yarramate/workspace.yaml`\n' +
+        '\n' +
+        'Author native documents only; never edit generated output.\n';
+    // Harnesses look in different files: AGENTS.md is the cross-harness
+    // convention, while Claude Code auto-loads CLAUDE.md only. Delivering to
+    // both is what makes the pointer reach an agent without instruction.
+    const pointerNotes = [];
+    if (writePointer) {
+        for (const pointerFile of ['AGENTS.md', 'CLAUDE.md']) {
+            const pointerPath = resolve(workspaceRoot, pointerFile);
+            const displayPointerPath = relative(cwd, pointerPath);
+            if (!existsSync(pointerPath)) {
+                writeFileSync(pointerPath, pointerBlock, 'utf8');
+                pointerNotes.push(`Created ${displayPointerPath} with the YarraMate pointer\n`);
+            }
+            else {
+                const existingPointer = readFileSync(pointerPath, 'utf8');
+                if (existingPointer.includes(pointerMarker)) {
+                    pointerNotes.push(`${displayPointerPath} already declares the YarraMate pointer\n`);
+                }
+                else {
+                    writeFileSync(pointerPath, `${existingPointer.replace(/\n*$/, '\n\n')}${pointerBlock}`, 'utf8');
+                    pointerNotes.push(`Extended ${displayPointerPath} with the YarraMate pointer\n`);
+                }
+            }
+        }
+    }
     return {
         exitCode: 0,
-        stdout: `Created ${displayPath} and ${displayManifestPath}\n`,
+        stdout: `Created ${displayPath} and ${displayManifestPath}\n` +
+            pointerNotes.join(''),
         stderr: '',
     };
 };
@@ -558,6 +716,9 @@ export function runCli(args, cwd = process.cwd()) {
     if (command === '--help' || command === '-h' || command === 'help') {
         return { exitCode: 0, stdout: usage, stderr: '' };
     }
+    if (command === '--version' || command === '-v') {
+        return versionResult('yarramate');
+    }
     if (command === 'init') {
         return runInit(options, cwd);
     }
@@ -571,7 +732,9 @@ export function runCli(args, cwd = process.cwd()) {
         return runCompile(options, cwd);
     }
     if (command === 'context') {
-        return runProjection(options, cwd, 'json');
+        return options.includes('--subject')
+            ? runAdHocContext(options, cwd)
+            : runProjection(options, cwd, 'json');
     }
     if (command === 'view') {
         return runProjection(options, cwd, 'markdown');
@@ -588,6 +751,12 @@ export function runCli(args, cwd = process.cwd()) {
     if (command === 'check') {
         return runCheckCommand(options, cwd);
     }
+    if (command === 'status') {
+        return runStatusCommand(options, cwd);
+    }
+    if (command === 'new') {
+        return runNewCommand(options, cwd);
+    }
     return { exitCode: 2, stdout: '', stderr: usage };
 }
 if (isMainModule(import.meta.url, process.argv[1])) {