@cubis/foundry 0.3.78 → 0.3.80

package/dist/cli/core.js

@@ -27,8 +27,16 @@ const ENGINEERING_RULES_FILE_BLOCK_START_RE = /<!--\s*cbx:engineering:rules:star
 const ENGINEERING_RULES_FILE_BLOCK_END_RE = /<!--\s*cbx:engineering:rules:end\s*-->/g;
 const ENGINEERING_ARCHITECTURE_BLOCK_START_RE = /<!--\s*cbx:architecture:rules:start[^>]*-->/g;
 const ENGINEERING_ARCHITECTURE_BLOCK_END_RE = /<!--\s*cbx:architecture:rules:end\s*-->/g;
+const PRODUCT_FOUNDATION_BLOCK_START_RE = /<!--\s*cbx:product:foundation:start[^>]*-->/g;
+const PRODUCT_FOUNDATION_BLOCK_END_RE = /<!--\s*cbx:product:foundation:end\s*-->/g;
+const ARCHITECTURE_DOC_BLOCK_START_RE = /<!--\s*cbx:architecture:doc:start[^>]*-->/g;
+const ARCHITECTURE_DOC_BLOCK_END_RE = /<!--\s*cbx:architecture:doc:end\s*-->/g;
 const TECH_ARCHITECTURE_BLOCK_START_RE = /<!--\s*cbx:architecture:tech:start[^>]*-->/g;
 const TECH_ARCHITECTURE_BLOCK_END_RE = /<!--\s*cbx:architecture:tech:end\s*-->/g;
+const ROADMAP_FOUNDATION_BLOCK_START_RE = /<!--\s*cbx:roadmap:foundation:start[^>]*-->/g;
+const ROADMAP_FOUNDATION_BLOCK_END_RE = /<!--\s*cbx:roadmap:foundation:end\s*-->/g;
+const FOUNDATION_DOCS_DIR = path.join("docs", "foundation");
+const FOUNDATION_ADR_DIR = path.join(FOUNDATION_DOCS_DIR, "adr");
 const COPILOT_ALLOWED_SKILL_FRONTMATTER_KEYS = new Set([
     "compatibility",
     "description",
@@ -954,6 +962,154 @@ function buildArchitectureMermaid(snapshot) {
     }
     return lines.join("\n");
 }
+function inferProductFoundationProfile(snapshot, specRoots = []) {
+    const appRoots = (snapshot.architectureByApp || [])
+        .map((item) => item.rootPath)
+        .filter((value) => value && value !== ".");
+    const primarySurfaces = appRoots.length > 0 ? appRoots : snapshot.topDirs.slice(0, 6);
+    const userPersonas = [];
+    if (snapshot.frameworks.includes("Flutter")) {
+        userPersonas.push("End users interacting through mobile or desktop app surfaces");
+    }
+    if (snapshot.frameworks.includes("Next.js") ||
+        snapshot.frameworks.includes("React") ||
+        snapshot.topDirs.includes("web")) {
+        userPersonas.push("Browser users and internal operators using web-facing flows");
+    }
+    if (snapshot.frameworks.includes("NestJS") || snapshot.topDirs.includes("api")) {
+        userPersonas.push("Internal services, operators, or partner systems consuming API boundaries");
+    }
+    if (userPersonas.length === 0) {
+        userPersonas.push("Project stakeholders are not obvious from the repo alone; refine personas from product context before major feature work.");
+    }
+    const coreJourneys = [];
+    if (specRoots.length > 0) {
+        coreJourneys.push(`Active implementation themes are reflected in current spec packs: ${specRoots.join(", ")}.`);
+    }
+    if (primarySurfaces.length > 0) {
+        coreJourneys.push(`Primary product surfaces currently live in: ${primarySurfaces.join(", ")}.`);
+    }
+    if (snapshot.isMcpServer || snapshot.mcpSignals.length > 0) {
+        coreJourneys.push("Tool-assisted and MCP-driven workflows are part of the operating model and should stay stable.");
+    }
+    if (coreJourneys.length === 0) {
+        coreJourneys.push("Repository evidence is thin; capture the primary user journeys here before scaling the codebase further.");
+    }
+    const successSignals = [
+        "Feature work should stay aligned to explicit user or operator value, not speculative abstractions.",
+        "Architecture changes should reduce onboarding, debugging, and testing cost over time.",
+    ];
+    if (snapshot.cicdSignals.length > 0) {
+        successSignals.push(`Delivery flows already rely on ${snapshot.cicdSignals.join(", ")} signals; keep release friction low for that pipeline.`);
+    }
+    return {
+        productScope: snapshot.readmeExcerpt ||
+            "No explicit product summary was detected from repo docs. Replace this with a concise product statement when better context exists.",
+        primarySurfaces,
+        userPersonas,
+        coreJourneys,
+        successSignals,
+    };
+}
+function buildProductFoundationSection(snapshot, specRoots = []) {
+    const profile = inferProductFoundationProfile(snapshot, specRoots);
+    const hash = hashStableObject(profile);
+    return [
+        `<!-- cbx:product:foundation:start version=1 profile=${hash} -->`,
+        "## Product Foundation (auto-managed)",
+        "",
+        "### Product Scope",
+        profile.productScope,
+        "",
+        "### Primary Surfaces",
+        ...(profile.primarySurfaces.length > 0
+            ? profile.primarySurfaces.map((item) => `- ${item}`)
+            : ["- No primary surfaces were detected automatically."]),
+        "",
+        "### Users and Operators",
+        ...profile.userPersonas.map((item) => `- ${item}`),
+        "",
+        "### Core Journeys",
+        ...profile.coreJourneys.map((item) => `- ${item}`),
+        "",
+        "### Success Signals",
+        ...profile.successSignals.map((item) => `- ${item}`),
+        "",
+        "### Product Guardrails",
+        "- Keep product intent stable across future features so agents do not optimize for the wrong user outcome.",
+        "- Refresh this managed section when scope, personas, operating model, or success metrics change materially.",
+        "<!-- cbx:product:foundation:end -->",
+        "",
+    ].join("\n");
+}
+function inferArchitectureDocProfile(snapshot, specRoots = []) {
+    const contract = inferArchitectureContractProfile(snapshot);
+    const architectureSignals = (snapshot.architectureByApp || []).map((item) => {
+        const label = item.rootPath === "." ? "repo root" : item.rootPath;
+        const signals = item.architectureSignals && item.architectureSignals.length > 0
+            ? item.architectureSignals.join(", ")
+            : "not enough signals to classify";
+        return `${label}: ${signals}`;
+    });
+    const decisionAreas = [
+        "Module boundaries and dependency direction",
+        "Design-system ownership and reusable primitives",
+        "Testing and validation expectations by runtime boundary",
+    ];
+    if (specRoots.length > 0) {
+        decisionAreas.push(`Active specs that may influence upcoming architecture work: ${specRoots.join(", ")}.`);
+    }
+    return {
+        style: contract.style,
+        designSystemSource: contract.designSystemSource,
+        moduleBoundaries: contract.moduleBoundaries,
+        architectureSignals,
+        decisionAreas,
+        scalingConstraints: contract.scalingConstraints,
+        testingStrategy: contract.testingStrategy,
+    };
+}
+function buildArchitectureDocSection(snapshot, specRoots = []) {
+    const profile = inferArchitectureDocProfile(snapshot, specRoots);
+    const hash = hashStableObject(profile);
+    return [
+        `<!-- cbx:architecture:doc:start version=1 profile=${hash} -->`,
+        "## Accepted Architecture Backbone (auto-managed)",
+        "",
+        "### System Overview",
+        `- Accepted style: ${profile.style}.`,
+        `- Design-system source of truth: ${profile.designSystemSource}`,
+        "",
+        "### Bounded Contexts and Module Boundaries",
+        ...(profile.moduleBoundaries.length > 0
+            ? profile.moduleBoundaries.map((item) => `- ${item}`)
+            : ["- No strong top-level module boundaries were detected automatically."]),
+        "",
+        "### Architecture Signals by Surface",
+        ...(profile.architectureSignals.length > 0
+            ? profile.architectureSignals.map((item) => `- ${item}`)
+            : ["- No app-level architecture signals were inferred from the repo scan."]),
+        "",
+        "### Decision Areas to Preserve",
+        ...profile.decisionAreas.map((item) => `- ${item}`),
+        "",
+        "### Scalability and Reliability Notes",
+        ...profile.scalingConstraints.map((item) => `- ${item}`),
+        "",
+        "### Testing and Operability",
+        ...profile.testingStrategy.map((item) => `- ${item}`),
+        "",
+        "### ADR Linkage",
+        "- Keep durable architecture decisions in `docs/adr/` and summarize the active decision set here.",
+        "",
+        "### Mermaid Diagram",
+        "```mermaid",
+        buildArchitectureDocMermaid(snapshot),
+        "```",
+        "<!-- cbx:architecture:doc:end -->",
+        "",
+    ].join("\n");
+}
 function buildEngineeringArchitectureSection(snapshot) {
     const profile = inferArchitectureContractProfile(snapshot);
     const hash = hashStableObject(profile);
@@ -973,11 +1129,30 @@ function buildEngineeringArchitectureSection(snapshot) {
         ...profile.testingStrategy.map((rule) => `  - ${rule}`),
         "- Doc refresh policy:",
         "  - Update these managed sections when architecture, scale, boundaries, design-system rules, or testing strategy changes.",
-        "  - For non-trivial work, read this file before planning and read TECH.md next.",
+        `  - For non-trivial work, read ${FOUNDATION_DOCS_DIR}/PRODUCT.md, ENGINEERING_RULES.md, ${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md, and ${FOUNDATION_DOCS_DIR}/TECH.md in that order when they exist.`,
         "<!-- cbx:architecture:rules:end -->",
         "",
     ].join("\n");
 }
+function buildArchitectureDocMermaid(snapshot) {
+    const topDirs = snapshot.topDirs.slice(0, 5);
+    const lines = [
+        "flowchart LR",
+        '  product["Product Intent"] --> rules["Engineering Rules"]',
+        '  product --> arch["Architecture Backbone"]',
+        '  arch --> tech["Current Tech Snapshot"]',
+    ];
+    if (topDirs.length > 0) {
+        for (let index = 0; index < topDirs.length; index += 1) {
+            const dir = topDirs[index];
+            const nodeName = `D${index}`;
+            lines.push(`  arch --> ${nodeName}["${dir}/"]`);
+        }
+    }
+    lines.push('  arch --> adr["docs/adr"]');
+    lines.push('  product --> specs["docs/specs"]');
+    return lines.join("\n");
+}
 function buildTechArchitectureSection(snapshot) {
     const profile = inferArchitectureContractProfile(snapshot);
     const payload = {
@@ -1030,6 +1205,48 @@ function buildTechArchitectureSection(snapshot) {
         "",
     ].join("\n");
 }
+function buildRoadmapFoundationSection(snapshot, specRoots = []) {
+    const payload = {
+        topDirs: snapshot.topDirs,
+        frameworks: snapshot.frameworks,
+        specRoots,
+    };
+    const hash = hashStableObject(payload);
+    const nowItems = specRoots.length > 0
+        ? specRoots.map((item) => `Track active change planning in \`${item}\`.`)
+        : [
+            "No active spec packs detected. Create a spec pack before starting the next non-trivial feature or migration.",
+        ];
+    const nextItems = [];
+    if (snapshot.frameworks.length > 0) {
+        nextItems.push(`Keep shared conventions stable across the current stack: ${snapshot.frameworks.join(", ")}.`);
+    }
+    if (snapshot.cicdSignals.length > 0) {
+        nextItems.push(`Preserve release compatibility with the detected delivery surfaces: ${snapshot.cicdSignals.join(", ")}.`);
+    }
+    if (nextItems.length === 0) {
+        nextItems.push("Document the next scaling milestones here once product direction and architecture constraints are clearer.");
+    }
+    return [
+        `<!-- cbx:roadmap:foundation:start version=1 profile=${hash} -->`,
+        "## Delivery Backbone (auto-managed)",
+        "",
+        "### Now",
+        ...nowItems.map((item) => `- ${item}`),
+        "",
+        "### Next",
+        ...nextItems.map((item) => `- ${item}`),
+        "",
+        "### Later",
+        "- Use this section for medium-term scaling themes, major migrations, or cross-team architecture investments.",
+        "",
+        "### Backbone Maintenance",
+        `- Keep ${FOUNDATION_DOCS_DIR}/PRODUCT.md, ${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md, ENGINEERING_RULES.md, and ${FOUNDATION_DOCS_DIR}/TECH.md aligned when direction or structure changes.`,
+        "- Link major roadmap themes back to specs and ADRs instead of burying them in chat-only planning.",
+        "<!-- cbx:roadmap:foundation:end -->",
+        "",
+    ].join("\n");
+}
 function buildEngineeringRulesTemplate() {
     return [
         "# Engineering Rules",
@@ -1131,17 +1348,139 @@ function buildEngineeringRulesTemplate() {
         "",
     ].join("\n");
 }
-function buildEngineeringRulesManagedBlock({ platform, engineeringRulesFilePath, techMdFilePath, ruleFilePath, }) {
+function buildProductTemplate(snapshot, specRoots = []) {
+    return [
+        "# Product",
+        "",
+        "This file is the durable product backbone for the project.",
+        "",
+        buildProductFoundationSection(snapshot, specRoots).trimEnd(),
+        "",
+    ].join("\n");
+}
+function buildArchitectureDocTemplate(snapshot, specRoots = []) {
+    return [
+        "# Architecture",
+        "",
+        "This file captures the accepted architecture backbone for the project.",
+        "",
+        buildArchitectureDocSection(snapshot, specRoots).trimEnd(),
+        "",
+    ].join("\n");
+}
+function buildRoadmapTemplate(snapshot, specRoots = []) {
+    return [
+        "# Roadmap",
+        "",
+        "This file captures the living delivery backbone for medium-term product and architecture work.",
+        "",
+        buildRoadmapFoundationSection(snapshot, specRoots).trimEnd(),
+        "",
+    ].join("\n");
+}
+function buildProductBuildSkeleton() {
+    return [
+        "# Product",
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        "<!-- cbx:product:foundation:start version=1 profile=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <codex|claude|gemini|copilot>`.",
+        "<!-- cbx:product:foundation:end -->",
+        "",
+    ].join("\n");
+}
+function buildArchitectureBuildSkeleton() {
+    return [
+        "# Architecture",
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        "<!-- cbx:architecture:doc:start version=1 profile=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <codex|claude|gemini|copilot>`.",
+        "<!-- cbx:architecture:doc:end -->",
+        "",
+    ].join("\n");
+}
+function buildTechBuildSkeleton() {
+    return [
+        "# TECH.md",
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        "<!-- cbx:architecture:tech:start version=1 snapshot=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <codex|claude|gemini|copilot>`.",
+        "<!-- cbx:architecture:tech:end -->",
+        "",
+    ].join("\n");
+}
+function buildAdrReadme() {
+    return [
+        "# Architecture Decision Records",
+        "",
+        "Use this directory for durable decisions that future contributors and agents need to preserve.",
+        "",
+        "## When to add an ADR",
+        "",
+        "- Architecture style or boundary changes",
+        "- Data model or persistence strategy changes",
+        "- Deployment or scaling model changes",
+        "- Design-system ownership or shared UX pattern changes",
+        "",
+        "## Suggested format",
+        "",
+        "1. Context",
+        "2. Decision",
+        "3. Consequences",
+        "4. Validation",
+        "",
+        "Start with `0000-template.md` and create numbered follow-up ADRs for accepted decisions.",
+        "",
+    ].join("\n");
+}
+function buildAdrTemplate() {
+    return [
+        "# ADR 0000: Title",
+        "",
+        "## Status",
+        "",
+        "Proposed",
+        "",
+        "## Context",
+        "",
+        "- What problem or pressure led to this decision?",
+        "",
+        "## Decision",
+        "",
+        "- What is the chosen direction?",
+        "",
+        "## Consequences",
+        "",
+        "- What tradeoffs, benefits, or costs follow from this choice?",
+        "",
+        "## Validation",
+        "",
+        "- How will the team know this decision is working?",
+        "",
+    ].join("\n");
+}
+function buildEngineeringRulesManagedBlock({ platform, productFilePath, architectureFilePath, engineeringRulesFilePath, techMdFilePath, roadmapFilePath, ruleFilePath, }) {
+    const productRef = toPosixPath(path.resolve(productFilePath));
+    const architectureRef = toPosixPath(path.resolve(architectureFilePath));
     const engineeringRef = toPosixPath(path.resolve(engineeringRulesFilePath));
     const techRef = toPosixPath(path.resolve(techMdFilePath));
+    const roadmapRef = toPosixPath(path.resolve(roadmapFilePath));
     const ruleRef = toPosixPath(path.resolve(ruleFilePath));
     return [
         `<!-- cbx:engineering:auto:start platform=${platform} version=1 -->`,
         "## Engineering Guardrails (auto-managed)",
         "Apply these before planning, coding, review, and release:",
         "",
+        `- Product backbone: \`${productRef}\``,
+        `- Accepted architecture: \`${architectureRef}\``,
         `- Required baseline: \`${engineeringRef}\``,
         `- Project tech map: \`${techRef}\``,
+        `- Delivery roadmap: \`${roadmapRef}\``,
         `- Active platform rule file: \`${ruleRef}\``,
         "",
         "Hard policy:",
@@ -1149,7 +1488,7 @@ function buildEngineeringRulesManagedBlock({ platform, engineeringRulesFilePath,
         "2. Keep architecture simple (KISS) and avoid speculative work (YAGNI).",
         "3. Apply SOLID pragmatically to reduce change risk, not add ceremony.",
         "4. Use clear naming with focused responsibilities and explicit boundaries.",
-        "5. For non-trivial work, read ENGINEERING_RULES.md first and TECH.md next before planning or implementation.",
+        `5. For non-trivial work, read ${FOUNDATION_DOCS_DIR}/PRODUCT.md, ENGINEERING_RULES.md, ${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md, and ${FOUNDATION_DOCS_DIR}/TECH.md in that order when they exist before planning or implementation.`,
         "6. Require validation evidence (lint/types/tests) before merge.",
         "7. Use Decision Log response style.",
         "8. Every Decision Log must include a `Skills Used` section listing skill, workflow, or agent names.",
@@ -1240,11 +1579,14 @@ async function upsertEngineeringRulesFile({ targetPath, template, overwrite = fa
         filePath: targetPath,
     };
 }
-async function upsertEngineeringRulesBlock({ ruleFilePath, platform, engineeringRulesFilePath, techMdFilePath, dryRun = false, }) {
+async function upsertEngineeringRulesBlock({ ruleFilePath, platform, productFilePath, architectureFilePath, engineeringRulesFilePath, techMdFilePath, roadmapFilePath, dryRun = false, }) {
     const block = buildEngineeringRulesManagedBlock({
         platform,
+        productFilePath,
+        architectureFilePath,
         engineeringRulesFilePath,
         techMdFilePath,
+        roadmapFilePath,
         ruleFilePath,
     });
     const exists = await pathExists(ruleFilePath);
@@ -1313,6 +1655,16 @@ async function upsertTaggedSectionInFile({ targetPath, initialContent, block, st
         nextContent =
             trimmed.length > 0 ? `${trimmed}\n\n${block}\n` : `${block}\n`;
     }
+    if (!exists) {
+        if (!dryRun) {
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await writeFile(targetPath, nextContent, "utf8");
+        }
+        return {
+            action: dryRun ? "would-create" : "created",
+            filePath: targetPath,
+        };
+    }
     if (nextContent === original) {
         return {
             action: "unchanged",
@@ -1334,20 +1686,41 @@ async function upsertTaggedSectionInFile({ targetPath, initialContent, block, st
         filePath: targetPath,
     };
 }
-function buildArchitectureBuildMetadata({ platform, researchMode, rulesProfileHash, techSnapshotHash, }) {
+function buildArchitectureBuildMetadata({ platform, researchMode, managedDocs, }) {
     return {
-        schemaVersion: 1,
+        schemaVersion: 3,
         generatedBy: "cbx build architecture",
         generatedAt: new Date().toISOString(),
         platform,
         researchMode,
-        rulesProfileHash,
-        techSnapshotHash,
+        managedDocs,
     };
 }
-async function ensureArchitectureDocScaffold({ workspaceRoot, snapshot, overwrite = false, dryRun = false, }) {
+async function ensureArchitectureDocScaffold({ workspaceRoot, snapshot, specRoots = [], overwrite = false, dryRun = false, }) {
+    const productPath = path.join(workspaceRoot, "PRODUCT.md");
+    const architectureDocPath = path.join(workspaceRoot, "ARCHITECTURE.md");
     const engineeringRulesPath = path.join(workspaceRoot, "ENGINEERING_RULES.md");
     const techMdPath = path.join(workspaceRoot, "TECH.md");
+    const roadmapPath = path.join(workspaceRoot, "ROADMAP.md");
+    const adrDir = path.join(workspaceRoot, "docs", "adr");
+    const adrReadmePath = path.join(adrDir, "README.md");
+    const adrTemplatePath = path.join(adrDir, "0000-template.md");
+    const productResult = await upsertTaggedSectionInFile({
+        targetPath: productPath,
+        initialContent: `${buildProductTemplate(snapshot, specRoots)}\n`,
+        block: buildProductFoundationSection(snapshot, specRoots),
+        startPattern: PRODUCT_FOUNDATION_BLOCK_START_RE,
+        endPattern: PRODUCT_FOUNDATION_BLOCK_END_RE,
+        dryRun,
+    });
+    const architectureDocResult = await upsertTaggedSectionInFile({
+        targetPath: architectureDocPath,
+        initialContent: `${buildArchitectureDocTemplate(snapshot, specRoots)}\n`,
+        block: buildArchitectureDocSection(snapshot, specRoots),
+        startPattern: ARCHITECTURE_DOC_BLOCK_START_RE,
+        endPattern: ARCHITECTURE_DOC_BLOCK_END_RE,
+        dryRun,
+    });
     const rulesTemplate = buildEngineeringRulesTemplate();
     const rulesFileResult = await upsertEngineeringRulesFile({
         targetPath: engineeringRulesPath,
@@ -1378,13 +1751,115 @@ async function ensureArchitectureDocScaffold({ workspaceRoot, snapshot, overwrit
         endPattern: TECH_ARCHITECTURE_BLOCK_END_RE,
         dryRun,
     });
+    const roadmapResult = await upsertTaggedSectionInFile({
+        targetPath: roadmapPath,
+        initialContent: `${buildRoadmapTemplate(snapshot, specRoots)}\n`,
+        block: buildRoadmapFoundationSection(snapshot, specRoots),
+        startPattern: ROADMAP_FOUNDATION_BLOCK_START_RE,
+        endPattern: ROADMAP_FOUNDATION_BLOCK_END_RE,
+        dryRun,
+    });
+    const adrReadmeResult = await writeTextFile({
+        targetPath: adrReadmePath,
+        content: `${buildAdrReadme()}\n`,
+        overwrite,
+        dryRun,
+    });
+    const adrTemplateResult = await writeTextFile({
+        targetPath: adrTemplatePath,
+        content: `${buildAdrTemplate()}\n`,
+        overwrite,
+        dryRun,
+    });
     return {
+        productPath,
+        architectureDocPath,
         engineeringRulesPath,
         techMdPath,
+        roadmapPath,
+        adrReadmePath,
+        adrTemplatePath,
+        productResult,
+        architectureDocResult,
         rulesFileResult,
         rulesArchitectureResult,
         techResult,
         techArchitectureResult,
+        roadmapResult,
+        adrReadmeResult,
+        adrTemplateResult,
+    };
+}
+async function ensureArchitectureBuildScaffold({ workspaceRoot, dryRun = false, }) {
+    const foundationRoot = path.join(workspaceRoot, FOUNDATION_DOCS_DIR);
+    const productPath = path.join(foundationRoot, "PRODUCT.md");
+    const architectureDocPath = path.join(foundationRoot, "ARCHITECTURE.md");
+    const techMdPath = path.join(foundationRoot, "TECH.md");
+    const adrDir = path.join(workspaceRoot, FOUNDATION_ADR_DIR);
+    const adrReadmePath = path.join(adrDir, "README.md");
+    const adrTemplatePath = path.join(adrDir, "0000-template.md");
+    const productResult = await upsertTaggedSectionInFile({
+        targetPath: productPath,
+        initialContent: `${buildProductBuildSkeleton()}\n`,
+        block: [
+            "<!-- cbx:product:foundation:start version=1 profile=uninitialized -->",
+            "Replace this managed section by running `cbx build architecture --platform <codex|claude|gemini|copilot>`.",
+            "<!-- cbx:product:foundation:end -->",
+            "",
+        ].join("\n"),
+        startPattern: PRODUCT_FOUNDATION_BLOCK_START_RE,
+        endPattern: PRODUCT_FOUNDATION_BLOCK_END_RE,
+        dryRun,
+    });
+    const architectureDocResult = await upsertTaggedSectionInFile({
+        targetPath: architectureDocPath,
+        initialContent: `${buildArchitectureBuildSkeleton()}\n`,
+        block: [
+            "<!-- cbx:architecture:doc:start version=1 profile=uninitialized -->",
+            "Replace this managed section by running `cbx build architecture --platform <codex|claude|gemini|copilot>`.",
+            "<!-- cbx:architecture:doc:end -->",
+            "",
+        ].join("\n"),
+        startPattern: ARCHITECTURE_DOC_BLOCK_START_RE,
+        endPattern: ARCHITECTURE_DOC_BLOCK_END_RE,
+        dryRun,
+    });
+    const techResult = await upsertTaggedSectionInFile({
+        targetPath: techMdPath,
+        initialContent: `${buildTechBuildSkeleton()}\n`,
+        block: [
+            "<!-- cbx:architecture:tech:start version=1 snapshot=uninitialized -->",
+            "Replace this managed section by running `cbx build architecture --platform <codex|claude|gemini|copilot>`.",
+            "<!-- cbx:architecture:tech:end -->",
+            "",
+        ].join("\n"),
+        startPattern: TECH_ARCHITECTURE_BLOCK_START_RE,
+        endPattern: TECH_ARCHITECTURE_BLOCK_END_RE,
+        dryRun,
+    });
+    const adrReadmeResult = await writeTextFile({
+        targetPath: adrReadmePath,
+        content: `${buildAdrReadme()}\n`,
+        overwrite: false,
+        dryRun,
+    });
+    const adrTemplateResult = await writeTextFile({
+        targetPath: adrTemplatePath,
+        content: `${buildAdrTemplate()}\n`,
+        overwrite: false,
+        dryRun,
+    });
+    return {
+        productPath,
+        architectureDocPath,
+        techMdPath,
+        adrReadmePath,
+        adrTemplatePath,
+        productResult,
+        architectureDocResult,
+        techResult,
+        adrReadmeResult,
+        adrTemplateResult,
     };
 }
 function normalizeTechPackageName(value) {
@@ -6958,14 +7433,6 @@ async function performWorkflowInstall(options, { postmanSelectionOverride = null
         dryRun,
         cwd,
     });
-    const engineeringArtifactsResult = await upsertEngineeringArtifacts({
-        platform,
-        scope: ruleScope,
-        overwrite: false,
-        dryRun,
-        skipTech: false,
-        cwd,
-    });
     const postmanSetupResult = await configurePostmanInstallArtifacts({
         platform,
         scope,
@@ -7007,7 +7474,7 @@ async function performWorkflowInstall(options, { postmanSelectionOverride = null
         bundleId,
         installResult,
         syncResult,
-        engineeringArtifactsResult,
+        engineeringArtifactsResult: null,
         postmanSetupResult,
         terminalVerificationRuleResult,
     };
@@ -7035,10 +7502,7 @@ async function runWorkflowInstall(options) {
             dryRun: result.dryRun,
         });
         printRuleSyncResult(result.syncResult);
-        printInstallEngineeringSummary({
-            engineeringResults: result.engineeringArtifactsResult.engineeringResults,
-            techResult: result.engineeringArtifactsResult.techResult,
-        });
+        printInstallDocumentationNotice();
         printPostmanSetupSummary({
             postmanSetup: result.postmanSetupResult,
         });
@@ -9897,6 +10361,11 @@ function printInstallEngineeringSummary({ engineeringResults, techResult }) {
         console.log(`- TECH scan files: ${techResult.snapshot.scannedFiles}`);
     }
 }
+function printInstallDocumentationNotice() {
+    console.log("\nProject backbone docs:");
+    console.log("- Install only wires the rule references and workflow assets.");
+    console.log(`- Use \`cbx rules init\` to scaffold ENGINEERING_RULES.md and TECH.md, or \`cbx build architecture --platform <codex|claude|gemini|copilot>\` to generate ${FOUNDATION_DOCS_DIR}/PRODUCT.md, ${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md, ${FOUNDATION_DOCS_DIR}/TECH.md, and ADR scaffolds.`);
+}
 async function upsertEngineeringArtifacts({ platform, scope, overwrite = false, skipTech = false, dryRun = false, cwd = process.cwd(), }) {
     const ruleFilePath = await resolveRuleFilePath(platform, scope, cwd);
     if (!ruleFilePath)
@@ -9906,10 +10375,10 @@ async function upsertEngineeringArtifacts({ platform, scope, overwrite = false,
     const scaffold = await ensureArchitectureDocScaffold({
         workspaceRoot,
         snapshot,
+        specRoots: [],
         overwrite,
         dryRun,
     });
-    const techMdPath = path.join(workspaceRoot, "TECH.md");
     const targets = [{ ruleFilePath }];
     if (scope === "global") {
         const workspaceRuleFile = await resolveWorkspaceRuleFileForGlobalScope(platform, cwd);
@@ -9924,8 +10393,11 @@ async function upsertEngineeringArtifacts({ platform, scope, overwrite = false,
         const blockResult = await upsertEngineeringRulesBlock({
             ruleFilePath: target.ruleFilePath,
             platform,
+            productFilePath: scaffold.productPath,
+            architectureFilePath: scaffold.architectureDocPath,
             engineeringRulesFilePath: scaffold.engineeringRulesPath,
-            techMdFilePath: techMdPath,
+            techMdFilePath: scaffold.techMdPath,
+            roadmapFilePath: scaffold.roadmapPath,
             dryRun,
         });
         engineeringResults.push({
@@ -10043,6 +10515,61 @@ async function listSpecPackRoots(workspaceRoot) {
         .sort((a, b) => a.localeCompare(b))
         .slice(0, 8);
 }
+async function resolveArchitectureInspectionAnchors(workspaceRoot, snapshot, specRoots) {
+    const seen = new Set();
+    const ordered = [];
+    const pushCandidate = async (relativePath) => {
+        const normalized = toPosixPath(relativePath);
+        if (!normalized || seen.has(normalized))
+            return;
+        if (!(await pathExists(path.join(workspaceRoot, relativePath))))
+            return;
+        seen.add(normalized);
+        ordered.push(normalized);
+    };
+    for (const candidate of [
+        "README.md",
+        "package.json",
+        "pubspec.yaml",
+        "go.mod",
+        "pyproject.toml",
+        "Cargo.toml",
+        "Dockerfile",
+        "docker-compose.yml",
+        "docker-compose.yaml",
+        "compose.yaml",
+        "cbx_config.json",
+        ".vscode/mcp.json",
+        ".gemini/settings.json",
+    ]) {
+        await pushCandidate(candidate);
+    }
+    for (const specRoot of specRoots.slice(0, 4)) {
+        await pushCandidate(specRoot);
+    }
+    for (const app of snapshot.architectureByApp || []) {
+        if (!app?.rootPath || app.rootPath === ".")
+            continue;
+        await pushCandidate(app.rootPath);
+        for (const child of [
+            "README.md",
+            "src",
+            "lib",
+            "app",
+            "prisma",
+            "migrations",
+            "test",
+            "tests",
+            "docs",
+        ]) {
+            await pushCandidate(path.join(app.rootPath, child));
+        }
+    }
+    for (const dir of snapshot.topDirs || []) {
+        await pushCandidate(dir);
+    }
+    return ordered.slice(0, 18);
+}
 function resolveArchitectureConditionalSkills(snapshot, specRoots, researchMode) {
     const conditional = [];
     const frameworks = new Set(snapshot.frameworks || []);
@@ -10087,9 +10614,12 @@ async function resolveArchitectureSkillPathHints(platform, cwd, skillIds) {
         .map((skillId) => path.join(skillsDir, skillId, "SKILL.md"))
         .map((filePath) => toPosixPath(path.relative(findWorkspaceRoot(cwd), filePath)));
 }
-function buildArchitecturePrompt({ platform, workspaceRoot, snapshot, specRoots, researchMode, coreSkills, conditionalSkills, skillPathHints, }) {
-    const rulesPath = "ENGINEERING_RULES.md";
-    const techPath = "TECH.md";
+function buildArchitecturePrompt({ platform, workspaceRoot, snapshot, specRoots, inspectionAnchors, researchMode, coreSkills, conditionalSkills, skillPathHints, }) {
+    const productPath = `${FOUNDATION_DOCS_DIR}/PRODUCT.md`;
+    const architecturePath = `${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md`;
+    const techPath = `${FOUNDATION_DOCS_DIR}/TECH.md`;
+    const adrReadmePath = `${FOUNDATION_ADR_DIR}/README.md`;
+    const adrTemplatePath = `${FOUNDATION_ADR_DIR}/0000-template.md`;
     const architectureSignals = snapshot.architectureByApp
         .filter((item) => (item.architectureSignals || []).length > 0)
         .map((item) => {
@@ -10100,9 +10630,9 @@ function buildArchitecturePrompt({ platform, workspaceRoot, snapshot, specRoots,
         `You are running inside ${platform}.`,
         "",
         "Objective:",
-        `- Inspect the repository at ${toPosixPath(workspaceRoot)} and refresh the managed architecture sections in ${rulesPath} and ${techPath}.`,
-        "- Keep ENGINEERING_RULES.md normative and TECH.md descriptive.",
-        "- Preserve manual content outside the managed `cbx:architecture:*` markers.",
+        `- Inspect the repository at ${toPosixPath(workspaceRoot)} and author or refresh the core foundation docs in ${productPath}, ${architecturePath}, ${techPath}, ${adrReadmePath}, and ${adrTemplatePath}.`,
+        "- The content should be primarily AI-authored from repository inspection, not copied from placeholder scaffolding.",
+        "- Preserve manual content outside the managed `cbx:*` markers.",
         "",
         "Required skill bundle:",
         `- Load these exact skill IDs first: ${coreSkills.map((skillId) => `\`${skillId}\``).join(", ")}`,
@@ -10121,24 +10651,33 @@ function buildArchitecturePrompt({ platform, workspaceRoot, snapshot, specRoots,
         architectureSignals.length > 0
             ? `- Architecture signals: ${architectureSignals.join(" | ")}`
             : "- Architecture signals: none confidently inferred from the repo scan",
+        `- Entry points: ${snapshot.entryPoints.length > 0 ? snapshot.entryPoints.slice(0, 8).join(" | ") : "none detected"}`,
+        `- Key scripts: ${snapshot.keyScripts.length > 0 ? snapshot.keyScripts.slice(0, 8).map((item) => `${item.name}=${item.command}`).join(" | ") : "none detected"}`,
+        `- Inspection anchors: ${inspectionAnchors.length > 0 ? inspectionAnchors.join(", ") : "no concrete anchors detected; inspect the repo root, main source trees, and manifest files manually"}`,
         "",
         "Execution contract:",
-        "1. Read ENGINEERING_RULES.md first if present, then read TECH.md.",
-        "2. Inspect the repo before making architecture claims.",
-        "3. Update only the content between the existing `cbx:architecture:rules` and `cbx:architecture:tech` markers.",
-        "4. Keep the marker lines themselves intact, including their hash metadata.",
-        "5. In ENGINEERING_RULES.md, state architecture style, dependency rules, feature or module structure rules, design-system source of truth, testability expectations, and doc refresh policy.",
-        "6. In TECH.md, update architecture snapshot, module or app topology, flow narratives, Mermaid diagrams, and scaling or deployment notes.",
+        "1. Inspect the repository first before writing any backbone doc content. Derive structure, product surfaces, runtime boundaries, and technical constraints from the actual codebase.",
+        "2. Complete a real inspection pass before drafting. At minimum, inspect the concrete anchors listed above, plus any adjacent directories needed to understand the main execution paths, data boundaries, and integration surfaces.",
+        "3. Do not infer architecture from filenames alone when you can open representative files. Read enough source to validate the main app boundaries, runtime flows, and persistence/integration patterns.",
+        `4. Then read ${productPath}, ${architecturePath}, and ${techPath} in that order when they exist so you can preserve useful manual context and update existing managed sections cleanly.`,
+        `5. Replace or update only the content between the existing managed markers in ${productPath}, ${architecturePath}, and ${techPath}. Do not append a second marker block.`,
+        `6. In ${productPath}, write a concrete product foundation: product purpose, primary users/operators, main journeys, business capabilities, operational constraints, and what future contributors must preserve.`,
+        `7. In ${architecturePath}, write a lean but detailed architecture backbone in a pragmatic arc42/C4 style: system purpose and constraints, bounded contexts, major building blocks, dependency rules, data and integration boundaries, runtime flows, deployment/operability notes, testing/debugging strategy, and only the diagram levels that add real value.`,
+        `8. In ${techPath}, write the developer-facing technical map: stack, repo layout, key commands, entrypoints, data stores, external services, environment/config surfaces, MCP/tooling footprint, and change hotspots future agents should inspect before editing code.`,
+        "9. Every major claim should be grounded in repository evidence. Mention concrete repo paths in the docs when a structural claim would otherwise be ambiguous.",
+        "10. Avoid placeholder filler, generic checklists, and duplicated content across files. Each doc should have a clear job.",
+        "11. Do not create ROADMAP.md, ENGINEERING_RULES.md, or other extra docs unless the prompt explicitly asks for them.",
         researchMode === "never"
-            ? "7. Stay repo-only. Do not use outside research."
-            : "7. Use repo evidence first. Use official docs when needed. Treat Reddit or community sources only as labeled secondary evidence.",
+            ? "12. Stay repo-only. Do not use outside research."
+            : "12. Use repo evidence first. Use official docs when needed. Treat Reddit or community sources only as labeled secondary evidence.",
         researchMode === "always"
-            ? "8. Include an external research evidence subsection in TECH.md with clearly labeled primary and secondary evidence."
-            : "8. Include external research notes only if they materially informed the architecture update.",
-        "9. If the project clearly follows Clean Architecture, feature-first modules, or another stable structure, make that explicit so future implementation stays consistent.",
+            ? `13. Include an external research evidence subsection in ${techPath} with clearly labeled primary and secondary evidence.`
+            : "13. Include external research notes only if they materially informed the architecture update.",
+        `14. If the project clearly follows Clean Architecture, feature-first modules, DDD, modular monolith, or another stable structure, make that explicit in ${architecturePath} with evidence from the repo.`,
+        `15. Ensure ${adrReadmePath} and ${adrTemplatePath} exist as ADR entrypoints, but keep them lean.`,
         "",
         "Return one JSON object on the last line with this shape:",
-        '{"files_written":["ENGINEERING_RULES.md","TECH.md"],"research_used":false,"gaps":[],"next_actions":[]}',
+        `{"files_written":["${productPath}","${architecturePath}","${techPath}","${adrReadmePath}","${adrTemplatePath}"],"research_used":false,"gaps":[],"next_actions":[]}`,
         "",
         "Do not emit placeholder TODOs in the managed sections.",
     ].join("\n");
@@ -10167,6 +10706,73 @@ async function execFileCapture(command, args, options = {}) {
         };
     }
 }
+async function spawnCapture(command, args, options = {}) {
+    const { cwd, env, streamOutput = false } = options;
+    return await new Promise((resolve, reject) => {
+        let stdout = "";
+        let stderr = "";
+        const child = spawn(command, args, {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout.on("data", (chunk) => {
+            const text = chunk.toString();
+            stdout += text;
+            if (streamOutput)
+                process.stdout.write(text);
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString();
+            stderr += text;
+            if (streamOutput)
+                process.stderr.write(text);
+        });
+        child.on("error", (error) => {
+            if (error?.code === "ENOENT") {
+                reject(new Error(`Required CLI '${command}' is not installed or not on PATH.`));
+                return;
+            }
+            reject(error);
+        });
+        child.on("close", (code) => {
+            resolve({
+                ok: code === 0,
+                stdout,
+                stderr,
+                code: code ?? 1,
+            });
+        });
+    });
+}
+function explainArchitectureBuildFailure(platform, execution) {
+    const combined = String(`${execution.stderr || ""}\n${execution.stdout || ""}`.trim());
+    const notes = [];
+    if (platform === "gemini") {
+        if (combined.includes("Error during discovery for MCP server") ||
+            combined.includes("[MCP error]")) {
+            notes.push("Gemini CLI is failing while loading MCP servers from your Gemini settings. Start the required MCP runtime(s) first or disable the broken server entries in `.gemini/settings.json` before retrying.");
+        }
+        if (combined.includes("cloudaicompanion.companions.generateChat") ||
+            combined.includes("PERMISSION_DENIED") ||
+            combined.includes("403")) {
+            notes.push("Gemini CLI reached Google auth, but the active account or project cannot generate chat content. Re-authenticate Gemini CLI with a permitted account or configure a supported Gemini API credential and project before retrying.");
+        }
+    }
+    if (platform === "claude" && combined.includes("permission")) {
+        notes.push("Claude CLI appears to be blocked by its own permission model. Re-run in a Claude environment that allows non-interactive edits for this workspace.");
+    }
+    if (notes.length === 0) {
+        return `Architecture build failed via ${platform}. ${combined}`.trim();
+    }
+    return [
+        `Architecture build failed via ${platform}.`,
+        ...notes.map((note) => `- ${note}`),
+        combined ? `Raw CLI output:\n${combined}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
 async function probeArchitectureAdapter(platform, cwd) {
     if (platform === "codex") {
         const help = await execFileCapture("codex", ["exec", "--help"], { cwd });
@@ -10242,7 +10848,7 @@ async function probeArchitectureAdapter(platform, cwd) {
         },
     };
 }
-function normalizeArchitectureResult({ stdout, workspaceRoot, rulesPath, techPath, researchMode, }) {
+function normalizeArchitectureResult({ stdout, workspaceRoot, researchMode, changedFiles = [], }) {
     const trimmed = String(stdout || "").trim();
     if (trimmed) {
         const lastLine = trimmed.split(/\r?\n/).pop();
@@ -10251,9 +10857,11 @@ function normalizeArchitectureResult({ stdout, workspaceRoot, rulesPath, techPat
                 const parsed = JSON.parse(lastLine);
                 return {
                     outputRoot: workspaceRoot,
-                    filesWritten: Array.isArray(parsed.files_written)
-                        ? parsed.files_written
-                        : [rulesPath, techPath],
+                    filesWritten: changedFiles.length > 0
+                        ? changedFiles
+                        : Array.isArray(parsed.files_written)
+                            ? parsed.files_written
+                            : [],
                     researchUsed: typeof parsed.research_used === "boolean"
                         ? parsed.research_used
                         : researchMode === "always",
@@ -10271,55 +10879,72 @@ function normalizeArchitectureResult({ stdout, workspaceRoot, rulesPath, techPat
     }
     return {
         outputRoot: workspaceRoot,
-        filesWritten: [rulesPath, techPath],
+        filesWritten: changedFiles,
         researchUsed: researchMode === "always",
         gaps: [],
         nextActions: [],
         rawOutput: trimmed,
     };
 }
+async function captureFileContents(filePaths) {
+    const snapshot = {};
+    for (const filePath of filePaths) {
+        if (await pathExists(filePath)) {
+            snapshot[filePath] = await readFile(filePath, "utf8");
+        }
+        else {
+            snapshot[filePath] = null;
+        }
+    }
+    return snapshot;
+}
 async function readArchitectureDriftStatus(workspaceRoot, snapshot) {
-    const rulesPath = path.join(workspaceRoot, "ENGINEERING_RULES.md");
-    const techPath = path.join(workspaceRoot, "TECH.md");
+    const productPath = path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "PRODUCT.md");
+    const architecturePath = path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "ARCHITECTURE.md");
+    const techPath = path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "TECH.md");
+    const adrReadmePath = path.join(workspaceRoot, FOUNDATION_ADR_DIR, "README.md");
     const metadataPath = path.join(workspaceRoot, ".cbx", ARCHITECTURE_BUILD_METADATA_FILENAME);
-    const rulesExists = await pathExists(rulesPath);
+    const productExists = await pathExists(productPath);
+    const architectureExists = await pathExists(architecturePath);
     const techExists = await pathExists(techPath);
-    const expectedRulesHash = hashStableObject(inferArchitectureContractProfile(snapshot));
-    const expectedTechHash = hashStableObject({
-        style: inferArchitectureContractProfile(snapshot).style,
-        topDirs: snapshot.topDirs,
-        frameworks: snapshot.frameworks,
-        architectureByApp: snapshot.architectureByApp,
-    });
+    const adrReadmeExists = await pathExists(adrReadmePath);
     const findings = [];
-    let actualRulesHash = null;
+    let actualProductHash = null;
+    let actualArchitectureHash = null;
     let actualTechHash = null;
-    if (!rulesExists) {
-        findings.push("ENGINEERING_RULES.md is missing.");
+    if (!productExists) {
+        findings.push(`${FOUNDATION_DOCS_DIR}/PRODUCT.md is missing.`);
     }
     else {
-        const content = await readFile(rulesPath, "utf8");
-        actualRulesHash = extractTaggedMarkerAttribute(content, ENGINEERING_ARCHITECTURE_BLOCK_START_RE, "profile");
-        if (!actualRulesHash) {
-            findings.push("ENGINEERING_RULES.md is missing the managed architecture contract block.");
+        const content = await readFile(productPath, "utf8");
+        actualProductHash = extractTaggedMarkerAttribute(content, PRODUCT_FOUNDATION_BLOCK_START_RE, "profile");
+        if (!actualProductHash) {
+            findings.push(`${FOUNDATION_DOCS_DIR}/PRODUCT.md is missing the managed product foundation block.`);
         }
-        else if (actualRulesHash !== expectedRulesHash) {
-            findings.push(`ENGINEERING_RULES.md architecture profile is stale (expected ${expectedRulesHash}, found ${actualRulesHash}).`);
+    }
+    if (!architectureExists) {
+        findings.push(`${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md is missing.`);
+    }
+    else {
+        const content = await readFile(architecturePath, "utf8");
+        actualArchitectureHash = extractTaggedMarkerAttribute(content, ARCHITECTURE_DOC_BLOCK_START_RE, "profile");
+        if (!actualArchitectureHash) {
+            findings.push(`${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md is missing the managed architecture backbone block.`);
         }
     }
     if (!techExists) {
-        findings.push("TECH.md is missing.");
+        findings.push(`${FOUNDATION_DOCS_DIR}/TECH.md is missing.`);
     }
     else {
         const content = await readFile(techPath, "utf8");
         actualTechHash = extractTaggedMarkerAttribute(content, TECH_ARCHITECTURE_BLOCK_START_RE, "snapshot");
         if (!actualTechHash) {
-            findings.push("TECH.md is missing the managed architecture snapshot block.");
-        }
-        else if (actualTechHash !== expectedTechHash) {
-            findings.push(`TECH.md architecture snapshot is stale (expected ${expectedTechHash}, found ${actualTechHash}).`);
+            findings.push(`${FOUNDATION_DOCS_DIR}/TECH.md is missing the managed architecture snapshot block.`);
         }
     }
+    if (!adrReadmeExists) {
+        findings.push(`${FOUNDATION_ADR_DIR}/README.md is missing.`);
+    }
     const metadata = await readJsonFileIfExists(metadataPath);
     if (!metadata.exists) {
         findings.push("Architecture build metadata is missing.");
@@ -10327,12 +10952,13 @@ async function readArchitectureDriftStatus(workspaceRoot, snapshot) {
     return {
         stale: findings.length > 0,
         findings,
-        rulesPath,
+        productPath,
+        architecturePath,
         techPath,
+        adrReadmePath,
         metadataPath,
-        expectedRulesHash,
-        expectedTechHash,
-        actualRulesHash,
+        actualProductHash,
+        actualArchitectureHash,
         actualTechHash,
     };
 }
@@ -10347,6 +10973,7 @@ async function runBuildArchitecture(options) {
         const cwd = process.cwd();
         const workspaceRoot = findWorkspaceRoot(cwd);
         const snapshot = await collectTechSnapshot(workspaceRoot);
+        const specRoots = await listSpecPackRoots(workspaceRoot);
         if (checkOnly) {
             const drift = await readArchitectureDriftStatus(workspaceRoot, snapshot);
             if (emitJson) {
@@ -10356,6 +10983,7 @@ async function runBuildArchitecture(options) {
                 console.log(`Platform: ${platform}`);
                 console.log(`Workspace: ${toPosixPath(workspaceRoot)}`);
                 console.log(`Status: ${drift.stale ? "stale" : "fresh"}`);
+                console.log(`Backbone docs: ${FOUNDATION_DOCS_DIR}/PRODUCT.md, ${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md, ${FOUNDATION_DOCS_DIR}/TECH.md, ${FOUNDATION_ADR_DIR}/README.md`);
                 if (drift.findings.length > 0) {
                     console.log("Findings:");
                     for (const finding of drift.findings) {
@@ -10367,13 +10995,13 @@ async function runBuildArchitecture(options) {
                 process.exit(1);
             return;
         }
-        const scaffold = await ensureArchitectureDocScaffold({
-            workspaceRoot,
-            snapshot,
-            overwrite,
-            dryRun,
-        });
-        const specRoots = await listSpecPackRoots(workspaceRoot);
+        const managedFilePaths = [
+            path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "PRODUCT.md"),
+            path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "ARCHITECTURE.md"),
+            path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "TECH.md"),
+            path.join(workspaceRoot, FOUNDATION_ADR_DIR, "README.md"),
+            path.join(workspaceRoot, FOUNDATION_ADR_DIR, "0000-template.md"),
+        ];
         const coreSkills = [
             "architecture-doc",
             "system-design",
@@ -10383,11 +11011,13 @@ async function runBuildArchitecture(options) {
         const conditionalSkills = resolveArchitectureConditionalSkills(snapshot, specRoots, researchMode);
         const skillBundle = [...coreSkills, ...conditionalSkills];
         const skillPathHints = await resolveArchitectureSkillPathHints(platform, cwd, skillBundle);
+        const inspectionAnchors = await resolveArchitectureInspectionAnchors(workspaceRoot, snapshot, specRoots);
         const prompt = buildArchitecturePrompt({
             platform,
             workspaceRoot,
             snapshot,
             specRoots,
+            inspectionAnchors,
             researchMode,
             coreSkills,
             conditionalSkills,
@@ -10395,6 +11025,13 @@ async function runBuildArchitecture(options) {
         });
         const adapter = await probeArchitectureAdapter(platform, workspaceRoot);
         const args = adapter.buildInvocation(prompt);
+        const managedTargets = [
+            path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "PRODUCT.md"),
+            path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "ARCHITECTURE.md"),
+            path.join(workspaceRoot, FOUNDATION_DOCS_DIR, "TECH.md"),
+            path.join(workspaceRoot, FOUNDATION_ADR_DIR, "README.md"),
+            path.join(workspaceRoot, FOUNDATION_ADR_DIR, "0000-template.md"),
+        ].map((filePath) => toPosixPath(filePath));
         if (dryRun) {
             const summary = {
                 platform,
@@ -10402,10 +11039,7 @@ async function runBuildArchitecture(options) {
                 adapter: adapter.binary,
                 invocation: [adapter.binary, ...args],
                 researchMode,
-                managedTargets: [
-                    toPosixPath(scaffold.engineeringRulesPath),
-                    toPosixPath(scaffold.techMdPath),
-                ],
+                managedTargets,
                 skillBundle,
             };
             if (emitJson) {
@@ -10416,36 +11050,55 @@ async function runBuildArchitecture(options) {
                 console.log(`Workspace: ${toPosixPath(workspaceRoot)}`);
                 console.log(`Adapter: ${adapter.binary}`);
                 console.log(`Research mode: ${researchMode}`);
-                console.log(`Managed targets: ${toPosixPath(scaffold.engineeringRulesPath)}, ${toPosixPath(scaffold.techMdPath)}`);
+                console.log(`Managed targets: ${summary.managedTargets.join(", ")}`);
                 console.log(`Skill bundle: ${skillBundle.join(", ")}`);
                 console.log(`Invocation: ${[adapter.binary, ...args].join(" ")}`);
             }
             return;
         }
-        const execution = await execFileCapture(adapter.binary, args, {
+        const filesBefore = await captureFileContents(managedFilePaths);
+        const scaffold = await ensureArchitectureBuildScaffold({
+            workspaceRoot,
+            dryRun,
+        });
+        if (!emitJson) {
+            console.log(`Streaming ${adapter.binary} output...`);
+        }
+        const execution = await spawnCapture(adapter.binary, args, {
             cwd: workspaceRoot,
             env: process.env,
+            streamOutput: !emitJson,
         });
         if (!execution.ok) {
-            throw new Error(`Architecture build failed via ${adapter.binary}. ${String(execution.stderr || execution.stdout || "").trim()}`);
-        }
-        const rulesContent = await readFile(scaffold.engineeringRulesPath, "utf8");
-        const techContent = await readFile(scaffold.techMdPath, "utf8");
+            throw new Error(explainArchitectureBuildFailure(platform, execution));
+        }
+        const filesAfter = await captureFileContents(managedFilePaths);
+        const changedFiles = managedFilePaths
+            .filter((filePath) => filesBefore[filePath] !== filesAfter[filePath])
+            .map((filePath) => toPosixPath(path.relative(workspaceRoot, filePath)));
+        const techContent = filesAfter[scaffold.techMdPath] ?? (await readFile(scaffold.techMdPath, "utf8"));
+        const productContent = filesAfter[scaffold.productPath] ?? (await readFile(scaffold.productPath, "utf8"));
+        const architectureContent = filesAfter[scaffold.architectureDocPath] ??
+            (await readFile(scaffold.architectureDocPath, "utf8"));
         const metadataPath = path.join(workspaceRoot, ".cbx", ARCHITECTURE_BUILD_METADATA_FILENAME);
         const metadata = buildArchitectureBuildMetadata({
             platform,
             researchMode,
-            rulesProfileHash: extractTaggedMarkerAttribute(rulesContent, ENGINEERING_ARCHITECTURE_BLOCK_START_RE, "profile") || "unknown",
-            techSnapshotHash: extractTaggedMarkerAttribute(techContent, TECH_ARCHITECTURE_BLOCK_START_RE, "snapshot") || "unknown",
+            managedDocs: [
+                `${FOUNDATION_DOCS_DIR}/PRODUCT.md`,
+                `${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md`,
+                `${FOUNDATION_DOCS_DIR}/TECH.md`,
+                `${FOUNDATION_ADR_DIR}/README.md`,
+                `${FOUNDATION_ADR_DIR}/0000-template.md`,
+            ],
         });
         await mkdir(path.dirname(metadataPath), { recursive: true });
         await writeFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
         const result = normalizeArchitectureResult({
             stdout: execution.stdout,
             workspaceRoot: toPosixPath(workspaceRoot),
-            rulesPath: "ENGINEERING_RULES.md",
-            techPath: "TECH.md",
             researchMode,
+            changedFiles: [...new Set(changedFiles)],
         });
         if (emitJson) {
             console.log(JSON.stringify({
@@ -10459,7 +11112,8 @@ async function runBuildArchitecture(options) {
         console.log(`Platform: ${platform}`);
         console.log(`Adapter: ${adapter.binary}`);
         console.log(`Workspace: ${toPosixPath(workspaceRoot)}`);
-        console.log(`Managed docs: ENGINEERING_RULES.md, TECH.md`);
+        console.log(`Managed docs: ${FOUNDATION_DOCS_DIR}/PRODUCT.md, ${FOUNDATION_DOCS_DIR}/ARCHITECTURE.md, ${FOUNDATION_DOCS_DIR}/TECH.md`);
+        console.log(`ADR scaffold: ${FOUNDATION_ADR_DIR}/README.md, ${FOUNDATION_ADR_DIR}/0000-template.md`);
         console.log(`Skill bundle: ${skillBundle.join(", ")}`);
         console.log(`Files written: ${(result.filesWritten || []).join(", ") || "(none reported)"}`);
         console.log(`Research used: ${result.researchUsed ? "yes" : "no"}`);
@@ -10680,10 +11334,7 @@ async function runInitWizard(options) {
                     dryRun: installOutcome.dryRun,
                 });
                 printRuleSyncResult(installOutcome.syncResult);
-                printInstallEngineeringSummary({
-                    engineeringResults: installOutcome.engineeringArtifactsResult.engineeringResults,
-                    techResult: installOutcome.engineeringArtifactsResult.techResult,
-                });
+                printInstallDocumentationNotice();
                 printPostmanSetupSummary({
                     postmanSetup: installOutcome.postmanSetupResult,
                 });