octwin-cli 0.3.0 → 0.6.0

package/dist/lib/kb-index.js

@@ -0,0 +1,214 @@
+/**
+ * The three maps `octwin platform-kb pull` writes beside the reference.
+ *
+ * The KB is ~1.6 MB across ~200 files. Reading it whole costs more context than
+ * the pack being authored, so the pull ships navigation instead:
+ *
+ *   INDEX.md    — the corpus: which docs exist, which FAMILY each belongs to,
+ *                 how big it is, and the order to read the first six.
+ *   SYMBOLS.md  — a NAME → the file that defines it (see `kb-symbols.ts`).
+ *   OUTLINE.md  — every doc's headings WITH line numbers, so a heavy doc is read
+ *                 from the right offset instead of end to end.
+ *
+ * ## Why INDEX.md stopped listing every catalog entry
+ *
+ * It used to print a row per primitive, per builtin, per render intent — ~900
+ * rows, ~30 KB, read in full at the start of every session to answer a question
+ * that is almost always about ONE name. That job is `SYMBOLS.md`'s, and it is a
+ * grep rather than a read. What is left here is the part that genuinely needs
+ * reading once: the shape of the corpus.
+ *
+ * ## Degrading against an older platform
+ *
+ * This CLI talks to any platform version. `group`, `bytes` and `sections` arrived
+ * with the navigation work; a platform that predates them sends an index without
+ * them. Every renderer here falls back to the flat shape rather than printing an
+ * empty table — and `OUTLINE.md` is simply not written when no doc carries an
+ * outline, because an empty map is worse than an absent one.
+ */
+/** First sentence (or a hard clamp) of a possibly-long `describe` — a map needs
+ *  one scannable line per entry, not the whole contract.
+ *
+ *  Sentence detection ignores punctuation nested in brackets: primitive `describe`
+ *  text routinely inlines an envelope shape (`… { rows, total, …, refs? } …`) whose
+ *  `?` would otherwise cut the summary off mid-brace. */
+export function kbOneLiner(text, max = 160) {
+    if (typeof text !== 'string' || !text.trim())
+        return '';
+    const flat = text.replace(/\s+/g, ' ').trim();
+    let depth = 0;
+    let end = -1;
+    for (let i = 0; i < flat.length; i++) {
+        const ch = flat[i];
+        if (ch === '{' || ch === '(' || ch === '[')
+            depth++;
+        else if (ch === '}' || ch === ')' || ch === ']')
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && (ch === '.' || ch === '!' || ch === '?')) {
+            const next = flat[i + 1];
+            if (next === undefined || next === ' ') {
+                end = i + 1;
+                break;
+            }
+        }
+    }
+    const line = end >= 40 ? flat.slice(0, end) : flat;
+    return line.length > max ? line.slice(0, max - 1).trimEnd() + '…' : line;
+}
+/**
+ * What one doc costs to open.
+ *
+ * DERIVED from the published byte count, never declared. `craft-capabilities`
+ * used to carry this as a hand-typed table of four doc names, which is a fact
+ * stated twice — and the corpus is lopsided enough (3.7 KB to 71 KB) that
+ * getting it wrong costs an agent a five-figure token read on a hunch.
+ */
+export function kbWeight(bytes) {
+    if (!bytes)
+        return { label: '', kb: '' };
+    const kb = `${Math.round(bytes / 1024)} KB`;
+    if (bytes >= 30 * 1024)
+        return { label: 'heavy — search it', kb };
+    if (bytes >= 12 * 1024)
+        return { label: 'a sitting', kb };
+    return { label: 'one read', kb };
+}
+/** Display order of the doc families: the authoring on-ramp first, grammar last. */
+const GROUP_ORDER = ['craft', 'module-guide', 'reference'];
+const GROUP_HEADING = {
+    craft: {
+        title: 'Craft guides — how to build WELL',
+        blurb: 'Author altitude, opinionated, and where the traps are. Each is small enough to read whole. '
+            + 'Start here for any "how should I…" question.',
+    },
+    'module-guide': {
+        title: 'Module guides — one module end to end',
+        blurb: 'The deep companion to a declaration catalog. Reach for one when a craft guide has named the '
+            + 'module and you need everything it can do.',
+    },
+    reference: {
+        title: 'Reference — what EXISTS',
+        blurb: 'Grammar and contracts, pinned to platform source. Exhaustive rather than instructive: reach '
+            + 'for one when you need a rule no single catalog entry can give you.',
+    },
+};
+/**
+ * Build `INDEX.md` — the map an authoring agent reads FIRST, and the only one of
+ * the three meant to be read rather than searched.
+ */
+export function buildKbIndexMarkdown(bundle, catalogEntryCounts) {
+    const index = bundle.index ?? [];
+    const docs = index.filter(e => e.kind === 'doc');
+    const catalogs = index.filter(e => e.kind === 'catalog');
+    const grouped = docs.some(d => d.group);
+    const L = [];
+    L.push('# Octwin platform capability reference — INDEX');
+    L.push('');
+    L.push(`Reference version ${bundle.version ?? '?'} · content_hash \`${bundle.content_hash ?? '?'}\` · pulled ${bundle.generated_at ?? '?'}`);
+    L.push('');
+    L.push('**Everything the platform supports is here.** If a step, function, field, or render intent is');
+    L.push('NOT in this reference, it does not exist for a pure-YAML pack. Do not fill a gap from memory.');
+    L.push('');
+    L.push('Three maps sit beside the reference, and they answer different questions:');
+    L.push('');
+    L.push('| You have | Open |');
+    L.push('|---|---|');
+    L.push('| a question (*"how do I take a deposit?"*) | **this file** — pick the guide, then read it |');
+    L.push('| a name (`record_list`, `active_only`, `$coalesce`, `collect:`) | **`SYMBOLS.md`** — grep it; every name maps to its exact file |');
+    L.push('| a heavy doc and one subject inside it | **`OUTLINE.md`** — every heading with its line number; read from there |');
+    L.push('');
+    // The reading route, straight from the index — no second hand-maintained copy.
+    const route = docs.filter(d => d.read_order != null).sort((a, b) => a.read_order - b.read_order);
+    if (route.length) {
+        L.push('## Read in this order');
+        L.push('');
+        L.push('Before authoring anything. Everything else is reached on demand.');
+        L.push('');
+        for (const d of route) {
+            const w = kbWeight(d.bytes);
+            L.push(`${d.read_order}. \`${d.key}.md\`${w.kb ? ` *(${w.kb})*` : ''} — ${kbOneLiner(d.summary, 150)}`);
+        }
+        L.push('');
+    }
+    L.push('## Guides & reference docs');
+    L.push('');
+    const renderDocTable = (rows) => {
+        L.push('| Doc | Read it for | File | Size |');
+        L.push('|---|---|---|---|');
+        for (const d of rows) {
+            const w = kbWeight(d.bytes);
+            const size = w.kb ? `${w.kb} · ${w.label}` : '';
+            L.push(`| ${d.title ?? d.key} | ${kbOneLiner(d.summary).replace(/\|/g, '\\|')} | \`${d.key}.md\` | ${size} |`);
+        }
+        L.push('');
+    };
+    if (grouped) {
+        for (const g of GROUP_ORDER) {
+            const rows = docs.filter(d => d.group === g);
+            if (!rows.length)
+                continue;
+            const h = GROUP_HEADING[g];
+            L.push(`### ${h.title}`);
+            L.push('');
+            L.push(h.blurb);
+            L.push('');
+            renderDocTable(rows);
+        }
+        // Anything the platform grouped in a way this CLI does not know about still
+        // gets printed — an unknown family must never silently drop a doc.
+        const known = new Set(GROUP_ORDER);
+        const rest = docs.filter(d => !d.group || !known.has(d.group));
+        if (rest.length) {
+            L.push('### Other');
+            L.push('');
+            renderDocTable(rest);
+        }
+    }
+    else {
+        renderDocTable(docs);
+    }
+    L.push('## Catalogs — exact machine-readable schemas');
+    L.push('');
+    L.push('One file per entry. **Never read a whole catalog** — grep `SYMBOLS.md` for the name and open');
+    L.push('the single file it points at (a primitive is a ~600-token read).');
+    L.push('');
+    L.push('| Catalog | What is in it | Entries | Path |');
+    L.push('|---|---|---|---|');
+    for (const c of catalogs) {
+        const n = catalogEntryCounts.get(c.key) ?? 0;
+        const path = n ? `\`${c.key}/<name>.json\`` : `\`${c.key}.json\``;
+        L.push(`| ${c.title ?? c.key} | ${kbOneLiner(c.summary, 200).replace(/\|/g, '\\|')} | ${n || '—'} | ${path} |`);
+    }
+    L.push('');
+    return L.join('\n');
+}
+/**
+ * Build `OUTLINE.md`, or `null` when no doc published an outline (an older
+ * platform) — an empty map would read as "these docs have no sections".
+ */
+export function buildKbOutlineMarkdown(bundle) {
+    const docs = (bundle.index ?? []).filter(e => e.kind === 'doc' && e.sections?.length);
+    if (!docs.length)
+        return null;
+    const L = [];
+    L.push('# Octwin platform capability reference — OUTLINE');
+    L.push('');
+    L.push(`Every heading in every doc, with its line number. content_hash \`${bundle.content_hash ?? '?'}\`.`);
+    L.push('');
+    L.push('**For reading INTO a doc, not instead of one.** Find the section, then read that file from its');
+    L.push('line — `dsl.md` is ~18k tokens whole and ~900 for the one section you needed.');
+    L.push('');
+    // Heaviest first: the outline earns its keep on exactly those docs.
+    const ordered = [...docs].sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0));
+    for (const d of ordered) {
+        const w = kbWeight(d.bytes);
+        L.push(`## \`${d.key}.md\`${w.kb ? ` — ${w.kb}` : ''}`);
+        L.push('');
+        for (const s of d.sections) {
+            const indent = s.level >= 3 ? '  ' : '';
+            L.push(`${indent}- **L${s.line}** ${s.title}`);
+        }
+        L.push('');
+    }
+    return L.join('\n');
+}

package/dist/lib/kb-path.js

@@ -68,6 +68,23 @@ export function lookupKbSubdir(packDir, subdir, isUsable) {
     }
     return { state: 'ok', dir };
 }
+/**
+ * Is this filename one of the catalog's ENTRIES?
+ *
+ * An exploded catalog directory holds one `<entry>.json` per member — and, since
+ * 2026-08-09, may also hold `_catalog.json`: the envelope's catalog-LEVEL content,
+ * which the explode used to discard. `system-entities/_catalog.json` carries the
+ * reserved-key rules, which belong to the whole set and to no single entity.
+ *
+ * Every loader in this package iterates `*.json` over one of those directories, so
+ * without this guard `_catalog.json` is read as an entry: an entity named
+ * `_catalog` with no fields, a primitive with no `inputSchema`, a render intent
+ * with no `allowed_keys`. The `_` prefix is the convention; this is the one place
+ * that decides it.
+ */
+export function isEntryFile(name) {
+    return name.endsWith('.json') && !name.startsWith('_');
+}
 /** The line to print when a check could not run. Same wording for all three. */
 export function describeKbLookup(l, what) {
     return l.state === 'absent'

package/dist/lib/kb-symbols.js

@@ -0,0 +1,271 @@
+/**
+ * The symbol router — every addressable name in the platform, in one greppable
+ * file, next to the exact path that defines it.
+ *
+ * ## The gap this closes
+ *
+ * `INDEX.md` answers "what docs and catalogs exist". It does not answer the
+ * question an authoring agent actually has, which arrives as a bare NAME: a
+ * `do:` step in a flow it is editing, an argument in an error message, a YAML key
+ * a customer asked about. Today that name is resolved by opening `INDEX.md`
+ * (~8k tokens), guessing a catalog, and grepping — and names that are not entry
+ * names at all (`active_only`, `fits_minutes`, `title_field`, a port name, a node
+ * op-key) appear in NO index, only in prose spread across 38 docs.
+ *
+ * `SYMBOLS.md` is one line per name → the exact file. One grep, one answer, and
+ * a name that is absent from it does not exist — which is the closure rule the
+ * skill already states but had no procedure for.
+ *
+ * ## Why this lives in the CLI and not the platform
+ *
+ * Every row is DERIVED from catalogs the pull has already written to disk. There
+ * is nothing here the platform knows and the CLI does not, so publishing it as a
+ * ninth catalog would have grown the bundle (and moved `content_hash`) to ship a
+ * pure function of the other eight.
+ *
+ * The extractors DO encode a little shape knowledge — that a primitive's args
+ * live under `inputSchema.properties`, that an intent's fields are `allowed_keys`.
+ * That is the same coupling `args-check.ts` and `render-check.ts` already carry,
+ * and it is handled the same way: every extractor is individually defensive and
+ * returns NOTHING for a payload it does not recognise. A catalog whose shape
+ * moves loses its rows from the router; it never breaks the pull.
+ */
+const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : null;
+const keysOf = (v) => Object.keys(obj(v) ?? {});
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+/** Clamp a summary to one scannable line — a table cell, not a paragraph. */
+function line(text, max = 110) {
+    const s = str(text);
+    if (!s)
+        return undefined;
+    const flat = s.replace(/\s+/g, ' ');
+    return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
+}
+const EXTRACTORS = {
+    primitives(entry, file) {
+        const v = obj(entry.value);
+        if (!v)
+            return [];
+        const out = [{ symbol: entry.name, kind: 'primitive', file, summary: line(entry.summary) }];
+        // Arguments — the class of name that used to appear in no index at all. An
+        // author reading `args: { order: … }` in their own flow has no other way to
+        // learn the argument is called `sort`.
+        for (const arg of keysOf(obj(v.inputSchema)?.properties)) {
+            out.push({ symbol: `${entry.name}.${arg}`, kind: 'primitive-arg', owner: entry.name, file });
+        }
+        // Output ports — what a `do:` node's `outputs:` switch may name.
+        for (const port of keysOf(v.portSchemas)) {
+            out.push({ symbol: `${entry.name}:${port}`, kind: 'primitive-port', owner: entry.name, file });
+        }
+        return out;
+    },
+    'render-intents'(entry, file) {
+        const v = obj(entry.value);
+        if (!v)
+            return [];
+        const out = [{ symbol: entry.name, kind: 'render-intent', file, summary: line(entry.summary) }];
+        const allowed = Array.isArray(v.allowed_keys) ? v.allowed_keys : keysOf(v.fields);
+        for (const k of allowed) {
+            if (typeof k !== 'string')
+                continue;
+            const required = obj(obj(v.fields)?.[k])?.required === true;
+            out.push({
+                symbol: `${entry.name}.${k}`, kind: 'render-intent-field', owner: entry.name, file,
+                summary: required ? 'required' : undefined,
+            });
+        }
+        return out;
+    },
+    builtins(entry, file) {
+        const v = obj(entry.value);
+        // `$` is how an author writes it, and how they will grep for it.
+        return [{
+                symbol: `$${entry.name}`, kind: 'builtin', file,
+                summary: line(str(v?.signature) ?? entry.summary),
+            }];
+    },
+    templates(entry, file) {
+        const v = obj(entry.value);
+        const out = [{ symbol: entry.name, kind: 'template', file, summary: line(entry.summary) }];
+        const params = Array.isArray(v?.params) ? v.params : [];
+        for (const p of params) {
+            const name = str(obj(p)?.name);
+            if (!name)
+                continue;
+            out.push({
+                symbol: `${entry.name}.${name}`, kind: 'template-param', owner: entry.name, file,
+                summary: obj(p)?.required === true ? 'required' : undefined,
+            });
+        }
+        return out;
+    },
+    declarations(entry, file) {
+        const v = obj(entry.value);
+        if (!v)
+            return [];
+        // The symbol is the FILE the author writes (`xrm.yaml`), not the catalog key.
+        const declFile = str(v.file) ?? `${entry.name}.yaml`;
+        const out = [{ symbol: declFile, kind: 'declaration', file, summary: line(entry.summary) }];
+        const schema = obj(v.schema);
+        const defs = obj(schema?.$defs) ?? {};
+        /** Follow one `$ref` into `$defs` — deeper chains are not worth the router's weight. */
+        const deref = (node) => {
+            const n = obj(node);
+            if (!n)
+                return null;
+            const ref = str(n.$ref);
+            if (!ref)
+                return n;
+            const name = ref.split('/').pop();
+            return name ? obj(defs[name]) : null;
+        };
+        for (const top of keysOf(schema?.properties)) {
+            out.push({ symbol: `${declFile}:${top}`, kind: 'declaration-key', owner: declFile, file });
+            // One level deeper, through a `$ref` and through an array's `items` — that
+            // is where the keys authors actually mistype live (`entities.*.title_field`).
+            const node = deref(obj(schema?.properties)?.[top]);
+            const inner = deref(node?.items) ?? deref(obj(node?.additionalProperties)) ?? node;
+            for (const sub of keysOf(inner?.properties)) {
+                out.push({ symbol: `${declFile}:${top}.${sub}`, kind: 'declaration-key', owner: declFile, file });
+            }
+        }
+        return out;
+    },
+    'system-entities'(entry, file) {
+        const v = obj(entry.value);
+        if (!v)
+            return [];
+        const out = [{
+                symbol: entry.name, kind: 'system-entity', file,
+                summary: line(str(v.description) ?? entry.summary) ?? 'reserved entity key',
+            }];
+        for (const f of keysOf(v.fields)) {
+            out.push({ symbol: `${entry.name}.${f}`, kind: 'system-entity-field', owner: entry.name, file });
+        }
+        return out;
+    },
+    channels(entry, file) {
+        const v = obj(entry.value);
+        const out = [{ symbol: entry.name, kind: 'channel', file, summary: line(entry.summary) }];
+        for (const cap of keysOf(v?.caps)) {
+            out.push({ symbol: `${entry.name}.$caps.${cap}`, kind: 'channel-cap', owner: entry.name, file });
+        }
+        return out;
+    },
+};
+/**
+ * Node op-keys from the flow JSON Schema — the one catalog that is a single
+ * document rather than a list, and the one holding names (`collect`, `dispatch`,
+ * `foreach`) that appear in no entry file anywhere.
+ *
+ * Each `FlowNode.anyOf` alternative is one node kind: its `required[0]` is the
+ * op-key, its sibling `properties` are that node's modifiers.
+ */
+export function flowSchemaSymbols(schema, file) {
+    const alts = obj(obj(obj(schema)?.definitions)?.FlowNode)?.anyOf;
+    if (!Array.isArray(alts))
+        return [];
+    const out = [];
+    for (const alt of alts) {
+        const a = obj(alt);
+        const req = Array.isArray(a?.required) ? a.required : [];
+        const op = str(req[0]);
+        if (!op)
+            continue;
+        out.push({ symbol: `${op}:`, kind: 'node-op', file, summary: line(str(a?.description)) });
+        for (const mod of keysOf(a?.properties)) {
+            if (mod === op)
+                continue;
+            out.push({ symbol: `${op}:.${mod}`, kind: 'node-modifier', owner: `${op}:`, file });
+        }
+    }
+    return out;
+}
+/**
+ * Link a symbol to the prose section that explains it.
+ *
+ * Matching is deliberately narrow: a section counts only when the symbol appears
+ * **in its heading**, backticked. Scanning bodies would attach half the corpus to
+ * `record_list`, and a router that points everywhere points nowhere. A symbol
+ * with no heading-level home simply carries no link — the entry file is still
+ * exact, which is what the row is for.
+ */
+export function linkExplainers(symbols, docSections) {
+    // symbol → `<docKey>#<anchor>`, first match wins in index order.
+    const byHeading = new Map();
+    for (const [docKey, sections] of docSections) {
+        for (const s of sections) {
+            for (const m of s.title.matchAll(/`([^`]+)`/g)) {
+                const name = m[1].trim().replace(/:$/, '').replace(/^\$/, '$');
+                if (!name || byHeading.has(name))
+                    continue;
+                byHeading.set(name, `${docKey}#${s.anchor}`);
+            }
+        }
+    }
+    for (const sym of symbols) {
+        if (sym.owner)
+            continue; // members inherit their owner's file; a link would be noise
+        const hit = byHeading.get(sym.symbol) ?? byHeading.get(sym.symbol.replace(/:$/, ''));
+        if (hit)
+            sym.explains = hit;
+    }
+}
+/**
+ * Build the full symbol table from the catalogs the pull enumerated.
+ *
+ * `exploded` is catalogKey → entries; `files` maps an entry back to the path it
+ * was written to. `flat` carries the catalogs that were NOT exploded, so the flow
+ * schema still contributes.
+ */
+export function buildSymbols(exploded, fileFor, flat) {
+    const out = [];
+    for (const [catalogKey, entries] of exploded) {
+        const extract = EXTRACTORS[catalogKey];
+        if (!extract)
+            continue; // a catalog this CLI has no extractor for: skipped, never guessed at
+        for (const entry of entries) {
+            try {
+                out.push(...extract(entry, fileFor(catalogKey, entry.name)));
+            }
+            catch { /* one malformed entry must not cost the whole router */ }
+        }
+    }
+    if (flat['flow-schema'] != null) {
+        out.push(...flowSchemaSymbols(flat['flow-schema'], 'flow-schema.json'));
+    }
+    // Stable, and sorted the way a human scans: by symbol, case-insensitively.
+    out.sort((a, b) => a.symbol.toLowerCase().localeCompare(b.symbol.toLowerCase()) || a.symbol.localeCompare(b.symbol));
+    return out;
+}
+/** Render `SYMBOLS.md` — a grep target first, a readable table second. */
+export function renderSymbolsMarkdown(symbols, contentHash) {
+    const byKind = new Map();
+    for (const s of symbols)
+        byKind.set(s.kind, (byKind.get(s.kind) ?? 0) + 1);
+    const L = [];
+    L.push('# Octwin platform capability reference — SYMBOLS');
+    L.push('');
+    L.push(`Every addressable name in the platform, and the exact file that defines it. content_hash \`${contentHash ?? '?'}\`.`);
+    L.push('');
+    L.push('**Grep this file; do not read it.** Search the name you have — a `do:` step, an argument from an');
+    L.push('error, a YAML key, a `$function`, a node op-key — and open the file in its row.');
+    L.push('');
+    L.push('**A name that is not in this table does not exist for a pure-YAML pack.** Not "is undocumented":');
+    L.push('does not exist. Do not fill the gap from memory.');
+    L.push('');
+    L.push('Naming: `owner.member` is an argument or field of `owner`; `owner:port` is an output port;');
+    L.push('`file.yaml:key` is a key in a declaration file; `op:` is a flow node op-key.');
+    L.push('');
+    L.push(`${symbols.length} symbols — ${[...byKind].sort().map(([k, n]) => `${n} ${k}`).join(' · ')}`);
+    L.push('');
+    L.push('| Symbol | Kind | Defined in | Explained in |');
+    L.push('|---|---|---|---|');
+    for (const s of symbols) {
+        const cell = (v) => v.replace(/\|/g, '\\|');
+        const note = s.summary ? ` — ${cell(s.summary)}` : '';
+        L.push(`| \`${cell(s.symbol)}\` | ${s.kind}${note} | \`${s.file}\` | ${s.explains ? `\`${s.explains}\`` : ''} |`);
+    }
+    L.push('');
+    return L.join('\n');
+}

package/dist/lib/render-check.js

@@ -22,7 +22,7 @@
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { lookupKbSubdir } from './kb-path.js';
+import { lookupKbSubdir, isEntryFile } from './kb-path.js';
 /**
  * Load `render_intent -> allowed_keys` from the pulled KB.
  *
@@ -30,14 +30,14 @@ import { lookupKbSubdir } from './kb-path.js';
  * "checked, nothing wrong" from "could not check". See `kb-path.ts`.
  */
 export function loadAllowedRenderKeys(packDir) {
-    const lookup = lookupKbSubdir(packDir, 'render-intents', dir => readdirSync(dir).some(f => f.endsWith('.json')));
+    const lookup = lookupKbSubdir(packDir, 'render-intents', dir => readdirSync(dir).some(isEntryFile));
     if (lookup.state !== 'ok')
         return { lookup, keys: null };
     const dir = lookup.dir;
     const out = new Map();
     try {
         for (const file of readdirSync(dir)) {
-            if (!file.endsWith('.json'))
+            if (!isEntryFile(file))
                 continue;
             const entry = JSON.parse(readFileSync(join(dir, file), 'utf8'));
             if (entry.render_intent && Array.isArray(entry.allowed_keys)) {
@@ -61,9 +61,9 @@ export function loadAllowedRenderKeys(packDir) {
  */
 export function findRenderKeyViolations(doc, file, allowedByIntent) {
     const findings = [];
-    const walk = (node) => {
+    const walk = (node, path) => {
         if (Array.isArray(node)) {
-            node.forEach(walk);
+            node.forEach((v, i) => walk(v, [...path, i]));
             return;
         }
         if (!node || typeof node !== 'object')
@@ -72,26 +72,27 @@ export function findRenderKeyViolations(doc, file, allowedByIntent) {
         if (typeof obj.render_intent === 'string') {
             const allowed = allowedByIntent.get(obj.render_intent);
             if (!allowed) {
-                findings.push({ file, intent: obj.render_intent, keys: [], allowed: [...allowedByIntent.keys()] });
+                findings.push({ file, path: [...path], intent: obj.render_intent, keys: [], allowed: [...allowedByIntent.keys()] });
             }
             else {
                 const bad = Object.keys(obj).filter(k => !allowed.includes(k));
                 if (bad.length)
-                    findings.push({ file, intent: obj.render_intent, keys: bad, allowed });
+                    findings.push({ file, path: [...path], intent: obj.render_intent, keys: bad, allowed });
             }
         }
-        for (const v of Object.values(obj))
-            walk(v);
+        for (const [k, v] of Object.entries(obj))
+            walk(v, [...path, k]);
     };
-    walk(doc);
+    walk(doc, []);
     return findings;
 }
 /** One-line human message per finding. */
 export function describeRenderFinding(f) {
+    const at = f.line != null ? `:${f.line}` : (f.path.length ? ` (${f.path.join('.')})` : '');
     if (f.keys.length === 0) {
-        return `${f.file}: unknown render_intent '${f.intent}' — known intents: ${f.allowed.join(', ')}`;
+        return `${f.file}${at}: unknown render_intent '${f.intent}' — known intents: ${f.allowed.join(', ')}`;
     }
     const plural = f.keys.length === 1 ? 'field' : 'fields';
-    return `${f.file}: render_intent '${f.intent}' has unknown ${plural} ${f.keys.map(k => `'${k}'`).join(', ')} ` +
+    return `${f.file}${at}: render_intent '${f.intent}' has unknown ${plural} ${f.keys.map(k => `'${k}'`).join(', ')} ` +
         `— silently dropped at render. Allowed: ${f.allowed.join(', ')}`;
 }