yarramate 0.11.0 → 0.13.0

package/README.md

@@ -17,6 +17,20 @@ whose gaps are found deterministically.
 > YarraMate is pre-release software. Interfaces may evolve before the first
 > stable release.
 
+## Proven across harnesses
+
+The design bet is that the model — not the session — is the state, so any
+agent in any harness can resume the work cold. We tested that adversarially
+on a real product: a Claude Code session worked the design interview all
+day, then an OpenAI Codex session — no shared context, the tool never
+named — resumed it from a ten-line pointer file and the published CLI. It
+answered 63 open design questions, filed two genuine defect reports, and in
+a later session reported that the model "was not merely documentation" — it
+caught an approval-path regression before the release shipped.
+
+The full story, with every commit, PR, and release attached:
+[The model is the handover](docs/CASE-STUDY-CROSS-HARNESS.md).
+
 ## Why YarraMate?
 
 Architecture documents often drift away from implementation or become tied to
@@ -134,6 +148,7 @@ node dist/cli.js ask .yarramate/workspace.yaml
 node dist/cli.js ask .yarramate/workspace.yaml "free text about the model"
 node dist/cli.js ask .yarramate/workspace.yaml --subjects
 node dist/cli.js ask .yarramate/workspace.yaml --advise "a design question"
+node dist/cli.js ask .yarramate/workspace.yaml --where "compiler"
 node dist/cli.js check .yarramate/workspace.yaml --json
 node dist/cli.js reconcile .yarramate/workspace.yaml
 node dist/cli.js export graph .yarramate/workspace.yaml

package/dist/adapters/likec4-cli.js

@@ -712,6 +712,9 @@ export function runLikeC4Cli(args, cwd = process.cwd()) {
                 ? [
                     {
                         ...(view.id === undefined ? {} : { id: view.id }),
+                        ...(view.folder === undefined
+                            ? {}
+                            : { folder: view.folder }),
                         prepared,
                         ...(view.compare === undefined
                             ? {}

package/dist/adapters/likec4-project.d.ts

@@ -11,6 +11,7 @@ export interface LikeC4ProjectDefinition {
     readonly views: ReadonlyArray<{
         readonly id?: string;
         readonly projection: string;
+        readonly folder?: string;
         readonly compare?: {
             readonly from: string;
             readonly to: string;
@@ -40,6 +41,7 @@ export interface LikeC4Deployment {
 export declare const loadLikeC4ProjectDefinition: (source: WorkspaceSource) => import("../source-document.js").SourceDocumentResult<LikeC4ProjectDefinition>;
 export interface PreparedLikeC4ProjectView {
     readonly id?: string;
+    readonly folder?: string;
     readonly prepared: Extract<LikeC4PreparationResult, {
         readonly ok: true;
     }>;

package/dist/adapters/likec4-project.js

@@ -8,6 +8,15 @@ const Ajv2020 = Ajv2020Module.default;
 const validateLikeC4Project = new Ajv2020({ allErrors: true }).compile(likeC4ProjectSchema);
 export const loadLikeC4ProjectDefinition = (source) => loadSourceDocument(source, validateLikeC4Project, 'LikeC4 project');
 const quote = (value) => `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n')}'`;
+// A folder files the view in LikeC4's sidebar tree: the title becomes a
+// path ('Folder / Title') whose last segment is the displayed title (ADR
+// 0067). A view without a declared title still needs a title line to
+// carry the path, so the view id stands in as the leaf.
+const titleLines = (folder, title, viewId) => folder === undefined
+    ? title === undefined
+        ? []
+        : [`    title ${quote(title)}`]
+    : [`    title ${quote(`${folder} / ${title ?? viewId}`)}`];
 const unionProjection = (project, views) => ({
     format: 'yarramate/projection-result/v1',
     projection: `${project.id}@${project.version}`,
@@ -28,7 +37,7 @@ const unionProjection = (project, views) => ({
         ...new Map(views.flatMap(({ prepared }) => prepared.projection.claims.map((claim) => [claim.id, claim]))).values(),
     ].sort((left, right) => left.id.localeCompare(right.id)),
 });
-const viewBody = ({ id, prepared, dynamic, deployment, }, gitChange) => {
+const viewBody = ({ id, folder, prepared, dynamic, deployment, }, gitChange) => {
     const source = prepared.source;
     const startToken = '\nviews {\n';
     const start = source.indexOf(startToken);
@@ -58,9 +67,7 @@ const viewBody = ({ id, prepared, dynamic, deployment, }, gitChange) => {
         const viewId = id ?? prepared.projection.projection.split('@')[0];
         return [
             `  deployment view ${viewId} {`,
-            ...(prepared.projection.presentation?.title === undefined
-                ? []
-                : [`    title ${quote(prepared.projection.presentation.title)}`]),
+            ...titleLines(folder, prepared.projection.presentation?.title, viewId),
             ...(prepared.projection.presentation?.description === undefined
                 ? []
                 : [
@@ -105,9 +112,7 @@ const viewBody = ({ id, prepared, dynamic, deployment, }, gitChange) => {
         const viewId = id ?? prepared.projection.projection.split('@')[0];
         return [
             `  dynamic view ${viewId} {`,
-            ...(prepared.projection.presentation?.title === undefined
-                ? []
-                : [`    title ${quote(prepared.projection.presentation.title)}`]),
+            ...titleLines(folder, prepared.projection.presentation?.title, viewId),
             ...(prepared.projection.presentation?.description === undefined
                 ? []
                 : [
@@ -140,10 +145,17 @@ const viewBody = ({ id, prepared, dynamic, deployment, }, gitChange) => {
         ...relationshipRules,
         ...overlayRules,
     ].join('\n');
-    return source
+    const viewId = id ?? prepared.projection.projection.split('@')[0];
+    const body = source
         .slice(start + startToken.length, end)
-        .replace(/^  view [A-Za-z_][A-Za-z0-9_-]* \{/, `  view ${id ?? prepared.projection.projection.split('@')[0]} {`)
+        .replace(/^  view [A-Za-z_][A-Za-z0-9_-]* \{/, `  view ${viewId} {`)
         .replace('    include *', membershipRules);
+    if (folder === undefined)
+        return body;
+    const title = prepared.projection.presentation?.title;
+    return title === undefined
+        ? body.replace(`  view ${viewId} {`, `  view ${viewId} {\n${titleLines(folder, undefined, viewId).join('\n')}`)
+        : body.replace(`    title ${quote(title)}`, titleLines(folder, title, viewId).join('\n'));
 };
 const deploymentBody = ({ deployment, prepared, }) => {
     if (deployment === undefined)

package/dist/ask-command.js

@@ -8,7 +8,7 @@ import { deriveChangedSubjects } from './changed.js';
 import { runCheckCommand } from './check-command.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
-import { evaluateEvidenceWorkspace, loadEvidence } from './evidence.js';
+import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { evaluateCatalogue, loadQuestionCatalogue, renderInterrogationReport, } from './interrogate-command.js';
 import { buildNextSubjects, coverageClause, } from './next-command.js';
 import { conceptKinds, relationshipPolicies, } from './profile.js';
@@ -124,6 +124,7 @@ export function runAskCommand(options, cwd) {
     let open = false;
     let kinds = false;
     let advise = false;
+    let where = false;
     let compare;
     let changed;
     let budget;
@@ -157,6 +158,10 @@ export function runAskCommand(options, cwd) {
             advise = true;
             continue;
         }
+        if (option === '--where') {
+            where = true;
+            continue;
+        }
         if (option === '--compare') {
             const from = options[index + 1];
             const to = options[index + 2];
@@ -231,6 +236,12 @@ export function runAskCommand(options, cwd) {
         exclusiveModes > 1 ||
         (advise && exclusiveModes > 0) ||
         (advise && query.length === 0) ||
+        (where &&
+            (exclusiveModes > 0 ||
+                advise ||
+                changed !== undefined ||
+                budget !== undefined ||
+                query.length === 0)) ||
         (query.length > 0 && exclusiveModes > 0) ||
         (changed !== undefined &&
             (query.length > 0 || exclusiveModes > 0 || advise)) ||
@@ -638,7 +649,10 @@ export function runAskCommand(options, cwd) {
         // names a projection file is precise addressing; anything else runs
         // through free-text seeding, where exact subject ids win.
         const soleTerm = query.length === 1 ? query[0] : undefined;
-        const projectionCandidate = soleTerm !== undefined && !advise && existsSync(resolve(cwd, soleTerm))
+        const projectionCandidate = soleTerm !== undefined &&
+            !advise &&
+            !where &&
+            existsSync(resolve(cwd, soleTerm))
             ? resolve(cwd, soleTerm)
             : undefined;
         if (projectionCandidate !== undefined &&
@@ -672,6 +686,92 @@ export function runAskCommand(options, cwd) {
                     `List the roster: yarramate ask ${workspacePath} --subjects\n`,
             };
         }
+        // --where: evidence-backed pointing (ADR 0068). Verified locations for
+        // the matched subjects, an explicit list of matched-but-unobserved
+        // subjects, and a hand-off note for everything outside the model —
+        // authority follows epistemic status, so the routing is stated in the
+        // output rather than assumed by the reader.
+        if (where) {
+            const evidenceDocuments = [];
+            for (const path of workspace.evidence) {
+                const loaded = loadEvidence({
+                    path,
+                    source: readFileSync(resolve(cwd, path), 'utf8'),
+                });
+                if (!loaded.ok)
+                    return failed(loaded.diagnostics);
+                evidenceDocuments.push(loaded.evidence);
+            }
+            const subjectOf = (observation) => 'subject' in observation
+                ? observation.subject
+                : (observation.claim.split('~')[0] ?? observation.claim);
+            // Subject- and claim-level observations often share a locator; the
+            // pointer is the same either way, so identical entries collapse.
+            const entriesBySeed = resolution.seeds.map((seed) => ({
+                subject: seed,
+                observations: [
+                    ...new Map(evidenceDocuments
+                        .flatMap((document) => document.observations
+                        .filter((observation) => subjectOf(observation) === seed)
+                        .map((observation) => ({
+                        uri: observation.evidence.uri,
+                        result: observation.result,
+                        provider: document.provider,
+                        ...(observation.evidence.message === undefined
+                            ? {}
+                            : { message: observation.evidence.message }),
+                    })))
+                        .map((entry) => [
+                        `${entry.uri}${entry.result}${entry.provider}${entry.message ?? ''}`,
+                        entry,
+                    ])).values(),
+                ].sort((left, right) => left.uri.localeCompare(right.uri) ||
+                    left.result.localeCompare(right.result)),
+            }));
+            const located = entriesBySeed.filter(({ observations }) => observations.length > 0);
+            const unobserved = entriesBySeed
+                .filter(({ observations }) => observations.length === 0)
+                .map(({ subject }) => subject);
+            const note = workspace.evidence.length === 0
+                ? 'This workspace declares no evidence overlay, so no location is verified. For code locations, use your search tools; author evidence observations to make locations verifiable.'
+                : 'Locations above are verified by evidence overlays. Subjects listed as unobserved are modeled but unlocated. For code outside the model, use your search tools or a code index.';
+            const result = {
+                format: 'yarramate/ask-result/v1',
+                workspace: workspace.id,
+                mode: 'where',
+                addressing: resolution.addressing,
+                topic,
+                seeds: resolution.seeds,
+                matched: resolution.matched,
+                located,
+                coverage: { unobserved, note },
+            };
+            const lines = [
+                `Where: "${topic}" — ${plural(resolution.matched, 'concept')} matched` +
+                    (resolution.matched > resolution.seeds.length
+                        ? `, seeded from the top ${resolution.seeds.length}`
+                        : '') +
+                    `: ${resolution.seeds.join(', ')}`,
+                '',
+            ];
+            for (const entry of located) {
+                lines.push(`  ${entry.subject}`);
+                for (const observation of entry.observations) {
+                    lines.push(`    ${observation.result}  ${observation.uri}  (${observation.provider})`);
+                    if (observation.message !== undefined) {
+                        lines.push(`      ${observation.message}`);
+                    }
+                }
+            }
+            if (located.length === 0) {
+                lines.push('  no verified locations');
+            }
+            if (unobserved.length > 0) {
+                lines.push('', `  unobserved — modeled, no evidence: ${unobserved.join(', ')}`);
+            }
+            lines.push('', note);
+            return emit(result, `${lines.join('\n')}\n`);
+        }
         const evaluated = sliceProjection(graph, resolution.seeds, topic, compilation.profileContext);
         if (!advise) {
             const result = {

package/dist/cli-support.d.ts

@@ -7,7 +7,7 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 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 design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <document-id>#<local-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\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

@@ -23,7 +23,7 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <document-id>#<local-id>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <document-id>#<local-id> ... | <projection.yaml> [--budget <tokens>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <document-id>#<local-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml>\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/schema/yarramate-ask-result.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://yarrasys.dev/schema/yarramate-ask-result.schema.json",
   "title": "YarraMate ask result",
-  "description": "One envelope for every consumed-now read: orientation, roster, slice, advice, next, open questions, and state comparison, discriminated by mode.",
+  "description": "One envelope for every consumed-now read: orientation, roster, slice, advice, verified locations, next, open questions, and state comparison, discriminated by mode.",
   "type": "object",
   "required": [
     "format",
@@ -23,6 +23,7 @@
         "roster",
         "slice",
         "advice",
+        "where",
         "next",
         "open",
         "compare",
@@ -363,6 +364,119 @@
       },
       "additionalProperties": false
     },
+    {
+      "type": "object",
+      "required": [
+        "mode",
+        "addressing",
+        "topic",
+        "seeds",
+        "matched",
+        "located",
+        "coverage"
+      ],
+      "properties": {
+        "format": true,
+        "workspace": true,
+        "mode": {
+          "const": "where"
+        },
+        "addressing": {
+          "enum": [
+            "free-text",
+            "subjects"
+          ]
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1
+        },
+        "seeds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "matched": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "located": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "subject",
+              "observations"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "subject": {
+                "type": "string",
+                "minLength": 1
+              },
+              "observations": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "uri",
+                    "result",
+                    "provider"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "uri": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "result": {
+                      "enum": [
+                        "confirmed",
+                        "contradicted",
+                        "unknown",
+                        "not-observed"
+                      ]
+                    },
+                    "provider": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "message": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "coverage": {
+          "type": "object",
+          "required": [
+            "unobserved",
+            "note"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "unobserved": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "note": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    },
     {
       "type": "object",
       "required": [

package/schema/yarramate-likec4-project.schema.json

@@ -72,6 +72,11 @@
         "projection": {
           "$ref": "#/$defs/path"
         },
+        "folder": {
+          "type": "string",
+          "description": "Sidebar folder for the rendered view, emitted as a LikeC4 title path ('Folder / Title'). Nest with '/' separators; folders appear in the order their first view appears in the views list.",
+          "pattern": "^[^/]+(?:/[^/]+)*$"
+        },
         "compare": {
           "$ref": "#/$defs/comparison"
         },

package/skills/yarramate-architecture/SKILL.md

@@ -33,7 +33,10 @@ design questions, and the backlog — planned subjects in dependency
 order. `ask <workspace.yaml> --subjects` lists every concept;
 `ask <workspace.yaml> --kinds` lists the declarable vocabulary;
 `ask <workspace.yaml> "<free text>"` returns the model slice matching
-your words.
+your words; `ask <workspace.yaml> --where "<free text>"` returns the
+evidence-verified code locations of matching subjects — prefer those
+over searching when the subject is modeled, and use your own search
+tools beyond the coverage boundary the output states.
 
 - Existing implementation is the starting point: follow **Discover an
   existing project**.