yarramate 0.3.3 → 0.4.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/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,165 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline';
+import { isMainModule } 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: '0.1' },
+            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])) {
+    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,7 @@ 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 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 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

@@ -14,7 +14,7 @@ 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 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 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

@@ -7,15 +7,43 @@ import { compareArchitectureStates } from './architecture-state.js';
 import { serializeSemanticGraph } from './graph.js';
 import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, } 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 ||
@@ -270,9 +389,38 @@ const runInit = (options, cwd) => {
         'projections: []\n' +
         'adapterMappings: []\n' +
         'evidence: []\n', 'utf8');
+    const agentsPath = resolve(workspaceRoot, 'AGENTS.md');
+    const displayAgentsPath = relative(cwd, agentsPath);
+    const agentsMarker = '## YarraMate architecture';
+    const agentsBlock = `${agentsMarker}\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';
+    let agentsNote;
+    if (!existsSync(agentsPath)) {
+        writeFileSync(agentsPath, agentsBlock, 'utf8');
+        agentsNote = `Created ${displayAgentsPath} with the YarraMate pointer\n`;
+    }
+    else {
+        const existingAgents = readFileSync(agentsPath, 'utf8');
+        if (existingAgents.includes(agentsMarker)) {
+            agentsNote = `${displayAgentsPath} already declares the YarraMate pointer\n`;
+        }
+        else {
+            writeFileSync(agentsPath, `${existingAgents.replace(/\n*$/, '\n\n')}${agentsBlock}`, 'utf8');
+            agentsNote = `Extended ${displayAgentsPath} with the YarraMate pointer\n`;
+        }
+    }
     return {
         exitCode: 0,
-        stdout: `Created ${displayPath} and ${displayManifestPath}\n`,
+        stdout: `Created ${displayPath} and ${displayManifestPath}\n` + agentsNote,
         stderr: '',
     };
 };
@@ -571,7 +719,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 +738,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])) {

package/dist/compiler.js

@@ -1,6 +1,7 @@
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { LineCounter, parseDocument } from 'yaml';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
+import { closestCandidate, describeSchemaViolation, } from './source-document.js';
 import documentSchema from '../schema/yarramate-document.schema.json' with {
     type: 'json'
 };
@@ -112,7 +113,7 @@ function compileWorkspaceResolved(sources) {
                     code: 'YM201',
                     message: property
                         ? `Property "${property}" is not allowed`
-                        : `Profile schema violation: ${error.message ?? error.keyword}`,
+                        : `Profile schema violation: ${describeSchemaViolation(error)}`,
                     path: input.path,
                     pointer,
                     line: position.line,
@@ -335,7 +336,7 @@ function compileWorkspaceResolved(sources) {
                         code: 'YM201',
                         message: property
                             ? `Property "${property}" is not allowed`
-                            : `Document schema violation: ${error.message ?? error.keyword}`,
+                            : `Document schema violation: ${describeSchemaViolation(error)}`,
                         path: input.path,
                         pointer,
                         line: source.line,
@@ -536,7 +537,12 @@ function compileWorkspaceResolved(sources) {
                 diagnostics.push({
                     severity: 'error',
                     code: 'YM401',
-                    message: `Unknown concept kind "${concept.kind}" in profile "${value.profile}"`,
+                    message: `Unknown concept kind "${concept.kind}" in profile "${value.profile}"${(() => {
+                        const suggestion = closestCandidate(concept.kind, selectedProfile.conceptKinds.keys());
+                        return suggestion === undefined
+                            ? ''
+                            : `; did you mean "${suggestion}"?`;
+                    })()}`,
                     path: input.path,
                     pointer,
                     line: source.line,
@@ -742,7 +748,12 @@ function compileWorkspaceResolved(sources) {
                 diagnostics.push({
                     severity: 'error',
                     code: 'YM402',
-                    message: `Unknown relationship kind "${relationship.kind}" in profile "${value.profile}"`,
+                    message: `Unknown relationship kind "${relationship.kind}" in profile "${value.profile}"${(() => {
+                        const suggestion = closestCandidate(relationship.kind, selectedProfile.relationshipKinds.keys());
+                        return suggestion === undefined
+                            ? ''
+                            : `; did you mean "${suggestion}"?`;
+                    })()}`,
                     path: input.path,
                     pointer,
                     line: source.line,

package/dist/new-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runNewCommand(options: readonly string[], cwd: string): CliResult;

package/dist/new-command.js

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { humanDiagnostics, usage } from './cli-support.js';
+import { loadProjection } from './projection.js';
+const singleValueFlags = new Set([
+    '--id',
+    '--version',
+    '--title',
+    '--description',
+    '--relationships',
+]);
+const repeatableFlags = new Set(['--document', '--subject', '--kind']);
+const yamlText = (value) => /^[A-Za-z0-9][A-Za-z0-9 ._/@#-]*$/.test(value)
+    ? value
+    : JSON.stringify(value);
+export function runNewCommand(options, cwd) {
+    const [family, target, ...flags] = options;
+    if (family !== 'projection' || target === undefined || target.startsWith('-')) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const single = new Map();
+    const repeated = new Map();
+    for (let index = 0; index < flags.length; index += 2) {
+        const flag = flags[index];
+        const value = flags[index + 1];
+        if (flag === undefined ||
+            value === undefined ||
+            value.startsWith('--') ||
+            (!singleValueFlags.has(flag) && !repeatableFlags.has(flag))) {
+            return { exitCode: 2, stdout: '', stderr: usage };
+        }
+        if (singleValueFlags.has(flag)) {
+            if (single.has(flag)) {
+                return { exitCode: 2, stdout: '', stderr: usage };
+            }
+            single.set(flag, value);
+        }
+        else {
+            repeated.set(flag, [...(repeated.get(flag) ?? []), value]);
+        }
+    }
+    const id = single.get('--id');
+    if (id === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const documents = repeated.get('--document');
+    const subjects = repeated.get('--subject');
+    const kinds = repeated.get('--kind');
+    if (documents === undefined && subjects === undefined && kinds === undefined) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: 'new projection requires at least one selector: --document, --subject, or --kind\n',
+        };
+    }
+    const targetPath = resolve(cwd, target);
+    if (existsSync(targetPath)) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: `${target} already exists; nothing was changed\n`,
+        };
+    }
+    const lines = [
+        'format: yarramate/projection/v1',
+        `id: ${yamlText(id)}`,
+        `version: "${single.get('--version') ?? '1.0'}"`,
+        'query:',
+    ];
+    const list = (key, values) => {
+        if (values === undefined)
+            return;
+        lines.push(`  ${key}:`);
+        for (const value of values)
+            lines.push(`    - ${yamlText(value)}`);
+    };
+    list('subjects', subjects);
+    list('documents', documents);
+    list('kinds', kinds);
+    const relationships = single.get('--relationships');
+    if (relationships !== undefined) {
+        lines.push(`  relationships: ${yamlText(relationships)}`);
+    }
+    const title = single.get('--title');
+    const description = single.get('--description');
+    if (title !== undefined || description !== undefined) {
+        lines.push('presentation:');
+        if (title !== undefined)
+            lines.push(`  title: ${yamlText(title)}`);
+        if (description !== undefined) {
+            lines.push(`  description: ${yamlText(description)}`);
+        }
+    }
+    const source = `${lines.join('\n')}\n`;
+    const loaded = loadProjection({ path: target, source });
+    if (!loaded.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(loaded.diagnostics),
+        };
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, source, 'utf8');
+    return {
+        exitCode: 0,
+        stdout: `Created ${target} (${loaded.projection.id}@${loaded.projection.version})\n` +
+            'Include it in the workspace manifest projections list if no glob already covers it\n',
+        stderr: '',
+    };
+}

package/dist/projection.d.ts

@@ -40,3 +40,4 @@ export type ProjectionLoadResult = {
 export declare function loadProjection(source: WorkspaceSource): ProjectionLoadResult;
 export declare function evaluateProjection(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): ProjectionResult;
 export declare function renderProjectionMarkdown(result: ProjectionResult): string;
+export declare function renderBudgetedContext(result: ProjectionResult, budgetTokens: number): string;