@pikku/cli 0.12.156 → 0.12.160

package/dist/src/functions/commands/scenario.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { resolve, join } from 'node:path';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, join, dirname, relative, sep } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { glob } from 'tinyglobby';
 import { pikkuSessionlessFunc } from '#pikku/function';
 import { InMemoryWorkflowService } from '@pikku/core/services';
 import { FileScenarioRunStore } from '@pikku/core/services';
@@ -14,7 +15,8 @@ import { resolveScenarioBrowserProvider, scenarioBrowserLifecycle, } from './sce
 import { resolvePersonas } from '../../utils/resolve-personas.js';
 import { resolvePersonaCredentials } from '../../utils/persona-credentials.js';
 import { spawnDevServer } from '../../server/spawn-dev-server.js';
-import { buildScenarioPlan } from './scenario-plan.js';
+import { checkGuideCoverage, featureEvidence, guideStep, parseGuideLock, parseGuidePage, renderGuideLock, renderGuidePage, } from './scenario-guide.js';
+import { buildScenarioPlan, identifyScenarioResult } from './scenario-plan.js';
 import { resolveEnvironment, isLocalUrl } from './environment.js';
 import { readDevAddress } from './dev-address.js';
 import { createDevAgentRunner } from './dev-agent-runner.js';
@@ -236,7 +238,7 @@ export const scenarioRun = pikkuSessionlessFunc({
             apiUrl: env.apiUrl,
             appUrl: env.appUrl,
         });
-        scenarioService.setRunSurface(runSurface);
+        scenarioService.setRunSurface(runSurface, strict);
         // Scenario steps run here, not on the target — everything they touch of the
         // app goes over HTTP through an actor, which is what `guardRpc` below
         // enforces. `actor.converse` is the exception, and the reason this is not
@@ -354,11 +356,18 @@ export const scenarioRun = pikkuSessionlessFunc({
         const runStore = new FileScenarioRunStore({ dir: captureDir });
         const startedAtIso = new Date().toISOString();
         try {
+            const selection = {
+                ...(split(flows) ? { flows: split(flows) } : {}),
+                ...(split(features) ? { features: split(features) } : {}),
+                ...(split(tags) ? { tags: split(tags) } : {}),
+                ...(split(excludeTags) ? { excludeTags: split(excludeTags) } : {}),
+            };
             await runStore.start({
                 runId: captureRunId,
                 environment,
                 surface: runSurface,
                 status: 'running',
+                ...(Object.keys(selection).length > 0 ? { selection } : {}),
                 startedAt: startedAtIso,
                 results: [],
                 skipped,
@@ -371,6 +380,11 @@ export const scenarioRun = pikkuSessionlessFunc({
              * is the formatter's job.
              */
             const readRunSteps = async (service, runId, flowName) => {
+                // Taken from the run rather than derived from the ladder: the video
+                // clock starts when an actor's window opens, which is somewhere after
+                // step one, and every step that never touched a browser burns scenario
+                // time while the recording sits still.
+                const videoOffsets = scenarioService.takeStepVideoOffsets(runId);
                 const prose = collectScenarioStepProse(state.workflows?.meta?.[flowName], functionsMeta, state.personas?.definitions ?? []);
                 const steps = (await service.getRunSteps(runId)).map((step) => ({
                     stepName: step.stepName,
@@ -383,6 +397,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                     expected: step.error?.expected,
                     input: step.data,
                     stepFunc: step.rpcName,
+                    video: videoOffsets.get(step.stepName),
                 }));
                 return {
                     rows: scenarioStepRows(steps, prose),
@@ -427,33 +442,29 @@ export const scenarioRun = pikkuSessionlessFunc({
             };
             const hookFailures = [];
             /**
-             * What a result carries beyond its own outcome: which registration ran,
-             * which feature grouped it, and the tags it was selected by. Snapshotted
-             * into the record because a run read back next week is describing a suite
+             * Which registration ran and which feature grouped it, snapshotted into
+             * the record because a run read back next week is describing a suite
              * whose source has moved on.
              */
-            const identify = (result, scenarioName, feature) => {
-                const tags = state.workflows?.meta?.[scenarioName]?.tags;
-                return {
-                    ...result,
-                    scenarioName,
-                    ...(feature ? { feature } : {}),
-                    ...(tags?.length ? { tags } : {}),
-                };
-            };
-            const runEntry = async (label, scenarioName, data, feature) => {
+            const identityOf = (scenarioName, group) => ({
+                scenarioName,
+                featureId: group?.featureId,
+                featureName: group?.featureName,
+                tags: state.workflows?.meta?.[scenarioName]?.tags,
+            });
+            const runEntry = async (label, scenarioName, data, identity) => {
                 const startedAt = Date.now();
                 if (databaseBaseline) {
                     try {
                         await databaseBaseline.restore();
                     }
                     catch (e) {
-                        const result = identify({
+                        const result = identifyScenarioResult({
                             name: label,
                             status: 'failed',
                             durationMs: Date.now() - startedAt,
                             error: `database reset failed: ${e?.message ?? e}`,
-                        }, scenarioName, feature);
+                        }, identity);
                         results.push(result);
                         await runStore.recordScenario(captureRunId, result);
                         return;
@@ -534,7 +545,7 @@ export const scenarioRun = pikkuSessionlessFunc({
                 // Told here, acted on at the next scenario's reset — that is what closes
                 // these windows and finalises the video this outcome decides the fate of.
                 browserLifecycle.endScenario(result.status);
-                Object.assign(result, identify(result, scenarioName, feature));
+                Object.assign(result, identifyScenarioResult(result, identity));
                 await runStore.recordScenario(captureRunId, result);
                 if (coverageActive) {
                     const report = await invokeCoverage('pikkuScenarioTakeLiveCoverage');
@@ -582,19 +593,19 @@ export const scenarioRun = pikkuSessionlessFunc({
                         // Setup failed, so nothing in the group ran. Reporting them as failed
                         // rather than skipped is the honest reading: they did not pass.
                         for (const entry of group.entries) {
-                            const result = identify({
+                            const result = identifyScenarioResult({
                                 name: label(entry),
                                 status: 'failed',
                                 durationMs: 0,
                                 error: `${groupName ? `feature '${groupName}' ` : ''}${beforeStage} failed: ${beforeError?.message ?? beforeError}`,
-                            }, entry.scenarioName, groupName);
+                            }, identityOf(entry.scenarioName, group));
                             results.push(result);
                             await runStore.recordScenario(captureRunId, result);
                         }
                     }
                     else {
                         for (const entry of group.entries) {
-                            await runEntry(label(entry), entry.scenarioName, entry.data, groupName);
+                            await runEntry(label(entry), entry.scenarioName, entry.data, identityOf(entry.scenarioName, group));
                         }
                     }
                 }
@@ -699,3 +710,156 @@ export const scenarioRun = pikkuSessionlessFunc({
         }
     },
 });
+/**
+ * `pikku scenario guide` — the suite, written out as markdown.
+ *
+ * Structure comes from the registry (which features exist, what their scenarios
+ * are called), and evidence from the latest run record (what the steps actually
+ * said, and what they filed). Editorial prose comes from the project's own
+ * `docs/` sources, which cite a feature by leaving the marker pair where its
+ * block belongs; this merges the three and writes one markdown file per source.
+ * It renders nothing, resolves no asset URLs and calls no model: the writing is
+ * somebody else's concern, and this is the compiler that keeps it honest.
+ */
+export const scenarioGuide = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, { docs = 'docs', output, runId, allowUndocumented = false, artifactBase }) => {
+        const state = await getInspectorState(false, false, false, true);
+        const outDir = resolve(config.rootDir, config.outDir);
+        await loadScenarioBootstrap(outDir);
+        const { features: registeredFeatures } = collectRegisteredWirings();
+        const runsDir = join(outDir, 'scenario-runs');
+        const runStore = new FileScenarioRunStore({ dir: runsDir });
+        const latest = runId ?? (await runStore.list({ limit: 1 }))[0]?.runId;
+        const record = latest ? await runStore.get(latest) : undefined;
+        if (!record) {
+            logger.error(runId
+                ? `No run '${runId}' under ${runsDir}.`
+                : `No scenario run under ${runsDir} — run \`pikku scenario run <environment> --screenshots\` first, since a guide is written out of what a run recorded.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (record.status !== 'passed') {
+            logger.error(`Run '${record.runId}' is ${record.status}. A guide is a claim that the product does what the page says, so it is only ever written out of a run that passed.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (record.selection) {
+            const narrowed = Object.entries(record.selection)
+                .map(([flag, values]) => `--${flag} ${values.join(',')}`)
+                .join(' ');
+            logger.error(`Run '${record.runId}' was narrowed (${narrowed}), so it is missing scenarios the suite has. Guide pages would be written as though those flows do not exist — run the whole suite, or pass --run-id for one that was.`);
+            process.exitCode = 1;
+            return;
+        }
+        const workflowsMeta = state.workflows?.meta ?? {};
+        const features = [...registeredFeatures].map(([id, feature]) => {
+            const name = feature.name ?? id;
+            return {
+                id,
+                name,
+                ...(feature.description ? { description: feature.description } : {}),
+                document: feature.document !== false,
+                scenarios: record.results
+                    // By id, never by the display name: a title is rewritten freely,
+                    // and two features are allowed to share one.
+                    .filter((result) => result.featureId === id ||
+                    (result.featureId === undefined && result.feature === name))
+                    .map((result) => {
+                    const meta = result.scenarioName
+                        ? workflowsMeta[result.scenarioName]
+                        : undefined;
+                    return {
+                        name: result.scenarioName ?? result.name,
+                        title: meta?.title ?? result.name,
+                        ...(meta?.description ? { description: meta.description } : {}),
+                        steps: (result.steps ?? []).map((step) => guideStep(step.sentence)),
+                        screenshots: (result.artifacts ?? [])
+                            .filter((artifact) => artifact.kind === 'screenshot')
+                            .map((artifact) => ({
+                            ...(artifact.id ? { id: artifact.id } : {}),
+                            ...(artifact.name ? { name: artifact.name } : {}),
+                            path: artifact.path,
+                        })),
+                        videos: (result.artifacts ?? [])
+                            .filter((artifact) => artifact.kind === 'video')
+                            .map((artifact) => ({
+                            ...(artifact.id ? { id: artifact.id } : {}),
+                            ...(artifact.actor ? { actor: artifact.actor } : {}),
+                            path: artifact.path,
+                        })),
+                    };
+                }),
+            };
+        });
+        const docsDir = resolve(config.rootDir, docs);
+        const sources = (await glob('**/*.md', { cwd: docsDir, onlyFiles: true })).sort();
+        const pages = [];
+        for (const source of sources) {
+            pages.push(parseGuidePage(source, readFileSync(join(docsDir, source), 'utf-8')));
+        }
+        const lockPath = join(docsDir, '.guide.lock');
+        const lock = existsSync(lockPath)
+            ? parseGuideLock(readFileSync(lockPath, 'utf-8'))
+            : {};
+        const coverage = checkGuideCoverage(features, pages, lock);
+        for (const { path, featureId } of coverage.unknown) {
+            logger.error(`${join(docs, path)} cites '${featureId}', which is not a registered feature — a page describing something that no longer exists.`);
+        }
+        for (const { path, featureId } of coverage.optedOut) {
+            logger.error(`${join(docs, path)} cites '${featureId}', which declares \`document: false\`.`);
+        }
+        for (const { path, featureId } of coverage.figureless) {
+            logger.warn(`${join(docs, path)} cites '${featureId}', whose run filed no screenshot — the block renders empty. Take one with \`actor.screenshot(...)\` in a scenario the feature owns.`);
+        }
+        for (const { path, featureId, locked, current } of coverage.stale) {
+            logger.warn(`${join(docs, path)} was written against '${featureId}' at ${locked}, which is now ${current} — the flow moved, so re-read the prose around that block.`);
+        }
+        for (const featureId of coverage.missing) {
+            const message = `Feature '${featureId}' is cited by no page. Place \`<!-- pikku:guide feature=${featureId} -->\` and \`<!-- /pikku:guide -->\` in a page under ${docs}/, or set \`document: false\` on the feature.`;
+            if (allowUndocumented) {
+                logger.warn(message);
+            }
+            else {
+                logger.error(message);
+            }
+        }
+        // A compiler that has found an error does not emit. Undocumented features
+        // are the one failure that can be downgraded, because a suite mid-way
+        // through being written still wants its pages built.
+        if (coverage.unknown.length > 0 ||
+            coverage.optedOut.length > 0 ||
+            (!allowUndocumented && coverage.missing.length > 0)) {
+            process.exitCode = 1;
+            return;
+        }
+        const byId = new Map(features.map((feature) => [feature.id, feature]));
+        const outputDir = output
+            ? resolve(config.rootDir, output)
+            : join(outDir, 'guide');
+        const artifactRoot = join(runsDir, record.runId);
+        for (const page of pages) {
+            const target = join(outputDir, page.path);
+            // Relative, forward-slashed and computed per page: a guide is markdown
+            // with ordinary image refs, and whoever consumes it rewrites the paths.
+            // `artifactBase` replaces it with one prefix for every page, for a host
+            // that serves the artifacts at a fixed address rather than beside the
+            // markdown — and it stays as given, since only the caller knows whether
+            // it is a path, a route or an origin.
+            const base = artifactBase
+                ? artifactBase.endsWith('/')
+                    ? artifactBase
+                    : `${artifactBase}/`
+                : `${relative(dirname(target), artifactRoot).split(sep).join('/')}/`;
+            const markdown = renderGuidePage(page, byId, base);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, markdown);
+        }
+        writeFileSync(lockPath, renderGuideLock(features, coverage.cited));
+        logger.info(`${pages.length} page(s) → ${outputDir} (run ${record.runId}, ${coverage.cited.length} documented feature(s))`);
+        for (const feature of features) {
+            if (feature.document) {
+                logger.debug(`  ${feature.id} ${featureEvidence(feature)}`);
+            }
+        }
+    },
+});

package/dist/src/functions/commands/skill-agents.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The frontmatter a skill adds to become a subagent as well as a skill.
+ *
+ * A skill is instructions a session reads; an agent is a child process a host
+ * dispatches and then judges. The difference is entirely the gate, so the gate is
+ * the only thing a skill has to declare — everything else about the agent is
+ * derived from the skill it already is.
+ */
+export interface SkillAgentSpec {
+    tools?: string;
+    timeoutMs?: number;
+    acceptance?: Record<string, unknown>;
+}
+interface SkillFrontmatter {
+    name?: string;
+    description?: string;
+    agent?: SkillAgentSpec;
+}
+export declare function parseSkill(content: string): {
+    frontmatter: SkillFrontmatter;
+    body: string;
+} | null;
+/**
+ * Write out an agent for every installed skill that declares one.
+ *
+ * Skills without an `agent:` block are not projected: a reference skill has no
+ * post-condition a host could check, and an agent whose acceptance is `none` is a
+ * subagent dispatched to read something the caller could have read itself.
+ */
+export declare function installSkillAgents(skills: string[], agentRoot: string, skillDir: string, update: boolean, existing: (path: string) => boolean, read: (path: string) => Promise<string | null>, 
+/**
+ * Host extensions every projected agent loads, as pi resolves them.
+ *
+ * They are passed in rather than declared by the skill because they belong to
+ * whoever is running the agent, not to the instructions it follows: a sandbox
+ * fences its writers and routes their model, and the same skill run on a
+ * developer's own checkout needs neither.
+ */
+extensions?: string[]): Promise<{
+    written: string[];
+    skipped: string[];
+}>;
+export {};

package/dist/src/functions/commands/skill-agents.js

@@ -0,0 +1,135 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { parse, stringify } from 'yaml';
+/**
+ * The tools that can change the workspace, and so decide the agent's role.
+ *
+ * `bash` counts because a shell is a superset of the rest: `sed -i`, `echo >` and
+ * `git checkout` all mutate without touching a file tool.
+ */
+const MUTATING_TOOLS = [
+    'bash',
+    'shell',
+    'write',
+    'edit',
+    'write_files',
+    'edit_files',
+    'patch',
+];
+const DEFAULT_TOOLS = 'read, write, edit, bash, grep';
+/**
+ * The role is derived from the tools rather than declared beside them.
+ *
+ * It is what acceptance is inferred from, so a skill that declares the two
+ * independently can declare them inconsistently — a read-only role holding `write`
+ * is an agent the host judges by rules its tools do not match.
+ */
+function acceptanceRole(tools) {
+    const declared = tools.split(',').map((tool) => tool.trim());
+    return declared.some((tool) => MUTATING_TOOLS.includes(tool))
+        ? 'writer'
+        : 'read-only';
+}
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+export function parseSkill(content) {
+    const match = content.match(FRONTMATTER);
+    if (!match)
+        return null;
+    try {
+        return { frontmatter: parse(match[1]) ?? {}, body: match[2] ?? '' };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The first paragraph of the skill's own description, as the one line a host shows
+ * when it is choosing between agents.
+ *
+ * A skill description is written for a trigger matcher and carries TRIGGER/DO NOT
+ * TRIGGER clauses that mean nothing to a dispatcher, so they are cut rather than
+ * shipped as noise into every agent listing.
+ */
+function agentDescription(description) {
+    return description
+        .split(/\bTRIGGER when\b|\bDO NOT TRIGGER\b/)[0]
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/[,;]\s*$/, '');
+}
+/**
+ * pi reads `acceptance` as a JSON string on one line, and ignores any frontmatter key
+ * it does not know — a post-condition under a key pi has no reader for runs nowhere and
+ * says nothing about it. Emitting through the one key pi acts on is what makes the gate
+ * real rather than decorative.
+ */
+function renderAgent(name, frontmatter, skillDir, extensions) {
+    const agent = frontmatter.agent;
+    const tools = agent.tools ?? DEFAULT_TOOLS;
+    const lines = [
+        '---',
+        `name: ${name}`,
+        `description: ${JSON.stringify(agentDescription(frontmatter.description ?? name))}`,
+        `tools: ${tools}`,
+    ];
+    if (extensions.length > 0) {
+        lines.push(`extensions: ${extensions.join(', ')}`);
+    }
+    if (agent.acceptance) {
+        lines.push('acceptance:');
+        lines.push(stringify(agent.acceptance, { indent: 2 })
+            .trimEnd()
+            .split('\n')
+            .map((line) => `  ${line}`)
+            .join('\n'));
+    }
+    lines.push(`acceptanceRole: ${acceptanceRole(tools)}`);
+    if (agent.timeoutMs) {
+        lines.push(`timeoutMs: ${agent.timeoutMs}`);
+    }
+    lines.push('---', '');
+    const verify = (agent.acceptance?.verify ?? []);
+    lines.push(`Your instructions are \`${skillDir}/${name}/SKILL.md\`. Read it in full before you act, and follow it as written rather than improvising around it.`, '', 'Your caller dispatched you because this stage of the pipeline has a gate it can check, not because it wanted prose back. So the gate is the job.', '');
+    if (verify.length > 0) {
+        lines.push('You are not done until every one of these exits 0, and you have run them yourself:', '', ...verify.map((v) => `- \`${v.command}\``), '', 'A refusal is the gate working. Read what it says is wrong, fix that, and run it again — do not stop at the first one, and do not report success on a command you have not seen pass.', '');
+    }
+    lines.push('Report what you ran and what it said, what you changed, and anything in the skill that was wrong, missing or ambiguous. If you could not pass the gate, say so outright and say where you got stuck — a truthful failure is worth more to your caller than a pass it cannot trust.', '');
+    return lines.join('\n');
+}
+/**
+ * Write out an agent for every installed skill that declares one.
+ *
+ * Skills without an `agent:` block are not projected: a reference skill has no
+ * post-condition a host could check, and an agent whose acceptance is `none` is a
+ * subagent dispatched to read something the caller could have read itself.
+ */
+export async function installSkillAgents(skills, agentRoot, skillDir, update, existing, read, 
+/**
+ * Host extensions every projected agent loads, as pi resolves them.
+ *
+ * They are passed in rather than declared by the skill because they belong to
+ * whoever is running the agent, not to the instructions it follows: a sandbox
+ * fences its writers and routes their model, and the same skill run on a
+ * developer's own checkout needs neither.
+ */
+extensions = []) {
+    const written = [];
+    const skipped = [];
+    for (const name of skills) {
+        const content = await read(`${name}/SKILL.md`);
+        if (content === null)
+            continue;
+        const parsed = parseSkill(content);
+        if (!parsed?.frontmatter.agent)
+            continue;
+        const target = join(agentRoot, `${name}.md`);
+        if (existing(target) && !update) {
+            skipped.push(name);
+            continue;
+        }
+        await mkdir(agentRoot, { recursive: true });
+        await writeFile(target, renderAgent(name, parsed.frontmatter, skillDir, extensions), 'utf-8');
+        written.push(name);
+    }
+    return { written, skipped };
+}

package/dist/src/functions/commands/skills.d.ts

@@ -12,6 +12,9 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     fabric?: boolean;
     client?: boolean;
     update?: boolean;
+    agentExtensions?: string;
+    agentDir?: string;
+    agentSkillDir?: string;
 }, void, "rpc" | "session", import("#pikku/function").PikkuFunction<{
     agent?: string;
     only?: string;
@@ -19,6 +22,9 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     fabric?: boolean;
     client?: boolean;
     update?: boolean;
+    agentExtensions?: string;
+    agentDir?: string;
+    agentSkillDir?: string;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
     agent?: string;
     only?: string;
@@ -26,4 +32,7 @@ export declare const pikkuSkillsInstall: import("#pikku/function").PikkuFunction
     fabric?: boolean;
     client?: boolean;
     update?: boolean;
+    agentExtensions?: string;
+    agentDir?: string;
+    agentSkillDir?: string;
 }, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/commands/skills.js

@@ -1,7 +1,8 @@
 import { readdir, mkdir, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
-import { dirname, join, sep } from 'path';
+import { dirname, isAbsolute, join, sep } from 'path';
 import { listSkillFiles, listSkillNames, readSkillFile } from '@pikku/skills';
+import { installSkillAgents } from './skill-agents.js';
 import { pikkuSessionlessFunc } from '#pikku/function';
 /**
  * Write one skill's files out to `dest`, reading through @pikku/skills rather
@@ -33,6 +34,17 @@ const AGENT_SKILL_DIRS = {
     opencode: join('.opencode', 'skills'),
     pi: join('.pi', 'skills'),
 };
+/**
+ * Where a harness that dispatches subagents reads them from.
+ *
+ * Only harnesses that can enforce a post-condition are listed. Installing an agent
+ * for a harness that cannot run its `acceptance` gate ships the instruction to verify
+ * with nothing that verifies, which reads as stricter than the skill it came from
+ * while being exactly as strict.
+ */
+const AGENT_DIRS = {
+    pi: join('.pi', 'agents'),
+};
 function parseInstallGroups(frontmatter) {
     const inline = frontmatter.match(/^\s*installGroups\s*:\s*\[([^\]]*)\]/m);
     if (inline) {
@@ -118,7 +130,7 @@ export const pikkuSkillsList = pikkuSessionlessFunc({
     },
 });
 export const pikkuSkillsInstall = pikkuSessionlessFunc({
-    func: async ({ logger }, { agent = 'claude', only, core = false, fabric = false, client = false, update = false, }) => {
+    func: async ({ logger }, { agent = 'claude', only, core = false, fabric = false, client = false, update = false, agentExtensions, agentDir, agentSkillDir, }) => {
         const supportedAgents = Object.keys(AGENT_SKILL_DIRS);
         if (!supportedAgents.includes(agent)) {
             logger.error(`Agent "${agent}" is not yet supported. Supported: ${supportedAgents.join(', ')}. ` +
@@ -156,5 +168,20 @@ export const pikkuSkillsInstall = pikkuSessionlessFunc({
         logger.info(`Installed ${installed} skill(s) into ${destLabel}${skipped > 0
             ? ` (skipped ${skipped} already present — pass --update to overwrite)`
             : ''}`);
+        const agentRelative = agentDir ?? AGENT_DIRS[agent];
+        if (!agentRelative)
+            return;
+        const projected = await installSkillAgents(wanted, isAbsolute(agentRelative)
+            ? agentRelative
+            : join(process.cwd(), agentRelative), agentSkillDir ?? AGENT_SKILL_DIRS[agent].split(sep).join('/'), update, existsSync, readSkillFile, agentExtensions
+            ?.split(',')
+            .map((path) => path.trim())
+            .filter(Boolean));
+        if (projected.written.length === 0 && projected.skipped.length === 0)
+            return;
+        const agentLabel = `${agentRelative.split(sep).join('/')}/`;
+        logger.info(`Projected ${projected.written.length} agent(s) into ${agentLabel}${projected.skipped.length > 0
+            ? ` (skipped ${projected.skipped.length} already present — pass --update to overwrite)`
+            : ''}`);
     },
 });

package/dist/src/functions/db/postgres/postgres-introspector.d.ts

@@ -27,6 +27,12 @@ export declare class PostgresIntrospector implements DbIntrospector {
      */
     private getCheckEnums;
     getForeignKeys(table: string): Promise<ForeignKeyInfo[]>;
+    /**
+     * `pk_cols` is fenced with `AS MATERIALIZED` deliberately. Referenced once,
+     * Postgres 12+ inlines it, and the constraint views it joins are then
+     * re-derived per candidate row — quadratic in the number of tables, minutes
+     * instead of milliseconds on a large schema.
+     */
     getAllColumns(): Promise<Map<string, ColumnInfo[]>>;
     getAllForeignKeys(): Promise<Map<string, ForeignKeyInfo[]>>;
     listEnums(): Promise<EnumInfo[]>;

package/dist/src/functions/db/postgres/postgres-introspector.js

@@ -167,8 +167,14 @@ export class PostgresIntrospector {
             foreignColumn: r.foreign_column_name,
         }));
     }
+    /**
+     * `pk_cols` is fenced with `AS MATERIALIZED` deliberately. Referenced once,
+     * Postgres 12+ inlines it, and the constraint views it joins are then
+     * re-derived per candidate row — quadratic in the number of tables, minutes
+     * instead of milliseconds on a large schema.
+     */
     async getAllColumns() {
-        const result = await this.client.query(`WITH pk_cols AS (
+        const result = await this.client.query(`WITH pk_cols AS MATERIALIZED (
          SELECT tc.table_schema, tc.table_name, kcu.column_name
          FROM information_schema.table_constraints tc
          JOIN information_schema.key_column_usage kcu

package/dist/src/functions/knowledge/render.d.ts

@@ -16,4 +16,4 @@ export declare const renderKnowledgePlanDefer: (_services: unknown, { ok, messag
  * rendered as a picker: this is the fallback every harness has, and one that can do
  * better reads the same answer as JSON.
  */
-export declare const renderKnowledgeReconcile: (_services: unknown, { kind, reason, note, hold, notes, question }: KnowledgeReconcileResult) => void;
+export declare const renderKnowledgeReconcile: (_services: unknown, { kind, reason, note, hold, notes, question, required, satisfied, }: KnowledgeReconcileResult) => void;

package/dist/src/functions/knowledge/render.js

@@ -1,9 +1,15 @@
 import { added, changed, dim, removed } from '../../fabric/lib/output.js';
+const ORPHANS_SHOWN = 10;
 export const renderKnowledgeValidate = (_services, { ok, notes, findings }) => {
     const errors = findings.filter((f) => f.severity === 'error');
     const warns = findings.filter((f) => f.severity === 'warn');
     const infos = findings.filter((f) => f.severity === 'info');
-    for (const finding of [...errors, ...warns, ...infos]) {
+    // Orphans are one finding each so a consumer can act on one at a time, but a
+    // project with no knowledge base yet reports every function it has — printing
+    // those in full buries the findings somebody can actually fix.
+    const orphans = infos.filter((f) => f.id.startsWith('knowledge-orphan-'));
+    const rest = infos.filter((f) => !f.id.startsWith('knowledge-orphan-'));
+    for (const finding of [...errors, ...warns, ...rest]) {
         const icon = finding.severity === 'error'
             ? removed('✗')
             : finding.severity === 'warn'
@@ -13,6 +19,18 @@ export const renderKnowledgeValidate = (_services, { ok, notes, findings }) => {
         console.log(`   ${dim('fix:')}  ${finding.fixHint}`);
         console.log();
     }
+    if (orphans.length) {
+        const shown = orphans.slice(0, ORPHANS_SHOWN);
+        console.log(`${dim('ℹ')}  ${orphans.length} thing${orphans.length !== 1 ? 's' : ''} in the code that no note describes`);
+        for (const orphan of shown) {
+            console.log(`   ${dim(orphan.id.slice('knowledge-orphan-'.length))}`);
+        }
+        if (orphans.length > shown.length) {
+            console.log(`   ${dim(`… and ${orphans.length - shown.length} more`)}`);
+        }
+        console.log(`   ${dim('fix:')}  ${shown[0].fixHint}`);
+        console.log();
+    }
     const counts = [dim(`${notes} note${notes !== 1 ? 's' : ''}`)];
     if (errors.length) {
         counts.push(removed(`${errors.length} error${errors.length !== 1 ? 's' : ''}`));
@@ -148,7 +166,12 @@ export const renderKnowledgePlanDefer = (_services, { ok, message }) => {
  * rendered as a picker: this is the fallback every harness has, and one that can do
  * better reads the same answer as JSON.
  */
-export const renderKnowledgeReconcile = (_services, { kind, reason, note, hold, notes, question }) => {
+export const renderKnowledgeReconcile = (_services, { kind, reason, note, hold, notes, question, required, satisfied, }) => {
+    if (required && !satisfied) {
+        process.exitCode = 1;
+        console.log(`${removed('✗')}  next is ${kind}, and this check requires ${required.join(' or ')}`);
+        console.log();
+    }
     if (kind === 'idle') {
         console.log(`${dim('=')}  ${dim(reason)}`);
         return;