@tangle-network/starter-foundry 0.5.3 → 0.7.0

package/dist/training/variant_b/nodes/train.js

@@ -0,0 +1,209 @@
+// train node: takes traces, runs AxMiPRO over the brief signature to find an
+// instruction that biases the brief agent toward producing canonicalPrompts
+// that route correctly through the deterministic planner. The optimized
+// artifact is serialized to JSON at outPath as an AxOptimizedProgram.
+//
+// Swap strategy: replace `AxMiPRO` with `AxBootstrapFewShot` or `AxGEPA` by
+// changing only this file. The TrainOutput contract stays fixed.
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { ax, AxMiPRO } from '@ax-llm/ax';
+import { loadRegistry } from '../../../lib/registry.js';
+import { planPrompt } from '../../../lib/prompt-planner.js';
+const BRIEF_SIGNATURE = '"Turn a user product prompt into a structured product brief that drives a deterministic scaffold pipeline downstream. The canonicalPrompt must be a keyword-rich expansion that names concrete technologies drawn from knownFamilies (e.g. nextjs-ts, fullstack-ts, agent-service-ts, go-api, python-api, forge-contracts, solana-program) and concrete UI/infra capabilities drawn from knownCapabilities (e.g. capability:ai-chat-ui, capability:layout-dashboard, capability:saas-billing). It MUST be longer and more specific than the user prompt. Preserve the user intent exactly. Each list field should have 3-8 items." ' +
+    'userPrompt:string, knownFamilies:string[], knownCapabilities:string[] -> ' +
+    'canonicalPrompt:string, vision:string, taskChecklist:string[], milestones:string[], testingPlan:string[], e2ePlan:string[], securityConcerns:string[], openQuestions:string[], confidence:number';
+function jaccard(a, b) {
+    const A = new Set(a);
+    const B = new Set(b);
+    if (A.size === 0 && B.size === 0)
+        return 1;
+    let inter = 0;
+    for (const x of A)
+        if (B.has(x))
+            inter++;
+    const union = A.size + B.size - inter;
+    return union === 0 ? 1 : inter / union;
+}
+async function buildKnownLists() {
+    const registry = await loadRegistry();
+    const knownFamilies = [...registry.families.keys()];
+    const knownCapabilities = [];
+    for (const [key] of registry.layers) {
+        if (key.startsWith('capability:'))
+            knownCapabilities.push(key);
+    }
+    return { knownFamilies, knownCapabilities };
+}
+// Build a metric: for each predicted canonicalPrompt, re-route through the
+// deterministic planner and measure capability-jaccard vs the expected
+// capabilities from the training example. This is exactly what downstream
+// eval will measure, so we optimize the metric that matters.
+function makeMetric(expectedByPrompt) {
+    return async ({ prediction, example }) => {
+        const pred = prediction;
+        const canonical = (pred.canonicalPrompt ?? '').trim();
+        if (!canonical)
+            return 0;
+        const ex = example;
+        const userPrompt = typeof ex['userPrompt'] === 'string' ? ex['userPrompt'] : '';
+        const expected = expectedByPrompt.get(userPrompt) ?? [];
+        if (expected.length === 0) {
+            // no expected caps — reward length + diversity as a weak proxy
+            return canonical.length > userPrompt.length ? 0.5 : 0;
+        }
+        let plan = null;
+        try {
+            plan = await planPrompt({ prompt: canonical });
+        }
+        catch {
+            return 0;
+        }
+        const p = plan;
+        const actual = p?.kind === 'starter'
+            ? p.spec?.layers ?? []
+            : (p?.spec?.projects ?? []).flatMap((proj) => proj.layers ?? []);
+        return jaccard(actual, expected);
+    };
+}
+export async function trainNode(input) {
+    const { knownFamilies, knownCapabilities } = await buildKnownLists();
+    // Only train on ideasai traces that have expected capabilities. held-out is
+    // measurement, not training. We also skip traces where capabilityHit was
+    // already 1.0 (nothing to learn).
+    const trainables = input.traces.filter((t) => t.corpus === 'ideasai' && t.expectedCapabilities.length > 0 && t.capabilityHit < 1.0);
+    const examples = trainables.slice(0, 30).map((t) => ({
+        userPrompt: t.prompt,
+        knownFamilies,
+        knownCapabilities,
+    }));
+    const expectedByPrompt = new Map();
+    for (const t of trainables)
+        expectedByPrompt.set(t.prompt, t.expectedCapabilities);
+    const briefProgram = ax(BRIEF_SIGNATURE);
+    const metric = makeMetric(expectedByPrompt);
+    let bestScore = 0;
+    let instruction;
+    let instructionMap;
+    let demos;
+    let modelConfig;
+    let optimizerType = 'variant_b.fallback';
+    let optimizationTime = 0;
+    let totalRounds = 0;
+    let converged = false;
+    let scoreHistory;
+    if (examples.length >= 3) {
+        try {
+            const optimizer = new AxMiPRO({
+                studentAI: input.llm,
+                numTrials: 3,
+                numCandidates: 3,
+                minibatch: true,
+                minibatchSize: Math.min(6, examples.length),
+                verbose: false,
+                seed: 42,
+            });
+            optimizer.configureAuto(input.auto ?? 'light');
+            const t0 = Date.now();
+            const result = await optimizer.compile(briefProgram, examples, metric, {
+                maxMetricCalls: Math.max(examples.length * 2, 12),
+                auto: input.auto ?? 'light',
+                verbose: false,
+            });
+            optimizationTime = Date.now() - t0;
+            const opt = result.optimizedProgram;
+            if (opt) {
+                bestScore = opt.bestScore;
+                instruction = opt.instruction;
+                instructionMap = opt.instructionMap;
+                demos = opt.demos;
+                modelConfig = opt.modelConfig;
+                optimizerType = opt.optimizerType;
+                totalRounds = opt.totalRounds;
+                converged = opt.converged;
+                scoreHistory = opt.scoreHistory;
+            }
+            else if (result.bestScore !== undefined) {
+                bestScore = result.bestScore;
+            }
+        }
+        catch (err) {
+            // Rate-limits, provider blips — fall back to the corpus-mined instruction
+            // so the variant still produces an artifact.
+            // eslint-disable-next-line no-console
+            console.warn('[variant_b/train] AxMiPRO failed, using fallback:', err instanceof Error ? err.message : err);
+        }
+    }
+    // Always attach a corpus-mined instruction as a floor. This is the part that
+    // reliably moves capHit because it surfaces the exact vocabulary the
+    // deterministic planner keys off. Real optimization can only improve on it.
+    if (!instruction) {
+        instruction = buildCorpusMinedInstruction(trainables, knownCapabilities);
+        optimizerType = optimizerType === 'variant_b.fallback' ? 'variant_b.corpus-mined' : optimizerType;
+    }
+    const artifact = {
+        optimizerType,
+        bestScore,
+        instruction,
+        instructionMap,
+        demos: Array.isArray(demos) ? demos.slice(0, 8) : demos,
+        modelConfig,
+        optimizationTime,
+        totalRounds,
+        converged,
+        scoreHistory,
+        artifactFormatVersion: 1,
+        signature: BRIEF_SIGNATURE,
+        promptShape: 'brief',
+        trainedAt: new Date().toISOString(),
+        trainingTraceCount: trainables.length,
+        knownFamilies,
+        knownCapabilities,
+    };
+    await mkdir(path.dirname(input.outPath), { recursive: true });
+    await writeFile(input.outPath, JSON.stringify(artifact, null, 2));
+    return { optimizedProgram: artifact, outPath: input.outPath };
+}
+// Mine the training traces to learn the high-signal vocabulary. For each
+// expected capability that was missed, collect the keywords from the original
+// prompt that co-occur with it. Build those into a tight instruction that
+// tells the brief agent to SURFACE the capability name explicitly when it
+// sees those keywords. This is the deterministic floor the optimizer must
+// beat. In practice it already lifts ideasaiCapHit materially because the
+// brief's canonicalPrompt will contain the exact layer IDs the planner scans.
+export function buildCorpusMinedInstruction(trainables, knownCapabilities) {
+    const capToKeywords = new Map();
+    for (const t of trainables) {
+        const words = t.prompt
+            .toLowerCase()
+            .replace(/[^a-z0-9\s-]/g, ' ')
+            .split(/\s+/)
+            .filter((w) => w.length >= 4);
+        for (const cap of t.expectedCapabilities) {
+            if (t.actualCapabilities.includes(cap))
+                continue; // already hit, no lesson
+            if (!capToKeywords.has(cap))
+                capToKeywords.set(cap, new Map());
+            const m = capToKeywords.get(cap);
+            for (const w of words)
+                m.set(w, (m.get(w) ?? 0) + 1);
+        }
+    }
+    const lines = [];
+    lines.push('ALWAYS name the capability IDs explicitly in canonicalPrompt when the user prompt matches.');
+    lines.push('For ambiguous AI-saas prompts, prefer fullstack-ts or nextjs-ts family.');
+    lines.push('Route rules (ordered):');
+    const entries = [...capToKeywords.entries()]
+        .map(([cap, m]) => ({ cap, top: [...m.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6).map(([w]) => w) }))
+        .filter((e) => knownCapabilities.includes(e.cap))
+        .slice(0, 12);
+    for (const { cap, top } of entries) {
+        lines.push(`- If prompt mentions any of [${top.join(', ')}] include "${cap}" in canonicalPrompt.`);
+    }
+    lines.push('ALWAYS include capability:tailwind for any UI that renders pages.');
+    lines.push('ALWAYS include capability:layout-dashboard when prompt describes analytics, tracking, monitoring, or multiple views.');
+    lines.push('ALWAYS include capability:layout-chat when prompt describes messaging, conversation, or companion UX.');
+    lines.push('ALWAYS include capability:ai-chat-ui when the product is AI-driven or talks to the user.');
+    return lines.join('\n');
+}
+//# sourceMappingURL=train.js.map

package/dist/training/variant_b/nodes/train.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"train.js","sourceRoot":"","sources":["../../../../src/training/variant_b/nodes/train.ts"],"names":[],"mappings":"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"}

package/dist/training/variant_b/run-flow.d.ts

@@ -0,0 +1,12 @@
+import type { FlowOutput } from './flow.js';
+interface RunFullFlowInput {
+    corpusPath?: string;
+    registryRoot?: string;
+    tracesDir?: string;
+    optimizedPath?: string;
+    ideasPath?: string;
+    judgePath?: string;
+    iterations?: number;
+}
+export declare function runFullFlow(input?: RunFullFlowInput): Promise<FlowOutput>;
+export {};

package/dist/training/variant_b/run-flow.js

@@ -0,0 +1,21 @@
+// runFullFlow: runs the entire AxFlow pipeline end-to-end. Used by the
+// variant_b-flow.mjs script and by the integration test. This is the
+// one-shot "do everything" entrypoint.
+import { buildVariantBFlow } from './flow.js';
+import { createLLM } from '../../lib/llm.js';
+export async function runFullFlow(input = {}) {
+    const llm = createLLM();
+    const flowInstance = buildVariantBFlow();
+    const result = await flowInstance.forward(llm, {
+        corpusPath: input.corpusPath ?? 'corpus/ideasai-prompts.json',
+        registryRoot: input.registryRoot ?? 'registry',
+        tracesDir: input.tracesDir ?? '.evolve/traces',
+        optimizedPath: input.optimizedPath ?? '.evolve/optimized/brief-variant_b.json',
+        ideasPath: input.ideasPath ?? '.evolve/ideas/variant_b.json',
+        judgePath: input.judgePath ?? '.evolve/judge/variant_b.jsonl',
+        iterations: input.iterations ?? 1,
+        llm,
+    });
+    return result;
+}
+//# sourceMappingURL=run-flow.js.map

package/dist/training/variant_b/run-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-flow.js","sourceRoot":"","sources":["../../../src/training/variant_b/run-flow.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,qEAAqE;AACrE,uCAAuC;AAEvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAa5C,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAA0B,EAAE;IAC5D,MAAM,GAAG,GAAG,SAAS,EAAE,CAAA;IACvB,MAAM,YAAY,GAAG,iBAAiB,EAAE,CAAA;IACxC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE;QAC7C,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,6BAA6B;QAC7D,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,UAAU;QAC9C,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,gBAAgB;QAC9C,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,wCAAwC;QAC9E,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,8BAA8B;QAC5D,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,+BAA+B;QAC7D,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC;QACjC,GAAG;KACJ,CAAC,CAAA;IACF,OAAO,MAAoB,CAAA;AAC7B,CAAC"}

package/dist/training/variant_b/train.d.ts

@@ -0,0 +1,15 @@
+import type { SerializedOptimizedProgram } from './nodes/train.js';
+export interface RunTrainingLoopInput {
+    corpusPath: string;
+    outPath: string;
+    tracesDir?: string;
+    auto?: 'light' | 'medium' | 'heavy';
+    limit?: number;
+}
+export interface RunTrainingLoopResult {
+    optimizedProgram: SerializedOptimizedProgram;
+    outPath: string;
+    traceCount: number;
+    tracesFile: string;
+}
+export declare function runTrainingLoop(input: RunTrainingLoopInput): Promise<RunTrainingLoopResult>;

package/dist/training/variant_b/train.js

@@ -0,0 +1,37 @@
+// Public entrypoint: runTrainingLoop({ corpusPath, outPath })
+//
+// Contract (see scripts/multi-pursue-eval.mjs):
+//   - Read corpusPath (defaults to corpus/ideasai-prompts.json)
+//   - Synthesize traces via the collect node
+//   - Run the train node, which compiles AxMiPRO on the brief signature
+//   - Write serialized AxOptimizedProgram JSON to outPath
+//
+// This wraps exactly the first two nodes of the flow. The full flow lives in
+// run-flow.ts. Training is separated so the eval harness can run it without
+// paying for generate/judge/rank/promote.
+import { createLLM } from '../../lib/llm.js';
+import { collectNode } from './nodes/collect.js';
+import { trainNode } from './nodes/train.js';
+export async function runTrainingLoop(input) {
+    const tracesDir = input.tracesDir ?? '.evolve/traces';
+    const collect = await collectNode({
+        corpusPath: input.corpusPath,
+        tracesDir,
+        limit: input.limit,
+        includeHeldOut: true,
+    });
+    const llm = createLLM();
+    const train = await trainNode({
+        traces: collect.traces,
+        outPath: input.outPath,
+        llm,
+        auto: input.auto ?? 'light',
+    });
+    return {
+        optimizedProgram: train.optimizedProgram,
+        outPath: train.outPath,
+        traceCount: collect.traces.length,
+        tracesFile: collect.tracesFile,
+    };
+}
+//# sourceMappingURL=train.js.map

package/dist/training/variant_b/train.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"train.js","sourceRoot":"","sources":["../../../src/training/variant_b/train.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,gDAAgD;AAChD,gEAAgE;AAChE,6CAA6C;AAC7C,wEAAwE;AACxE,0DAA0D;AAC1D,EAAE;AACF,6EAA6E;AAC7E,4EAA4E;AAC5E,0CAA0C;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAkB5C,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAA2B;IAC/D,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,gBAAgB,CAAA;IACrD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC;QAChC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,SAAS;QACT,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,cAAc,EAAE,IAAI;KACrB,CAAC,CAAA;IACF,MAAM,GAAG,GAAG,SAAS,EAAE,CAAA;IACvB,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG;QACH,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,OAAO;KAC5B,CAAC,CAAA;IACF,OAAO;QACL,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM;QACjC,UAAU,EAAE,OAAO,CAAC,UAAU;KAC/B,CAAA;AACH,CAAC"}

package/dist/types/registry-schemas.generated.d.ts

@@ -0,0 +1,105 @@
+export interface Buildhints {
+    "pages"?: Array<string>;
+    "apiRoutes"?: Array<string>;
+    "components"?: Array<string>;
+    "dataModels"?: Array<string>;
+    "integrations"?: Array<string>;
+    "architectureNotes"?: Array<string>;
+    "firstSteps"?: Array<string>;
+    "gotchas"?: Array<string>;
+    "whenToUse"?: string;
+    "placeholders"?: Array<{
+        "path": string;
+        "description": string;
+    }>;
+}
+export interface Family {
+    "id": string;
+    "description": string;
+    "tags": Array<string>;
+    "taxonomy"?: {
+        "language"?: string;
+        "runtime"?: string;
+        "surface"?: string;
+    };
+    "slots"?: Record<string, {
+        "options"?: Array<string>;
+        "default"?: string;
+    }>;
+    "requires"?: Array<string>;
+    "defaults"?: Record<string, unknown>;
+    "files"?: Array<{
+        "source": string;
+        "target": string;
+    }>;
+    "validationChecks"?: Array<{
+        "type": "file-exists" | "node-syntax" | "http-start" | "command-success" | "python-compile";
+        "path"?: string;
+        "command"?: Array<string>;
+        "expect"?: string;
+        "env"?: Record<string, unknown>;
+        "port"?: string;
+        "runOnce"?: boolean;
+    }>;
+    "contextHints"?: {
+        "commands"?: Array<string>;
+        "entrypoints"?: Array<string>;
+        "preview"?: unknown;
+        "extensionPoints"?: Array<string>;
+    };
+    "keywords"?: Array<string>;
+    "tieredKeywords"?: {
+        "tier1"?: Array<string>;
+        "tier2"?: Array<string>;
+        "tier3"?: Array<string>;
+        "archetypes"?: Array<string>;
+    };
+    "scoring"?: {
+        "boost"?: Record<string, number>;
+    };
+    "buildHints"?: Buildhints;
+}
+export interface Layer {
+    "id": string;
+    "description": string;
+    "group"?: string;
+    "slot"?: string;
+    "appliesTo"?: Array<string>;
+    "defaults"?: Record<string, unknown>;
+    "files"?: Array<{
+        "source": string;
+        "target": string;
+    }>;
+    "validationChecks"?: Array<Record<string, unknown>>;
+    "contextHints"?: {
+        "commands"?: Array<string>;
+        "entrypoints"?: Array<string>;
+        "extensionPoints"?: Array<string>;
+    };
+    "keywords"?: Array<string>;
+    "tieredKeywords"?: {
+        "tier1"?: Array<string>;
+        "tier2"?: Array<string>;
+        "tier3"?: Array<string>;
+        "archetypes"?: Array<string>;
+    };
+    "capabilityRequires"?: Array<string>;
+    "variants"?: Array<string>;
+    "buildHints"?: Buildhints;
+    "packageDeps"?: {
+        "dependencies"?: Record<string, string>;
+        "devDependencies"?: Record<string, string>;
+    };
+}
+export interface Partner {
+    "id": string;
+    "description": string;
+    "appliesTo"?: Array<string>;
+    "defaults"?: Record<string, unknown>;
+    "slotDefaults"?: Record<string, string>;
+    "files"?: Array<{
+        "source": string;
+        "target": string;
+    }>;
+    "buildHints"?: Buildhints;
+}

package/dist/types/registry-schemas.generated.js

@@ -0,0 +1,5 @@
+// AUTO-GENERATED from registry/_schemas/*.json by scripts/gen-types-from-schemas.mjs.
+// Do not edit by hand — re-run the generator after schema changes.
+// `pnpm test` enforces this file is in sync via scripts/gen-types-from-schemas.mjs --check.
+export {};
+//# sourceMappingURL=registry-schemas.generated.js.map

package/dist/types/registry-schemas.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-schemas.generated.js","sourceRoot":"","sources":["../../src/types/registry-schemas.generated.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,mEAAmE;AACnE,4FAA4F"}

package/dist/types.d.ts

@@ -75,6 +75,13 @@ export interface FamilyManifest extends ManifestBase {
     scoring?: {
         boost?: Record<string, number>;
     };
+    /**
+     * Domain-specific build guidance — first moves, gotchas, architecture
+     * notes — written into the composed scaffold's AGENTS.md. Family-level
+     * hints cover runtime-specific UX (e.g. "bun add" vs "pnpm add",
+     * "deno.json tasks", "run wasm-pack first").
+     */
+    buildHints?: BuildHints;
 }
 export interface LayerManifest extends ManifestBase {
     kind: 'layer';
@@ -83,18 +90,49 @@ export interface LayerManifest extends ManifestBase {
     appliesTo?: string[];
     /** Keywords for capability auto-detection. detectCapabilities scores prompts against these. */
     keywords?: string[];
+    /**
+     * Tiered keywords (same shape as FamilyManifest.tieredKeywords). Capability
+     * manifests use `tieredKeywords.archetypes` to declare their archetype
+     * signal arrays — the single source of truth for `implicit-caps.ts` in
+     * future; today it's enforced-parity with signals.ts arrays via a test.
+     */
+    tieredKeywords?: {
+        tier1?: string[];
+        tier2?: string[];
+        tier3?: string[];
+        archetypes?: string[];
+    };
     /** Other capability IDs that must be present when this capability is attached. */
     capabilityRequires?: string[];
     /** Available variant directory names under variants/. When present, compose picks one deterministically. */
     variants?: string[];
     /** Concrete build suggestions for the AI agent when this capability is active. */
     buildHints?: BuildHints;
+    /**
+     * Packages this layer contributes to the composed scaffold's root package.json.
+     * Merged into the family's package.json at compose time so capability layers
+     * can actually ship their runtime deps instead of scaffolding config files and
+     * expecting the agent to figure out which package to install.
+     *
+     * Added 2026-04-20 in response to blueprint-agent bug report #4: agents were
+     * installing snarkjs/circomlibjs 4× on zk-mixer-ui because no capability
+     * layer had a way to declare deps.
+     */
+    packageDeps?: {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+    };
 }
 export interface PartnerManifest extends ManifestBase {
     kind: 'partner';
     group: null;
     appliesTo?: string[];
     slotDefaults?: Record<string, string>;
+    /**
+     * Partner-specific agent guidance — which SDK to use, which env vars
+     * to set, ecosystem gotchas. Written into composed scaffold's AGENTS.md.
+     */
+    buildHints?: BuildHints;
 }
 export interface Registry {
     families: Map<string, FamilyManifest>;
@@ -128,10 +166,50 @@ export interface BuildPlan {
     dataModels: string[];
     integrations: string[];
     firstMoves: string[];
+    /**
+     * Domain-specific first moves declared by manifests (family + attached
+     * capability layers + partner). Each entry is attributed to its source
+     * (e.g. `family:bun-http: Use bun add not pnpm add`). Rendered in
+     * AGENTS.md as '## Domain first moves'.
+     */
+    domainFirstSteps: Array<{
+        source: string;
+        step: string;
+    }>;
+    /**
+     * Runtime-specific traps from manifest buildHints. Rendered in
+     * AGENTS.md as '## Gotchas' so an agent sees them before hitting them.
+     */
+    domainGotchas: Array<{
+        source: string;
+        note: string;
+    }>;
+    /**
+     * Default/placeholder files the agent MUST replace with product-specific
+     * content (blueprint-agent Gen 27 finding #6). Rendered in AGENTS.md as
+     * '## Placeholders — MUST replace'.
+     */
+    placeholders: Array<{
+        source: string;
+        path: string;
+        description: string;
+    }>;
     /** Natural-language design directives for the AI agent. Not CSS — English rules about aesthetics. */
     designDirective: string | null;
     /** shadcn preset code for `pnpm dlx shadcn@latest init --preset <code>` */
     presetCode?: string | null;
+    /** Vision statement (2-4 sentences) — only populated when a product brief was generated. */
+    vision?: string;
+    /** Ordered major phases with success criteria. Populated from product brief. */
+    milestones?: string[];
+    /** Unit/integration test plan items. Populated from product brief. */
+    testingPlan?: string[];
+    /** End-to-end user-journey coverage items. Populated from product brief. */
+    e2ePlan?: string[];
+    /** Red-team / audit surface concerns. Populated from product brief. */
+    securityConcerns?: string[];
+    /** Things the user should clarify. Populated from product brief. */
+    openQuestions?: string[];
 }
 export interface BuildHints {
     pages?: string[];
@@ -140,6 +218,44 @@ export interface BuildHints {
     dataModels?: string[];
     integrations?: string[];
     architectureNotes?: string[];
+    /**
+     * Domain-specific first moves an agent should make on this scaffold.
+     * Rendered as `## First moves` in AGENTS.md. Write concrete commands +
+     * file paths, not generic "familiarize yourself with the code" advice.
+     * Example (bun-http): "Use `bun add` not `pnpm add` for deps".
+     */
+    firstSteps?: string[];
+    /**
+     * Non-obvious traps specific to this runtime/stack. Rendered as
+     * `## Gotchas` in AGENTS.md. Each entry should name the failure mode
+     * + the fix. Not general "be careful" advice.
+     * Example (wasm-rust): "Proving keys are multi-MB — gitignore pkg/ and
+     * host the .wasm under public/ so Vite serves it."
+     */
+    gotchas?: string[];
+    /**
+     * One sentence on WHY an agent attaches or uses this surface.
+     * Rendered as the intro line of relevant AGENTS.md sections.
+     */
+    whenToUse?: string;
+    /**
+     * Scaffold files that ship DEFAULT / PLACEHOLDER content — the agent must
+     * replace them with product-specific behavior, not treat them as working
+     * infrastructure. Blueprint-agent Gen 27 finding #6: 4/5 failing sessions
+     * left default KPI dashboards unchanged because AGENTS.md didn't name them.
+     *
+     * Each entry is `{path, description}` — the path is relative to the
+     * composed scaffold root; description names what the default renders and
+     * what the agent should replace it with.
+     *
+     * Example (nextjs-ts):
+     * [{ path: 'app/dashboard/page.tsx', description: 'Default KPI cards
+     *   (Revenue, Users). Replace with the product's primary view.' }]
+     */
+    placeholders?: Array<{
+        path: string;
+        description: string;
+    }>;
 }
 export interface ProjectEntry {
     id?: string;
@@ -205,12 +321,16 @@ export interface StarterPromptPlan {
     confidence: Confidence;
     reasons: string[];
     spec: ComposeSpec;
+    /** Opaque product brief object attached when planPrompt was called with brief: true. */
+    brief?: unknown;
 }
 export interface WorkspacePromptPlan {
     kind: 'workspace';
     confidence: Confidence;
     reasons: string[];
     spec: WorkspaceSpec;
+    /** Opaque product brief object attached when planPrompt was called with brief: true. */
+    brief?: unknown;
 }
 export type PromptPlan = StarterPromptPlan | WorkspacePromptPlan;
 export interface ComposeComponents {
@@ -224,6 +344,21 @@ export interface ComposeResult {
     filesWritten: string[];
     composeReportPath: string;
     components: ComposeComponents;
+    /**
+     * Per-family prompt fragment — a concatenated string of any
+     * `registry/families/<id>/prompt-fragment.md` (family) +
+     * `registry/partners/<id>/prompt-fragment.md` (partner). Consumers
+     * (blueprint-agent etc.) can splice this into their own system prompt
+     * without reading the registry directly. Empty string when no family/
+     * partner ships a fragment.
+     */
+    promptFragment: string;
+    /**
+     * Path to the composed SBOM (CycloneDX 1.5). null if the scaffold has
+     * no manifested deps (e.g. Go/Rust without Cargo.toml). Consumers feed
+     * this to supply-chain scanners.
+     */
+    sbomPath: string | null;
 }
 export interface ValidationCheckResult {
     ok: boolean;