@clay-design-system/kb 0.0.0-stage → 0.14.0

package/dist/core/query.js

@@ -0,0 +1,637 @@
+import { markLine, markServed, noteSection, seenBody, seenLine } from './memory.js';
+import { STAGES, estimateTokens } from './model.js';
+import { layoutLine, limitShort, route as runRoute } from './route.js';
+import { search as runSearch } from './search.js';
+export const tokensOf = estimateTokens;
+export const tight = (body) => body.replace(/\n[ \t]*\n+/g, '\n').trim();
+/* ── get ───────────────────────────────────────────────────────────────────────────────────── */
+/** Full units. An id ending in `*` expands to every id with that prefix (max 25). */
+export function get(ctx, ids, opts = {}) {
+    const units = [];
+    const missing = [];
+    const repeated = [];
+    for (const raw of ids) {
+        if (raw.endsWith('*')) {
+            const pre = raw.slice(0, -1);
+            const hits = ctx.kb.units.filter((u) => u.id.startsWith(pre)).slice(0, 25);
+            if (!hits.length)
+                missing.push(raw);
+            units.push(...hits);
+            continue;
+        }
+        const u = ctx.byId.get(raw);
+        if (u)
+            units.push(u);
+        else
+            missing.push(raw);
+    }
+    // K8 session: a unit whose body this build was already served comes back as one line (`--full` re-prints it).
+    const fresh = units.filter((u) => {
+        if (!opts.full && seenBody(opts.session, u.id)) {
+            repeated.push(u.id);
+            return false;
+        }
+        return true;
+    });
+    for (const u of fresh)
+        markServed(opts.session, u.id, 'get');
+    const text = [
+        ...(repeated.length
+            ? [
+                `Served earlier in this session (\`--full\` to re-print): ${repeated.map((id) => `\`${id}\` (${opts.session.served[id]})`).join(' · ')}`,
+            ]
+            : []),
+        ...fresh.map((u) => {
+            const meta = [
+                u.kind,
+                u.authority,
+                u.severity,
+                u.modes?.length ? `mode ${u.modes.join('/')}` : '',
+                `stages ${u.stages.join(', ') || '—'}`,
+            ]
+                .filter(Boolean)
+                .join(' · ');
+            const rel = Object.entries(u.relations ?? {})
+                .filter(([, v]) => v?.length)
+                .map(([k, v]) => `${k}: ${v.join(', ')}`)
+                .join(' · ');
+            // K8: one header line (id · meta · relations); the source path only with --full (agents never open it).
+            return `## ${u.id} · _${meta}${rel ? ` · ${rel}` : ''}_${opts.full ? ` · source \`${u.source.path}${u.source.anchor ? `#${u.source.anchor}` : ''}\`` : ''}\n${opts.full ? tight(u.body) : clipUnions(ctx, tight(u.body))}`;
+        }),
+        ...(missing.length ? [`Not found: ${missing.join(', ')} (try \`clay search\`).`] : []),
+    ].join('\n');
+    return { text: `${text}\n`, data: { units, missing, repeated } };
+}
+/** Members a string-literal union keeps in `get` output before it is clipped (K11: `component.Icon` printed ~10 KB). */
+const UNION_KEEP = 8;
+/**
+ * K11: a long string-literal union in a code span (`'activity' \| 'airplay' \| …`, 597 icon names) is clipped to its
+ * first few members plus the count; `get --full` prints it whole. When the values are icon names, the line says how
+ * to look one up instead.
+ */
+export function clipUnions(ctx, body) {
+    const notes = new Set();
+    const out = body.replace(/`('[^'`]*'(?:\s*\\?\|\s*'[^'`]*')+)`/g, (whole, union) => {
+        const vals = [...union.matchAll(/'([^']*)'/g)].map((m) => m[1]);
+        if (vals.length <= UNION_KEEP * 2)
+            return whole;
+        const sep = union.includes('\\|') ? ' \\| ' : ' | ';
+        if (vals.slice(0, 3).every((v) => ctx.byId.has(`asset.icon.${v}`)))
+            notes.add(`Icon names: \`clay search "<what it shows> icon" --kind asset\` (or \`clay get asset.icon.<name>\`).`);
+        return `\`${vals
+            .slice(0, UNION_KEEP)
+            .map((v) => `'${v}'`)
+            .join(sep)}${sep}…\` (${vals.length} values; \`--full\` prints all)`;
+    });
+    return notes.size ? `${out}\n${[...notes].join('\n')}` : out;
+}
+/* ── search ────────────────────────────────────────────────────────────────────────────────── */
+/** One search hit; folded near-duplicate assets (K11) are named after it, at most two. */
+function hitLine(h) {
+    const al = h.aliases ?? [];
+    const also = al.length
+        ? ` (also \`${al.slice(0, 2).join('`, `')}\`${al.length > 2 ? ` +${al.length - 2} more` : ''})`
+        : '';
+    return `\`${h.id}\` (${h.kind}, ${h.authority}, ${h.score.toFixed(1)}) — ${h.summary}${also}`;
+}
+/**
+ * `clay search --each a,b,c` (K11): one search per term, the best hit(s) for each — resolves several brand / icon /
+ * section names in one call (`--limit n` per term, default 1).
+ */
+export function searchEach(ctx, termsList, opts = {}) {
+    const results = termsList.map((term) => ({
+        term,
+        hits: runSearch(ctx.kb, ctx.index, term, { ...opts, k: opts.k ?? 1 }),
+    }));
+    const text = results
+        .map(({ term, hits }) => hits.length === 1
+        ? `- ${term} → ${hitLine(hits[0])}`
+        : hits.length
+            ? [`- ${term}:`, ...hits.map((h, i) => `  ${i + 1}. ${hitLine(h)}`)].join('\n')
+            : `- ${term} → no match`)
+        .join('\n');
+    return { text: `${text}\n`, data: { results } };
+}
+export function search(ctx, query, opts = {}) {
+    const hits = runSearch(ctx.kb, ctx.index, query, opts);
+    const emailHint = !opts.scope?.length &&
+        /\b(?:e-?mails?|mjml|braze|preheader|subject lines?|newsletter|mj-[a-z]+)\b/i.test(query);
+    const text = (hits.length ? hits.map((h, i) => `${i + 1}. ${hitLine(h)}`).join('\n') : 'No units match.') +
+        (emailHint
+            ? '\n(Email knowledge is a separate scope: add `--scope email`, or `--scope all`.)'
+            : '');
+    return { text: `${text}\n`, data: { hits } };
+}
+/* ── route ─────────────────────────────────────────────────────────────────────────────────── */
+/**
+ * `--session` (K8): units this build was already served are named, not repeated; Watch drops lines it saw and units
+ * about sections it never looked at. `--since <stage>`: the same dedupe without a session file — the routes of
+ * `<stage>` up to the stage before this one (same skill and mode) count as served.
+ */
+export function route(ctx, opts) {
+    const brief = opts.brief;
+    if (!STAGES.includes(opts.stage))
+        throw new Error(`route: unknown stage "${opts.stage}" (one of ${STAGES.join(', ')})`);
+    const sess = opts.session;
+    const seen = {
+        bodies: new Set(Object.keys(sess?.served ?? {})),
+        lines: new Set(Object.keys(sess?.lines ?? {})),
+    };
+    if (opts.since) {
+        if (!STAGES.includes(opts.since))
+            throw new Error(`route: unknown --since stage "${opts.since}"`);
+        for (const st of STAGES.slice(STAGES.indexOf(opts.since), STAGES.indexOf(opts.stage))) {
+            const prev = runRoute(ctx.kb, ctx.index, {
+                skill: opts.skill,
+                mode: opts.mode,
+                stage: st,
+                brief: st === 'mapping' || st === 'structure' ? brief : undefined,
+            });
+            for (const u of prev.units)
+                (u.inlined === 'body' ? seen.bodies : seen.lines).add(u.id);
+        }
+    }
+    const r = runRoute(ctx.kb, ctx.index, {
+        ...opts,
+        brief,
+        briefLabel: opts.briefLabel ?? opts.briefPath,
+        seen: sess || opts.since ? seen : undefined,
+        sections: sess?.sections,
+        layouts: sess?.layouts,
+    });
+    if (sess) {
+        const where = `route ${opts.stage}`;
+        for (const u of r.units)
+            (u.inlined === 'body' ? markServed : markLine)(sess, u.id, where);
+        if (!sess.stages.includes(opts.stage))
+            sess.stages.push(opts.stage);
+    }
+    return { text: r.text, data: r };
+}
+function limitText(ctx, id) {
+    if (!id)
+        return '';
+    const u = ctx.byId.get(id);
+    return u
+        ? u.summary.replace(/^[^:]+:\s*/, '').replace(/\s*·\s*soft \(copy guidance\)\.?$/, '')
+        : '';
+}
+/** Labelled fragment-doc paragraphs `clay section email.<id>` leaves out (provenance / Storybook filing, not build knowledge). */
+const EMAIL_NOTE_SKIP = /^(?:source|source reference|re-file to|qa history|related)$/i;
+const EMAIL_NOTE_BLOCKS = [
+    ['Structure', /^structure$/i],
+    ['Tokens', /^tokens$/i],
+    ['Mobile', /^mobile behaviou?r$/i],
+    ['Dark mode', /^dark mode$/i],
+];
+function slotLines(slots, depth = 0, out = []) {
+    for (const n of slots) {
+        const attrs = Object.entries(n.attrs)
+            .map(([k, v]) => `${k}="${v}"`)
+            .join(' ');
+        if (n.el === 'repeat')
+            out.push(`${'  '.repeat(depth)}- ×${n.count} (these ${n.children.length} elements repeat as a group; copy differs per repeat)`);
+        else
+            out.push(`${'  '.repeat(depth)}- ${n.count > 1 ? `×${n.count} ` : ''}\`${n.el}\`${attrs ? ` ${attrs}` : ''}${n.text ? ` — "${n.text}"` : ''}`);
+        slotLines(n.children, depth + 1, out);
+    }
+    return out;
+}
+/**
+ * `clay section email.<id>` (K7 r1): the email analogue of the web section contract — flags + include, the brief fields with
+ * their limits (the "props"), the fragment's structure / tokens / mobile lines, the `.mjml` slot tree (each element's
+ * padding / mj-class / css-class to keep) and the gotchas (divergences + hand-written units about the section), so an agent
+ * does not need to open the `.md`, `.mjml` or `compile.ts`.
+ */
+function emailSection(ctx, name, sec) {
+    const f = sec.facts;
+    const used = [sec.id];
+    const id = f.emailId;
+    const L = [
+        `# ${name} · ${f.title}`,
+        sec.summary.replace(/^Email (?:section|component) `[^`]+` \([^)]*\): /, ''),
+        '',
+        `Flags: ${f.flags.join(' · ')}.`,
+        `Include: \`${f.include}\` (paste the fragment inline to change copy).`,
+    ];
+    const about = f.notes.find((n) => n.label === 'Note' || n.label === 'Intro');
+    if (about)
+        L.splice(2, 0, '', about.text.replace(/\s*\n\s*/g, ' '));
+    if (f.fields.length) {
+        L.push('', `## Brief fields → slots (limits: \`clay get limit.email.<key>\`)`);
+        const blocks = [...new Set(f.fields.map((x) => x.block))];
+        for (const b of blocks) {
+            const fs = f.fields.filter((x) => x.block === b);
+            L.push(`- ${fs[0].repeat ? 'repeating block' : 'block'}: ${fs
+                .map((x) => {
+                const lim = x.limitId ? ctx.byId.get(x.limitId) : undefined;
+                if (lim)
+                    used.push(lim.id);
+                return `${x.label} (${x.kind}${lim ? ` — ${/\*\*Email [^:]+: ([^*]+?)\.?\*\*/.exec(lim.body)?.[1] ?? lim.summary}` : ''})`;
+            })
+                .join(' · ')}`);
+        }
+    }
+    else
+        L.push('', '## Brief fields: none (structural — keep the fragment as is)');
+    const notes = f.notes.filter((n) => !EMAIL_NOTE_SKIP.test(n.label));
+    const taken = new Set();
+    for (const [title, re] of EMAIL_NOTE_BLOCKS) {
+        const n = notes.find((x) => re.test(x.label));
+        if (!n)
+            continue;
+        taken.add(n.label);
+        L.push('', `## ${title}`, n.text);
+        if (title === 'Structure' && f.slots.length) {
+            const lines = slotLines(f.slots);
+            L.push('', `## Slots (\`${f.mjmlPath}\` — keep each element's attributes; copy and asset placeholders are replaced)`, ...lines.slice(0, 40), ...(lines.length > 40 ? [`- … ${lines.length - 40} more lines (\`${f.mjmlPath}\`)`] : []));
+        }
+    }
+    if (!taken.has('Structure') && f.slots.length) {
+        const lines = slotLines(f.slots);
+        L.push('', `## Slots (\`${f.mjmlPath}\` — keep each element's attributes; copy and asset placeholders are replaced)`, ...lines.slice(0, 40), ...(lines.length > 40 ? [`- … ${lines.length - 40} more lines`] : []));
+    }
+    const gotchas = notes.filter((n) => !taken.has(n.label) && n.label !== 'Intro' && n.label !== 'Note');
+    const hand = ctx.kb.units
+        .filter((u) => u.scope === 'email' &&
+        u.authority !== 'derived' &&
+        u.authority !== 'background' &&
+        u.entities.includes(`section:email.${id}`) &&
+        u.entities.filter((e) => e.startsWith('section:email.')).length <= 3)
+        .sort((a, b) => (a.kind === 'gotcha' ? 0 : 1) - (b.kind === 'gotcha' ? 0 : 1) || (a.id < b.id ? -1 : 1));
+    if (gotchas.length || hand.length) {
+        L.push('', '## Gotchas and usage (`clay get <id>`)');
+        for (const n of gotchas) {
+            // Re-flow wrapped lines; a list under the label becomes nested bullets.
+            const items = n.text
+                .split('\n')
+                .reduce((acc, l) => /^\s*-\s/.test(l) || !acc.length
+                ? [...acc, l.trim()]
+                : [...acc.slice(0, -1), `${acc[acc.length - 1]} ${l.trim()}`], [])
+                .filter(Boolean);
+            if (items.length > 1 && items.every((x) => x.startsWith('- ')))
+                L.push(`- **${n.label}:**`, ...items.map((x) => `  ${x}`));
+            else
+                L.push(`- **${n.label}:** ${items.join(' ')}`);
+        }
+        for (const u of hand) {
+            L.push(`- \`${u.id}\`${u.severity ? ` (${u.severity})` : ''} — ${u.summary}`);
+            used.push(u.id);
+        }
+    }
+    return { text: `${L.join('\n')}\n`, data: { section: name, units: used } };
+}
+/** `clay section` with no name (K8): every web section with its layouts and use, plus the atoms `clay section` also takes. */
+export function sectionList(ctx, opts = {}) {
+    const email = opts.scope === 'email';
+    const secs = ctx.kb.units.filter((u) => u.kind === 'section' &&
+        u.authority === 'derived' &&
+        (email ? u.scope === 'email' : u.scope !== 'email'));
+    const L = [
+        `# ${email ? 'Email' : 'Web'} sections (${secs.length}) — \`clay section <name> [--layout <l>]\``,
+    ];
+    for (const u of secs) {
+        const name = u.id.replace(/^section\./, '');
+        const lays = ctx.kb.units
+            .filter((x) => x.kind === 'layout' && x.authority === 'derived' && x.id.startsWith(`layout.${name}.`))
+            .map((x) => x.id.split('.').pop());
+        const what = / — ([^—]+)$/.exec(u.summary)?.[1]?.replace(/\.$/, '') ?? '';
+        L.push(email
+            ? `- \`${name}\` — ${u.summary.replace(/^Email section `[^`]+` /, '').slice(0, 90)}`
+            : `- \`${name}\`${what ? ` (${what})` : ''}${lays.length ? `: ${lays.join(' · ')}` : ''}`);
+    }
+    if (!email) {
+        const atoms = ctx.kb.units
+            .filter((u) => u.kind === 'component' &&
+            u.authority === 'derived' &&
+            u.scope !== 'email' &&
+            !u.id.includes('.', 'component.'.length))
+            .map((u) => u.id.slice('component.'.length));
+        L.push('', `Atoms (\`clay section <Atom>\` for props): ${atoms.join(', ')}.`, 'Email sections: `clay section --scope email`.');
+    }
+    return { text: `${L.join('\n')}\n`, data: { sections: secs.map((u) => u.id) } };
+}
+/* K10 compact section view ─────────────────────────────────────────────────────────────────── */
+/** A prop or item-field type in a few characters: string is implied, unions keep their values, objects their keys. */
+function shortType(t) {
+    const s = t.trim();
+    if (s === 'string')
+        return '';
+    if (/^\(.*\)\s*=>/.test(s) || /^\(\(.*\)\)$/.test(s))
+        return '()';
+    if (/^\{/.test(s))
+        return `{${[...s.matchAll(/(\w+)\??:/g)]
+            .map((m) => m[1])
+            .filter((k) => k !== 'onClick')
+            .join(',')}}`;
+    if (/^'[^']*'(\s*\|\s*'[^']*')+$/.test(s))
+        return s.replace(/\s*\|\s*/g, '|');
+    if (s === 'ReactNode' || s === 'React.ReactNode')
+        return 'node';
+    return s.length > 40 ? `${s.slice(0, 37)}…` : s;
+}
+/** `●name type =default limit` — one prop or item field, compact. */
+function fieldShort(ctx, f) {
+    const t = shortType(f.type);
+    const lim = f.limitId ? limitShort(ctx.byId.get(f.limitId)) : '';
+    const def = f.defaultValue && f.defaultValue !== '[]'
+        ? `=${f.defaultValue.length > 28 ? `${f.defaultValue.slice(0, 26)}…` : f.defaultValue}`
+        : '';
+    return [`${f.required ? '●' : ''}${f.name}`, t, def, lim].filter(Boolean).join(' ');
+}
+/** The derived layout body lines a compact view keeps (CTAs, tab label, media, unguarded defaults, item-count code). */
+const LAYOUT_KEEP = /^(?:Use for:|Tab label:|Section CTA:|Item CTAs|Media slots|Always rendered|Item count|Grid|Columns|Note)/;
+/**
+ * `clay section <S> --layout <l>[,<l2>…]` inside a session (K10): per layout ~6–10 lines instead of ~25–50 — the range and
+ * heading tier on the title line, the rendered props on one line, one line per rendered item type, the CTA / media
+ * lines, and at most 4 new gotchas (the rest as ids). Several layouts of one section share the call.
+ */
+function compactSection(ctx, name, sec, layouts, sess) {
+    const f = (sec.facts ?? {});
+    const used = [sec.id];
+    const L = [];
+    const what = / — ([^—]+)$/.exec(sec.summary)?.[1]?.replace(/\.$/, '') ?? '';
+    const about = (u) => u.entities.includes(`section:${name}`) || u.entities.includes(`component:${name}`);
+    if (!layouts.length) {
+        // Overview: the layouts with their ranges, every prop on one line, the item types.
+        const lays = ctx.kb.units.filter((u) => u.kind === 'layout' && u.authority === 'derived' && u.id.startsWith(`layout.${name}.`));
+        const vp = variantPropOf(lays[0]);
+        L.push(`# ${name}${what ? ` — ${what}` : ''}${lays.length ? ` (${lays.length} ${vp === 'layout' ? 'layouts' : `\`${vp}\` values, passed as \`${vp}="…"\``}; \`clay section ${name} --layout a,b\` for what they render)` : ''}`);
+        for (const u of lays) {
+            const use = /Use for: ([^\n]*)/.exec(u.body)?.[1]?.replace(/\.$/, '');
+            L.push([
+                `- \`${u.id.split('.').pop()}\``,
+                layoutLine(u).replace(/^\S+ \S+ ?/, ''),
+                use ? `— ${use}` : '',
+            ]
+                .filter(Boolean)
+                .join(' '));
+            used.push(u.id);
+        }
+        const props = (f.props ?? []).filter((p) => p.name !== 'layout');
+        if (props.length)
+            L.push(`Props (● required; c chars · w words): ${props.map((p) => fieldShort(ctx, p)).join(' · ')}`);
+        for (const it of [
+            ...new Set(props.map((p) => /^([A-Z][A-Za-z0-9]*)\[\]$/.exec(p.type)?.[1]).filter(Boolean)),
+        ]) {
+            const iu = ctx.byId.get(`item.${it}`);
+            if (!iu)
+                continue;
+            used.push(iu.id);
+            L.push(`${it}: ${((iu.facts ?? {}).fields ?? []).map((x) => fieldShort(ctx, x)).join(' · ')}`);
+        }
+    }
+    for (const layout of layouts) {
+        const lu = ctx.byId.get(`layout.${name}.${layout}`);
+        if (!lu) {
+            const lays = ctx.kb.units
+                .filter((u) => u.kind === 'layout' && u.id.startsWith(`layout.${name}.`) && u.authority === 'derived')
+                .map((u) => u.id.split('.').pop());
+            throw new Error(`section: ${name} has no layout "${layout}". Layouts: ${lays.join(', ')}`);
+        }
+        used.push(lu.id);
+        const lf = (lu.facts ?? {});
+        const range = layoutLine(lu)
+            .replace(/^\S+ \S+ ?/, '')
+            .replace(/^\(|\)$/g, '');
+        L.push(`# ${name} · ${variantPropOf(lu)}="${layout}"${lf.headingTier ? ` · heading tier ${lf.headingTier}` : ''}${range ? ` · ${range}` : ' · items: no documented range'}`);
+        const rendered = new Set(lf.propsRendered ?? []);
+        const props = (f.props ?? []).filter((p) => rendered.has(p.name));
+        if (props.length)
+            L.push(`Props: ${props.map((p) => fieldShort(ctx, p)).join(' · ')}`);
+        if (lf.propsIgnored?.length)
+            L.push(`Ignored here: ${lf.propsIgnored.join(' · ')}`);
+        for (const [it, { rendered: rf }] of Object.entries(lf.itemFields ?? {})) {
+            const iu = ctx.byId.get(`item.${it}`);
+            const fields = (iu?.facts ?? {}).fields ?? [];
+            if (iu)
+                used.push(iu.id);
+            const shown = fields.filter((x) => rf.includes(x.name));
+            const not = fields.filter((x) => !rf.includes(x.name)).map((x) => x.name);
+            if (shown.length)
+                L.push(`${it}: ${shown.map((x) => fieldShort(ctx, x)).join(' · ')}${not.length ? ` (not rendered by this ${variantPropOf(lu)}: ${not.join(', ')})` : ''}`);
+        }
+        for (const l of tight(lu.body).split('\n'))
+            if (LAYOUT_KEEP.test(l))
+                L.push(l);
+    }
+    // Gotchas / usage about this section (and these layouts), new ones first, at most 4 printed.
+    const specific = (u) => u.kind !== 'policy' ||
+        u.id.split('.').includes(name) ||
+        u.entities.some((e) => e.startsWith(`layout:${name}:`));
+    const notes = ctx.kb.units
+        .filter((u) => u.authority !== 'background' &&
+        u.authority !== 'derived' &&
+        about(u) &&
+        ['gotcha', 'section', 'policy', 'component', 'layout'].includes(u.kind) &&
+        specific(u))
+        .filter((u) => !u.id.startsWith('gotcha.page.') &&
+        !u.id.startsWith('gotcha.ai-page.') &&
+        !u.id.includes('.example.'))
+        .filter((u) => !layouts.length ||
+        !u.entities.some((e) => e.startsWith(`layout:${name}:`)) ||
+        layouts.some((l) => u.entities.includes(`layout:${name}:${l}`)))
+        .sort((a, b) => (SEV[b.severity ?? ''] ?? 0) - (SEV[a.severity ?? ''] ?? 0) ||
+        (a.kind === 'gotcha' ? 0 : 1) - (b.kind === 'gotcha' ? 0 : 1) ||
+        (a.id < b.id ? -1 : 1));
+    const fresh = notes.filter((u) => !seenLine(sess, u.id));
+    const shown = fresh.slice(0, 4);
+    for (const u of shown) {
+        L.push(`- \`${u.id}\`${u.severity ? ` (${u.severity})` : ''} — ${u.summary}`);
+        used.push(u.id);
+    }
+    const rest = fresh.slice(4).map((u) => `\`${u.id}\``);
+    const old = notes.length - fresh.length;
+    if (rest.length || old)
+        L.push(`${rest.length ? `More about ${name}: ${rest.join(' · ')}` : ''}${rest.length && old ? ' · ' : ''}${old ? `${old} listed earlier this session` : ''}`);
+    const ex = ctx.kb.units.filter((u) => u.id.startsWith(`section.${name}.example.`) &&
+        (!layouts.length || layouts.some((l) => u.id.endsWith(`.example.${l}`))));
+    if (ex.length)
+        L.push(`Example${ex.length > 1 ? 's' : ''}: ${ex.map((u) => `\`clay get ${u.id}\``).join(' · ')}`);
+    if (sess) {
+        for (const l of layouts.length ? layouts : [undefined])
+            noteSection(sess, name, l);
+        const where = `section ${name}${layouts.length ? ` --layout ${layouts.join(',')}` : ''}`;
+        if (!layouts.length)
+            markServed(sess, `${sec.id}#overview`, where);
+        for (const id of used)
+            (id === sec.id || id.startsWith('layout.') || id.startsWith('item.') ? markServed : markLine)(sess, id, where);
+    }
+    return {
+        text: `${L.join('\n')}\n`,
+        data: { section: name, layout: layouts.join(',') || undefined, units: used },
+    };
+}
+const SEV = { Critical: 3, Major: 2, Minor: 1 };
+/** The section prop a layout unit is a value of (`layout`, `colorMode`, `variant`, …). */
+function variantPropOf(u) {
+    return (u?.facts ?? {}).variantProp ?? 'layout';
+}
+export function section(ctx, name, layout, opts = {}) {
+    const layouts = (layout ?? '')
+        .split(',')
+        .map((x) => x.trim())
+        .filter(Boolean);
+    if (opts.compact || layouts.length > 1) {
+        const sec0 = ctx.byId.get(`section.${name}`) ?? ctx.byId.get(`component.${name}`);
+        if (sec0 &&
+            !(sec0.scope === 'email' && sec0.facts?.emailId)) {
+            if (opts.compact)
+                return compactSection(ctx, name, sec0, layouts, opts.session);
+            const parts = layouts.map((l) => section(ctx, name, l, { session: opts.session }));
+            return {
+                text: parts.map((p) => p.text).join(''),
+                data: {
+                    section: name,
+                    layout: layouts.join(','),
+                    units: parts.flatMap((p) => p.data.units),
+                },
+            };
+        }
+    }
+    const sess = opts.session;
+    const sec = ctx.byId.get(`section.${name}`) ?? ctx.byId.get(`component.${name}`);
+    if (sec && sec.scope === 'email' && sec.facts?.emailId)
+        return emailSection(ctx, name, sec);
+    if (!sec) {
+        const near = ctx.kb.units
+            .filter((u) => u.kind === 'section' && u.authority === 'derived' && u.scope !== 'email')
+            .map((u) => u.id.slice('section.'.length));
+        throw new Error(`section: no section or component "${name}". Sections: ${near.join(', ')} (web; atoms: \`clay section\`; several: \`clay section A,B --layout x,y\`)`);
+    }
+    const f = (sec.facts ?? {});
+    const used = [sec.id];
+    const L = [
+        `# ${name}${layout ? ` · ${variantPropOf(ctx.byId.get(`layout.${name}.${layout}`))}="${layout}"` : ''}`,
+        sec.summary,
+    ];
+    // K8 session: the section's prop table / an item's fields were already printed → one line instead.
+    const propsKey = `${sec.id}#props`;
+    const propsSeen = seenBody(sess, propsKey);
+    if (!layout && seenBody(sess, `${sec.id}#overview`)) {
+        noteSection(sess, name);
+        return {
+            text: `# ${name}\nServed earlier in this session (\`clay section ${name}\`); \`clay section ${name} --layout <l>\` for one layout.\n`,
+            data: { section: name, units: [] },
+        };
+    }
+    const about = (u) => u.entities.includes(`section:${name}`) || u.entities.includes(`component:${name}`);
+    if (layout) {
+        const lu = ctx.byId.get(`layout.${name}.${layout}`);
+        if (!lu) {
+            const lays = ctx.kb.units
+                .filter((u) => u.kind === 'layout' && u.id.startsWith(`layout.${name}.`) && u.authority === 'derived')
+                .map((u) => u.id.split('.').pop());
+            throw new Error(`section: ${name} has no layout "${layout}". Layouts: ${lays.join(', ')}`);
+        }
+        used.push(lu.id);
+        L.push('', `## ${lu.id}`, tight(lu.body));
+    }
+    else {
+        const lays = ctx.kb.units.filter((u) => u.kind === 'layout' && u.authority === 'derived' && u.id.startsWith(`layout.${name}.`));
+        if (lays.length) {
+            const vp = variantPropOf(lays[0]);
+            L.push('', `## Layouts${vp === 'layout' ? '' : ` — values of the \`${vp}\` prop`} (\`clay section ${name} --layout <l>\` for what one renders)`);
+            for (const u of lays) {
+                L.push(`- \`${u.id.split('.').pop()}\` ${layoutLine(u).replace(/^\S+ \S+ ?/, '')}`);
+                used.push(u.id);
+            }
+        }
+    }
+    // Props (compact) — on a layout view, only the props that layout renders.
+    const rendered = layout
+        ? new Set((ctx.byId.get(`layout.${name}.${layout}`)?.facts ?? {})
+            .propsRendered ?? [])
+        : undefined;
+    const props = (f.props ?? []).filter((p) => !rendered || rendered.has(p.name));
+    if (props.length && propsSeen) {
+        L.push('', `Props${rendered ? ' this layout renders' : ''}: ${props.map((p) => `${p.required ? '●' : ''}\`${p.name}\``).join(' · ')} (types and limits: printed earlier by \`clay section ${name}\`).`);
+    }
+    else if (props.length) {
+        L.push('', `## Props${rendered ? ' this layout renders' : ''} (● required)`);
+        for (const p of props) {
+            const lim = limitText(ctx, p.limitId);
+            L.push(`- ${p.required ? '●' : '○'} \`${p.name}\`: \`${p.type.length > 70 ? `${p.type.slice(0, 67)}…` : p.type}\`${p.defaultValue ? ` = ${p.defaultValue.length > 40 ? `${p.defaultValue.slice(0, 37)}…` : p.defaultValue}` : ''}${lim ? ` · ${lim}` : ''}`);
+        }
+    }
+    // Item shapes used by the props shown.
+    const itemNames = [
+        ...new Set(props.map((p) => /^([A-Z][A-Za-z0-9]*)\[\]$/.exec(p.type)?.[1]).filter(Boolean)),
+    ];
+    for (const it of itemNames) {
+        const iu = ctx.byId.get(`item.${it}`);
+        if (!iu)
+            continue;
+        if (seenBody(sess, iu.id)) {
+            L.push('', `${it}: fields printed earlier in this session (\`clay get ${iu.id} --full\`).`);
+            continue;
+        }
+        used.push(iu.id);
+        const fields = (iu.facts ?? {}).fields ?? [];
+        L.push('', `## ${it}`, ...fields.map((x) => `- ${x.required ? '●' : '○'} \`${x.name}\`: \`${x.type.length > 60 ? `${x.type.slice(0, 57)}…` : x.type}\`${x.limitId ? ` · ${limitText(ctx, x.limitId)}` : ''}`));
+    }
+    // Gotchas / usage (hand-written) about this section (and this layout).
+    // Policies only when they are specific to this section (named in the id, or about one of its layouts).
+    const specific = (u) => u.kind !== 'policy' ||
+        u.id.split('.').includes(name) ||
+        u.entities.some((e) => e.startsWith(`layout:${name}:`));
+    const notes = ctx.kb.units
+        .filter((u) => u.authority !== 'background' &&
+        u.authority !== 'derived' &&
+        about(u) &&
+        ['gotcha', 'section', 'policy', 'component', 'layout'].includes(u.kind) &&
+        specific(u))
+        .filter((u) => !u.id.startsWith('gotcha.page.') && !u.id.startsWith('gotcha.ai-page.'))
+        .filter((u) => !layout ||
+        !u.entities.some((e) => e.startsWith(`layout:${name}:`)) ||
+        u.entities.includes(`layout:${name}:${layout}`))
+        .sort((a, b) => (a.kind === 'gotcha' ? 0 : 1) - (b.kind === 'gotcha' ? 0 : 1) || (a.id < b.id ? -1 : 1));
+    const newNotes = notes.filter((u) => !seenLine(sess, u.id));
+    const oldNotes = notes.filter((u) => seenLine(sess, u.id));
+    if (newNotes.length) {
+        L.push('', '## Gotchas and usage (`clay get <id>`)');
+        for (const u of newNotes) {
+            L.push(`- \`${u.id}\`${u.severity ? ` (${u.severity})` : ''} — ${u.summary}`);
+            used.push(u.id);
+        }
+    }
+    if (oldNotes.length)
+        L.push('', `Also about ${name} (listed earlier this session): ${oldNotes.map((u) => `\`${u.id}\``).join(', ')}`);
+    if (sess) {
+        noteSection(sess, name, layout);
+        const where = `section ${name}${layout ? ` --layout ${layout}` : ''}`;
+        if (props.length && !propsSeen && !layout)
+            markServed(sess, propsKey, where);
+        if (!layout)
+            markServed(sess, `${sec.id}#overview`, where);
+        for (const id of used)
+            (id === sec.id || id.startsWith('layout.') || id.startsWith('item.') ? markServed : markLine)(sess, id, where);
+    }
+    return { text: `${L.join('\n')}\n`, data: { section: name, layout, units: used } };
+}
+/* ── rules ─────────────────────────────────────────────────────────────────────────────────── */
+export function rules(ctx, opts = {}) {
+    // K7: `--scope email` lists the email rules (email-rules.json, what `pnpm email:check` enforces); the default is web.
+    const email = opts.scope === 'email';
+    const fits = (u) => (!opts.stage || u.stages.includes(opts.stage)) &&
+        (!opts.mode || !u.modes || u.modes.includes(opts.mode)) &&
+        (email ? u.scope === 'email' : u.scope !== 'email');
+    const hard = ctx.kb.units.filter((u) => u.kind === 'rule' && fits(u));
+    const pol = ctx.kb.units
+        .filter((u) => u.kind === 'policy' &&
+        u.authority === 'canonical' &&
+        (u.severity === 'Critical' || u.severity === 'Major') &&
+        u.enforcement?.length &&
+        fits(u))
+        .sort((a, b) => a.severity === b.severity ? (a.id < b.id ? -1 : 1) : a.severity === 'Critical' ? -1 : 1);
+    const line = (u) => `- \`${u.id}\`${u.severity ? ` ${u.severity}` : ''}${u.enforcement?.length ? ` · ${u.enforcement.join('/')}` : ''} — ${u.summary}`;
+    const text = [
+        `# Rules${opts.stage ? ` · stage ${opts.stage}` : ''}${opts.mode ? ` · mode ${opts.mode}` : ''}`,
+        `## ${email ? 'Email rules' : 'Hard Rules'} (${hard.length})`,
+        ...hard.map(line),
+        `## Policies with enforcement (${pol.length}; Critical first)`,
+        ...pol.map(line),
+    ].join('\n');
+    return { text: `${text}\n`, data: { units: [...hard, ...pol].map((u) => u.id) } };
+}
+//# sourceMappingURL=query.js.map