@duckcodeailabs/dql-cli 1.12.10 → 1.13.0

package/dist/apps-api.js

@@ -3,7 +3,7 @@
  * `/api/persona`. Designed to be invoked from `local-runtime.ts`'s request
  * dispatcher — returns `true` if the request was handled, `false` otherwise.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname, relative, basename } from 'node:path';
 import { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboardsForApp, parseAppDocument, parseDashboardDocument, normalizeDqlArtifactReference, suggestAppId, } from '@duckcodeailabs/dql-core';
@@ -72,6 +72,41 @@ export async function handleAppsApi(ctx) {
         return true;
     }
     // Two-phase AI build: propose (plan + confirmable content list, no files) …
+    if (req.method === 'POST' && path === '/api/apps/ai-builds/propose-background') {
+        try {
+            const body = await readJson(req);
+            if (!ctx.queueOperation) {
+                sendJson(res, 501, { ok: false, error: 'Background App builds are unavailable in this runtime.' });
+                return true;
+            }
+            const sessionId = appAiBuildSessionId(body.sessionId);
+            const operation = ctx.queueOperation({
+                type: 'app_ai_build',
+                scope: `app-build:${sessionId}`,
+                resourceRevision: createHash('sha256').update(JSON.stringify(body)).digest('hex'),
+                message: body.existingAppId ? 'App page proposal queued.' : 'App proposal queued.',
+                cancellable: true,
+            }, async (signal, report) => {
+                report({ phase: 'planning', progress: 8, message: 'Planning the governed App proposal.' });
+                if (signal.aborted)
+                    throw Object.assign(new Error('App build cancelled.'), { code: 'OPERATION_CANCELLED' });
+                const session = await proposeAppAiBuild(projectRoot, { ...body, sessionId }, {
+                    generateGovernedAnswer: ctx.generateGovernedAnswer,
+                });
+                if (signal.aborted)
+                    throw Object.assign(new Error('App build cancelled.'), { code: 'OPERATION_CANCELLED' });
+                if (session.status === 'error')
+                    throw Object.assign(new Error(session.error ?? 'App proposal failed.'), { code: 'APP_BUILD_FAILED' });
+                report({ phase: 'review_ready', progress: 96, message: 'Build Brief ready for review.' });
+                return { sessionId: session.id, status: session.status, appId: session.appId, dashboardId: session.dashboardId };
+            });
+            sendJson(res, 202, { ok: true, operation, sessionId });
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err.message });
+        }
+        return true;
+    }
     if (req.method === 'POST' && path === '/api/apps/ai-builds/propose') {
         try {
             const body = await readJson(req);
@@ -169,6 +204,37 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    m = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/approve-semantic$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        const dashboardId = decodeURIComponent(m[2]);
+        try {
+            const body = await readJson(req);
+            const runId = cleanString(body.runId);
+            const tileIds = unique((body.tileIds ?? []).map(cleanString).filter(Boolean));
+            if (!runId || tileIds.length === 0 || !ctx.verifyDashboardRun) {
+                sendJson(res, 400, { ok: false, error: 'A successful dashboard run and semantic tile selection are required.' });
+                return true;
+            }
+            const verified = ctx.verifyDashboardRun({ runId, appId, dashboardId, tileIds });
+            if (!verified.ok) {
+                sendJson(res, 409, { ok: false, error: verified.error });
+                return true;
+            }
+            const result = approveAppSemanticTiles(projectRoot, appId, dashboardId, {
+                tileIds,
+                runId,
+                snapshotId: verified.snapshotId,
+                expectedDashboardFingerprint: cleanString(body.expectedDashboardFingerprint),
+                reviewer: cleanString(body.reviewer) || 'local-reviewer',
+            });
+            sendJson(res, result.ok ? 200 : 409, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
     m = path.match(/^\/api\/apps\/([^/]+)\/editor\/catalog$/);
     if (m && req.method === 'GET') {
         const appId = decodeURIComponent(m[1]);
@@ -645,6 +711,22 @@ export async function handleAppsApi(ctx) {
     }
     // /api/apps/:id  — single App with dashboards summary
     m = path.match(/^\/api\/apps\/([^/]+)$/);
+    if (m && req.method === 'DELETE') {
+        const id = decodeURIComponent(m[1]);
+        try {
+            const result = deleteAppPackage(projectRoot, id);
+            if (!result.ok) {
+                sendJson(res, result.status, { ok: false, error: result.error });
+                return true;
+            }
+            ctx.scheduleProjectRefresh?.('app-deleted');
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err.message });
+        }
+        return true;
+    }
     if (m && req.method === 'GET') {
         const id = m[1];
         const result = loadAppById(projectRoot, id);
@@ -764,6 +846,7 @@ function collectAppsList(projectRoot) {
             status: document.lifecycle === 'review' ? 'review' : dashboards.length > 0 ? 'ready' : 'empty',
             storage: document.visibility === 'private' ? 'mine' : document.visibility === 'template' ? 'template' : 'shared',
             visibility: document.visibility ?? 'shared',
+            publicationIntent: document.publicationIntent ?? (document.visibility === 'private' ? 'personal' : 'shared_project'),
             owners: document.owners,
             tags: document.tags ?? [],
             members: document.members.length,
@@ -975,12 +1058,12 @@ export async function generateAppPackage(projectRoot, input) {
             owner: cleanString(input.owner) || undefined,
             preferredBlockIds: selectedBlockIds,
             plannerMode: input.plannerMode === 'ai_assisted' ? 'ai_assisted' : 'deterministic',
+            mode: input.mode === 'personal' ? 'personal' : 'stakeholder',
         });
         const validation = validateAppPlan(plan, kg);
-        const certifiedTiles = typeof validation.certifiedTiles === 'number'
-            ? validation.certifiedTiles
-            : 0;
-        if (certifiedTiles === 0) {
+        const governedTiles = plan.pages.flatMap((page) => page.tiles)
+            .filter((tile) => tile.kind === 'certified_block' || tile.kind === 'semantic_query').length;
+        if (governedTiles === 0) {
             return {
                 ok: false,
                 error: appBuildBlockedMessage(validation, plan),
@@ -1009,7 +1092,7 @@ export async function generateAppPackage(projectRoot, input) {
 }
 export async function createAppAiBuildSession(projectRoot, input) {
     const now = new Date().toISOString();
-    const id = `app_build_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const id = appAiBuildSessionId(input.sessionId);
     const selectedBlockIds = unique((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean));
     const base = {
         id,
@@ -1027,6 +1110,7 @@ export async function createAppAiBuildSession(projectRoot, input) {
             notebookPath: cleanString(input.notebookPath) || undefined,
             existingAppId: cleanString(input.existingAppId) || undefined,
             mode: input.mode === 'personal' ? 'personal' : 'stakeholder',
+            exploreGaps: input.mode === 'personal' && input.exploreGaps === true,
             selectedBlockIds,
         },
     };
@@ -1093,7 +1177,18 @@ function buildAppProposal(plan) {
                     description: tile.description,
                     blockId: tile.blockId,
                     viz: tile.viz,
+                    allowedVisualizations: tile.display?.genUi.allowedVisualizations ?? [tile.viz, 'table'],
                     certification: 'certified',
+                    sourceClass: 'certified_block',
+                    reviewStatus: 'not_required',
+                    requirementIds: tile.requirementIds,
+                    sourceEvidence: tile.sourceEvidence,
+                    preflight: {
+                        status: 'passed',
+                        snapshotId: plan.snapshotId,
+                        sourceFingerprint: tile.sourceNodeId,
+                        message: 'Certified source and requirement compatibility were validated against this project snapshot.',
+                    },
                     selectedByDefault: true,
                 });
             }
@@ -1106,7 +1201,18 @@ function buildAppProposal(plan) {
                     question: tile.title,
                     semantic: tile.semantic,
                     viz: tile.viz,
+                    allowedVisualizations: tile.display?.genUi.allowedVisualizations ?? [tile.viz, 'table'],
                     certification: 'reviewed_semantic',
+                    sourceClass: 'governed_semantic',
+                    reviewStatus: 'required',
+                    requirementIds: tile.requirementIds,
+                    sourceEvidence: tile.sourceEvidence,
+                    preflight: {
+                        status: 'review_required',
+                        snapshotId: plan.snapshotId,
+                        sourceFingerprint: tile.semantic.definitionFingerprint,
+                        message: 'Semantic identities are resolved; run and review the result before shared publication.',
+                    },
                     selectedByDefault: true,
                 });
             }
@@ -1137,6 +1243,10 @@ function buildAppProposal(plan) {
         gaps.push({ id: `gap_${gaps.length + 1}`, question, reason: 'No certified block covers this question.' });
     }
     return {
+        intent: {
+            target: plan.publicationIntent,
+            initialVisibility: 'private',
+        },
         tiles,
         gaps,
         followUps: gaps.map((gap) => gap.question).slice(0, 4),
@@ -1213,6 +1323,11 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 remaining.push(gap);
                 continue;
             }
+            const preview = previewFromAgentResult(answer.result);
+            const repair = answer.appBuilderRepair;
+            const unresolvedExecutionError = !preview
+                ? cleanString(answer.executionError ?? answer.warehouseFailure?.redactedMessage ?? '')
+                : '';
             // Gap-fill tiles are AI-generated by definition (they answer questions the
             // certified blocks did NOT cover). They are ALWAYS ai_generated / review-
             // required — never auto-certified, even if the governed loop happened to
@@ -1226,8 +1341,28 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 answer: cleanString(answer.answer ?? answer.text ?? '') || undefined,
                 viz: normalizeGeneratedViz(answer.suggestedViz),
                 certification: 'ai_generated',
-                preview: previewFromAgentResult(answer.result),
-                selectedByDefault: true,
+                sourceClass: 'exploratory_analysis',
+                reviewStatus: 'required',
+                preflight: {
+                    status: preview ? 'passed' : unresolvedExecutionError ? 'blocked' : 'review_required',
+                    sourceFingerprint: `sha256:${createHash('sha256').update(sql).digest('hex')}`,
+                    receiptId: preview
+                        ? `preview:${createHash('sha256').update(JSON.stringify(preview)).digest('hex')}`
+                        : undefined,
+                    message: preview
+                        ? repair?.status === 'repaired'
+                            ? 'The shared bounded repair produced a successful preview; the query remains review-required.'
+                            : 'A bounded preview ran successfully; business review is still required.'
+                        : repair?.status === 'failed'
+                            ? repair.message
+                            : unresolvedExecutionError
+                                ? 'The generated query failed its bounded preview and could not be selected.'
+                                : 'SQL was generated but has no successful preview receipt yet.',
+                },
+                preview,
+                ...(repair ? { repair } : {}),
+                ...(unresolvedExecutionError ? { error: unresolvedExecutionError } : {}),
+                selectedByDefault: false,
             });
         }
         catch (err) {
@@ -1246,6 +1381,12 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 question: gap.question,
                 viz: 'table',
                 certification: 'ai_generated',
+                sourceClass: 'exploratory_analysis',
+                reviewStatus: 'required',
+                preflight: {
+                    status: 'blocked',
+                    message: 'Exploratory analysis generation failed.',
+                },
                 error: message,
                 selectedByDefault: false,
             });
@@ -1267,11 +1408,11 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
  */
 export async function proposeAppAiBuild(projectRoot, input, hooks) {
     const now = new Date().toISOString();
-    const id = `app_build_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const id = appAiBuildSessionId(input.sessionId);
     const selectedBlockIds = unique((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean));
     const base = {
         id,
-        status: 'proposed',
+        status: 'building',
         createdAt: now,
         updatedAt: now,
         prompt: cleanString(input.prompt),
@@ -1285,6 +1426,7 @@ export async function proposeAppAiBuild(projectRoot, input, hooks) {
             notebookPath: cleanString(input.notebookPath) || undefined,
             existingAppId: cleanString(input.existingAppId) || undefined,
             mode: input.mode === 'personal' ? 'personal' : 'stakeholder',
+            exploreGaps: input.mode === 'personal' && input.exploreGaps === true,
             selectedBlockIds,
         },
     };
@@ -1293,17 +1435,32 @@ export async function proposeAppAiBuild(projectRoot, input, hooks) {
         writeAppAiBuildSession(projectRoot, session);
         return session;
     }
-    if (base.inputs.existingAppId) {
-        const session = { ...base, status: 'error', error: 'Updating an existing App is not supported yet. Create a new App so no existing content is silently replaced.' };
+    // Persist the durable identity before planning or provider work begins. The
+    // browser can leave this page immediately and recover the same session later.
+    writeAppAiBuildSession(projectRoot, base);
+    const existingApp = base.inputs.existingAppId ? loadAppById(projectRoot, base.inputs.existingAppId) : null;
+    if (base.inputs.existingAppId && !existingApp) {
+        const session = { ...base, status: 'error', error: `App "${base.inputs.existingAppId}" not found.` };
         writeAppAiBuildSession(projectRoot, session);
         return session;
     }
+    if (existingApp) {
+        // Existing-App page generation inherits server-owned App context. The prompt
+        // controls the new page, never the identity or governance boundary of the App.
+        base.inputs.domain = existingApp.app.domain;
+        base.inputs.audience = existingApp.app.audience;
+        base.inputs.owner = existingApp.app.businessOwner ?? existingApp.app.owners[0];
+        const publicationIntent = existingApp.app.publicationIntent
+            ?? (existingApp.app.visibility === 'private' ? 'personal' : 'shared_project');
+        base.inputs.mode = publicationIntent === 'personal' ? 'personal' : 'stakeholder';
+        base.inputs.exploreGaps = base.inputs.mode === 'personal' && input.exploreGaps === true;
+    }
     const { KGStore, defaultKgPath, planAppFromPrompt, reindexProject, validateAppPlan, } = await import('@duckcodeailabs/dql-agent');
     const kgPath = defaultKgPath(projectRoot);
     const index = await reindexProject(projectRoot, { kgPath });
     const kg = new KGStore(kgPath);
     try {
-        const plan = planAppFromPrompt({
+        const planned = planAppFromPrompt({
             prompt: base.prompt,
             kg,
             domain: base.inputs.domain,
@@ -1311,22 +1468,48 @@ export async function proposeAppAiBuild(projectRoot, input, hooks) {
             owner: base.inputs.owner,
             preferredBlockIds: selectedBlockIds,
             plannerMode: input.plannerMode === 'ai_assisted' ? 'ai_assisted' : 'deterministic',
-            mode: input.mode === 'personal' ? 'personal' : 'stakeholder',
+            mode: base.inputs.mode === 'personal' ? 'personal' : 'stakeholder',
             snapshotId: index.kgFingerprint,
         });
+        const firstPage = planned.pages[0];
+        if (!firstPage)
+            throw new Error('The App planner did not return a page.');
+        const existingDashboardIds = new Set(existingApp?.dashboards.map((dashboard) => dashboard.id) ?? []);
+        const pageId = existingApp
+            ? uniqueAppPageId(slugify(firstPage.title) || 'page', existingDashboardIds)
+            : firstPage.id;
+        const plan = existingApp ? {
+            ...planned,
+            appId: existingApp.app.id,
+            name: existingApp.app.name,
+            domain: existingApp.app.domain,
+            audience: existingApp.app.audience ?? planned.audience,
+            owner: existingApp.app.businessOwner ?? existingApp.app.owners[0] ?? planned.owner,
+            publicationIntent: existingApp.app.publicationIntent
+                ?? (existingApp.app.visibility === 'private' ? 'personal' : 'shared_project'),
+            pages: [{ ...firstPage, id: pageId }],
+        } : planned;
         const validation = validateAppPlan(plan, kg);
         const proposal = buildAppProposal(plan);
-        // App Builder v2 never turns generated SQL into a primary dashboard tile.
-        // Uncovered requirements stay visible gaps for Research/Copilot.
-        const proposalHash = createHash('sha256').update(JSON.stringify({ plan, proposal })).digest('hex');
+        // Raw SQL exploration is opt-in, personal-only, preview-bounded, and remains
+        // unselected until the user explicitly accepts it in the Build Brief.
+        if (base.inputs.exploreGaps) {
+            await fillProposalGaps(proposal, hooks, input.maxGeneratedTiles);
+        }
+        const existingAppFingerprint = existingApp ? fingerprintAppDirectory(existingApp.appDir) : undefined;
+        const proposalHash = createHash('sha256')
+            .update(JSON.stringify({ plan, proposal, existingAppFingerprint }))
+            .digest('hex');
         const session = {
             ...base,
+            status: 'proposed',
             appId: plan.appId,
             dashboardId: plan.pages[0]?.id ?? null,
             plan,
             validation,
             proposal,
             snapshotId: index.kgFingerprint,
+            ...(existingAppFingerprint ? { existingAppFingerprint } : {}),
             proposalHash,
             warnings: appBuildWarnings(validation, plan),
             reviewTasks: reviewTasksFromPlan(plan),
@@ -1348,12 +1531,11 @@ export async function proposeAppAiBuild(projectRoot, input, hooks) {
     }
 }
 /**
- * Persist selected AI-generated candidates as aiPins (certification preserved,
- * never upgraded; review-required) and append them as dashboard tiles below the
- * certified layout. The dashboard doc was just written by generateAppFromPlan, so
- * this rewrites it with the extra items — the renderer already badges aiPin tiles.
+ * Materialize explicitly selected exploratory candidates as Git-owned, app-scoped
+ * review DQL. They are never promoted into the shared block library and the
+ * dashboard stores a fingerprinted reference instead of inline SQL.
  */
-function attachGeneratedTiles(projectRoot, plan, generatedPaths, candidates) {
+function attachGeneratedDraftAnalyses(projectRoot, plan, generatedPaths, candidates) {
     const dashboardId = plan.pages[0]?.id ?? 'overview';
     const dashboardPath = generatedPaths.find((path) => path.endsWith(`${dashboardId}.dqld`))
         ?? generatedPaths.find((path) => path.endsWith('.dqld'));
@@ -1363,7 +1545,7 @@ function attachGeneratedTiles(projectRoot, plan, generatedPaths, candidates) {
     if (!existsSync(absolutePath))
         return;
     const doc = JSON.parse(readFileSync(absolutePath, 'utf-8'));
-    // Story layout: generated tiles live in the review appendix. Classic grids
+    // Story layout: exploratory tiles live in the review appendix. Classic grids
     // (no sections) just append at the bottom, untagged.
     const storyMode = Array.isArray(doc.sections) && doc.sections.length > 0;
     if (storyMode && !doc.sections.some((section) => section.kind === 'appendix')) {
@@ -1374,52 +1556,80 @@ function attachGeneratedTiles(projectRoot, plan, generatedPaths, candidates) {
             order: doc.sections.length,
         });
     }
-    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
-    try {
-        let y = doc.layout.items.reduce((max, item) => Math.max(max, item.y + item.h), 0);
-        let x = 0;
-        for (const tile of candidates) {
-            const certified = tile.certification === 'certified';
-            const pin = storage.createAiPin({
-                appId: plan.appId,
-                dashboardId: doc.id,
-                title: tile.title,
-                answer: tile.answer ?? tile.question ?? tile.title,
-                question: tile.question,
-                sql: tile.sql,
-                certification: certified ? 'certified' : 'ai_generated',
-                reviewStatus: certified ? 'certified' : 'needs_review',
-                refreshCadence: 'none',
-                result: tile.preview,
-                followUps: tile.followUps ?? [],
-            });
-            const item = {
-                i: `aipin_${pin.id}`,
-                x,
-                y,
-                w: 6,
-                h: 4,
-                aiPin: { id: pin.id },
-                viz: { type: normalizeGeneratedViz(tile.viz) },
-                title: tile.title,
-                trustState: certified ? 'certified' : 'review_required',
-                reviewStatus: certified ? 'certified' : 'review_required',
-                ...(storyMode ? { sectionId: 'appendix' } : {}),
-            };
-            doc.layout.items.push(item);
-            if (x === 0) {
-                x = 6;
-            }
-            else {
-                x = 0;
-                y += 4;
-            }
+    let y = doc.layout.items.reduce((max, item) => Math.max(max, item.y + item.h), 0);
+    let x = 0;
+    const draftsDir = join(projectRoot, 'apps', plan.appId, 'drafts');
+    mkdirSync(draftsDir, { recursive: true });
+    for (const tile of candidates) {
+        if (!tile.sql)
+            continue;
+        if (tile.sql.includes('"""'))
+            throw new Error(`Exploratory SQL for "${tile.title}" contains an unsupported triple-quote delimiter.`);
+        const draftId = slugify(tile.title) || slugify(tile.id) || `analysis-${Date.now()}`;
+        const draftPath = join(draftsDir, `${draftId}.dql`);
+        const source = [
+            `block "${escapeDqlString(draftId)}" {`,
+            `  domain = "${escapeDqlString(plan.domain)}"`,
+            '  type = "custom"',
+            '  status = "review"',
+            `  owner = "${escapeDqlString(plan.owner)}"`,
+            `  description = "${escapeDqlString((tile.answer ?? tile.question ?? tile.title).slice(0, 240))}"`,
+            tile.question ? `  llmContext = "${escapeDqlString(`App-scoped exploratory analysis. Question: ${tile.question}`)}"` : '',
+            tile.question ? `  examples = [{ question = "${escapeDqlString(tile.question)}" }]` : '',
+            '  caveats = ["AI-generated app draft. Validate joins, filters, grain, and business interpretation before promotion or publication."]',
+            '  tags = ["app-scoped", "ai-generated", "needs-review"]',
+            '',
+            '  query = """',
+            tile.sql,
+            '  """',
+            '',
+            '  visualization {',
+            `    chart = "${escapeDqlString(normalizeGeneratedViz(tile.viz))}"`,
+            '  }',
+            '}',
+            '',
+        ].filter(Boolean).join('\n');
+        const fingerprint = `sha256:${createHash('sha256').update(source).digest('hex')}`;
+        writeFileSync(draftPath, source, 'utf-8');
+        generatedPaths.push(relative(projectRoot, draftPath));
+        const item = {
+            i: `draft_${draftId}`,
+            x,
+            y,
+            w: 6,
+            h: 4,
+            draftAnalysis: {
+                ref: `drafts/${draftId}.dql`,
+                artifactFingerprint: fingerprint,
+                ...(plan.snapshotId ? { snapshotId: plan.snapshotId } : {}),
+                ...(tile.preflight.receiptId ? { executionReceiptId: tile.preflight.receiptId } : {}),
+            },
+            viz: { type: normalizeGeneratedViz(tile.viz) },
+            title: tile.title,
+            sourceClass: 'exploratory_analysis',
+            review: {
+                status: 'required',
+                sourceFingerprint: fingerprint,
+                ...(tile.preflight.receiptId ? { preflightReceiptId: tile.preflight.receiptId } : {}),
+            },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+            ...(storyMode ? { sectionId: 'appendix' } : {}),
+        };
+        doc.layout.items.push(item);
+        if (x === 0) {
+            x = 6;
+        }
+        else {
+            x = 0;
+            y += 4;
         }
-        writeFileSync(absolutePath, JSON.stringify(doc, null, 2) + '\n', 'utf-8');
     }
-    finally {
-        storage.close();
+    const parsed = parseDashboardDocument(JSON.stringify(doc), absolutePath);
+    if (!parsed.document || parsed.errors.length > 0) {
+        throw new Error(`Exploratory App dashboard is invalid: ${parsed.errors.map((error) => error.message).join('; ')}`);
     }
+    writeFileSync(absolutePath, JSON.stringify(doc, null, 2) + '\n', 'utf-8');
 }
 /**
  * Phase 2 of the two-phase app build: the user confirmed the proposal — filter the
@@ -1439,7 +1649,29 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
         return { ok: false, error: 'The App proposal changed or is stale. Refresh the proposal before creating the App.', status: 409 };
     }
     const plan = session.plan;
+    const existingAppId = cleanString(session.inputs.existingAppId);
+    const isExistingPageBuild = Boolean(existingAppId);
+    const existingApp = existingAppId ? loadAppById(projectRoot, existingAppId) : null;
+    if (isExistingPageBuild) {
+        if (!existingApp)
+            return { ok: false, error: `App "${existingAppId}" no longer exists.`, status: 409 };
+        if (!session.existingAppFingerprint
+            || fingerprintAppDirectory(existingApp.appDir) !== session.existingAppFingerprint) {
+            return {
+                ok: false,
+                error: 'The App changed after this page proposal was created. Refresh and review the page proposal again.',
+                status: 409,
+            };
+        }
+    }
     const proposal = session.proposal;
+    const proposalTileIds = new Set(proposal.tiles.map((tile) => tile.id));
+    const tileOverrides = Object.fromEntries(Object.entries(input.tileOverrides ?? {})
+        .filter(([tileId, value]) => proposalTileIds.has(tileId) && value && typeof value === 'object')
+        .map(([tileId, value]) => [tileId, {
+            ...(cleanString(value.title) ? { title: cleanString(value.title).slice(0, 120) } : {}),
+            ...(cleanString(value.viz) ? { viz: normalizeGeneratedViz(value.viz) } : {}),
+        }]));
     const selectable = new Set(proposal.tiles.filter((tile) => !tile.error).map((tile) => tile.id));
     const selected = new Set((input.selectedTileIds ?? Array.from(selectable)).filter((tileId) => selectable.has(tileId)));
     if (selected.size === 0) {
@@ -1449,11 +1681,43 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
     // tiles (narrative, draft placeholders) stay — they document the story + gaps.
     const committedPlan = {
         ...plan,
-        pages: plan.pages.map((page) => ({
+        ...(!isExistingPageBuild && cleanString(input.appName) ? { name: cleanString(input.appName).slice(0, 120) } : {}),
+        ...(!isExistingPageBuild && cleanString(input.audience) ? { audience: cleanString(input.audience).slice(0, 120) } : {}),
+        pages: plan.pages.map((page, pageIndex) => ({
             ...page,
-            tiles: page.tiles.filter((tile) => !['certified_block', 'semantic_query'].includes(tile.kind) || selected.has(tile.id)),
+            ...(isExistingPageBuild && pageIndex === 0 && cleanString(input.pageTitle)
+                ? { title: cleanString(input.pageTitle).slice(0, 120) }
+                : {}),
+            tiles: page.tiles
+                .filter((tile) => !['certified_block', 'semantic_query'].includes(tile.kind) || selected.has(tile.id))
+                .map((tile) => {
+                const override = tileOverrides[tile.id];
+                if (!override)
+                    return tile;
+                const viz = override.viz;
+                return {
+                    ...tile,
+                    ...(override.title ? { title: override.title } : {}),
+                    ...(viz ? { viz } : {}),
+                    ...(viz && tile.display ? {
+                        display: {
+                            ...tile.display,
+                            recommendedDisplayType: viz,
+                            genUi: {
+                                ...tile.display.genUi,
+                                defaultVisualization: viz,
+                                allowedVisualizations: Array.from(new Set([viz, ...tile.display.genUi.allowedVisualizations])),
+                            },
+                        },
+                    } : {}),
+                };
+            }),
         })),
     };
+    const selectedExploratory = proposal.tiles.filter((tile) => (tile.source === 'ai_generated' && selected.has(tile.id) && !tile.error && Boolean(tile.sql))).map((tile) => ({ ...tile, ...tileOverrides[tile.id] }));
+    if (plan.mode !== 'personal' && selectedExploratory.length > 0) {
+        return { ok: false, error: 'Exploratory SQL can only be accepted into a Personal Draft.', status: 400 };
+    }
     const { KGStore, defaultKgPath, ensureMetadataCatalogFresh, generateAppFromPlan, reindexProject, validateAppPlan, } = await import('@duckcodeailabs/dql-agent');
     const index = await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
     if (!session.snapshotId || index.kgFingerprint !== session.snapshotId) {
@@ -1465,8 +1729,8 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
         const validation = validateAppPlan(committedPlan, kg);
         const governedTileCount = committedPlan.pages.flatMap((page) => page.tiles)
             .filter((tile) => tile.kind === 'certified_block' || tile.kind === 'semantic_query').length;
-        if (governedTileCount === 0) {
-            return { ok: false, error: 'Select at least one certified block or governed semantic query.', status: 409 };
+        if (governedTileCount === 0 && selectedExploratory.length === 0) {
+            return { ok: false, error: 'Select a certified block, governed semantic query, or explicitly accepted Personal Draft analysis.', status: 409 };
         }
         // Copilot follow-ups the created app carries: still-uncovered gaps first, then
         // the questions behind any candidates the user chose to leave out.
@@ -1478,33 +1742,104 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
         ]).slice(0, 4);
         let generated;
         const stagingRoot = join(projectRoot, '.dql', 'local', 'app-build-staging', session.id);
-        const stagedAppDir = join(stagingRoot, 'apps', committedPlan.appId);
+        const generatedRoot = isExistingPageBuild ? join(stagingRoot, 'generated') : stagingRoot;
+        const generatedAppDir = join(generatedRoot, 'apps', committedPlan.appId);
+        const stagedAppDir = isExistingPageBuild
+            ? join(stagingRoot, 'candidate', 'apps', committedPlan.appId)
+            : generatedAppDir;
         const targetAppDir = join(projectRoot, 'apps', committedPlan.appId);
         const backupAppDir = join(projectRoot, '.dql', 'local', 'app-build-staging', `${session.id}-backup`);
         rmSync(stagingRoot, { recursive: true, force: true });
         try {
-            generated = generateAppFromPlan(stagingRoot, committedPlan, kg, { overwrite: true, copilotQuestions });
+            generated = generateAppFromPlan(generatedRoot, committedPlan, kg, { overwrite: true, copilotQuestions });
+            if (selectedExploratory.length > 0) {
+                attachGeneratedDraftAnalyses(generatedRoot, committedPlan, generated.paths, selectedExploratory);
+            }
             mkdirSync(dirname(targetAppDir), { recursive: true });
-            if (existsSync(targetAppDir)) {
+            if (isExistingPageBuild) {
+                if (!existingApp || !existsSync(targetAppDir)) {
+                    return { ok: false, error: `App "${existingAppId}" no longer exists.`, status: 409 };
+                }
+                if (fingerprintAppDirectory(existingApp.appDir) !== session.existingAppFingerprint) {
+                    return {
+                        ok: false,
+                        error: 'The App changed while this page was being prepared. Refresh and review the page proposal again.',
+                        status: 409,
+                    };
+                }
+                const page = committedPlan.pages[0];
+                if (!page)
+                    return { ok: false, error: 'The approved plan has no page to add.', status: 400 };
+                const generatedDashboardPath = join(generatedAppDir, 'dashboards', `${page.id}.dqld`);
+                const targetDashboardPath = join(stagedAppDir, 'dashboards', `${page.id}.dqld`);
+                if (existingApp.dashboards.some((dashboard) => dashboard.id === page.id)) {
+                    return { ok: false, error: `Dashboard page already exists: ${page.id}`, status: 409 };
+                }
+                cpSync(existingApp.appDir, stagedAppDir, { recursive: true });
+                if (existsSync(targetDashboardPath)) {
+                    return { ok: false, error: `Dashboard page already exists: ${page.id}`, status: 409 };
+                }
+                mkdirSync(dirname(targetDashboardPath), { recursive: true });
+                cpSync(generatedDashboardPath, targetDashboardPath);
+                const committedPaths = [relative(projectRoot, join(targetAppDir, 'dashboards', `${page.id}.dqld`))];
+                for (const generatedPath of generated.paths.filter((path) => path.includes('/drafts/') && path.endsWith('.dql'))) {
+                    const sourcePath = join(generatedRoot, generatedPath);
+                    const packageRelativePath = relative(generatedAppDir, sourcePath);
+                    const candidatePath = join(stagedAppDir, packageRelativePath);
+                    const finalPath = join(targetAppDir, packageRelativePath);
+                    if (existsSync(candidatePath)) {
+                        return { ok: false, error: `App draft already exists: ${relative(projectRoot, finalPath)}`, status: 409 };
+                    }
+                    mkdirSync(dirname(candidatePath), { recursive: true });
+                    cpSync(sourcePath, candidatePath);
+                    committedPaths.push(relative(projectRoot, finalPath));
+                }
+                generated = { ...generated, paths: committedPaths };
+                if (fingerprintAppDirectory(existingApp.appDir) !== session.existingAppFingerprint) {
+                    return {
+                        ok: false,
+                        error: 'The App changed while this page was being staged. Refresh and review the page proposal again.',
+                        status: 409,
+                    };
+                }
+                rmSync(backupAppDir, { recursive: true, force: true });
+                renameSync(targetAppDir, backupAppDir);
+                try {
+                    renameSync(stagedAppDir, targetAppDir);
+                }
+                catch (error) {
+                    if (!existsSync(targetAppDir) && existsSync(backupAppDir))
+                        renameSync(backupAppDir, targetAppDir);
+                    throw error;
+                }
+                rmSync(backupAppDir, { recursive: true, force: true });
+            }
+            else if (existsSync(targetAppDir)) {
                 if (!input.force)
                     return { ok: false, error: `App already exists: apps/${committedPlan.appId}`, status: 409 };
                 rmSync(backupAppDir, { recursive: true, force: true });
                 renameSync(targetAppDir, backupAppDir);
+                try {
+                    renameSync(stagedAppDir, targetAppDir);
+                    rmSync(backupAppDir, { recursive: true, force: true });
+                }
+                catch (error) {
+                    if (existsSync(backupAppDir) && !existsSync(targetAppDir))
+                        renameSync(backupAppDir, targetAppDir);
+                    throw error;
+                }
             }
-            try {
+            else {
                 renameSync(stagedAppDir, targetAppDir);
-                rmSync(backupAppDir, { recursive: true, force: true });
-            }
-            catch (error) {
-                if (existsSync(backupAppDir) && !existsSync(targetAppDir))
-                    renameSync(backupAppDir, targetAppDir);
-                throw error;
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             return { ok: false, error: message, status: message.includes('already exists') ? 409 : 400 };
         }
+        finally {
+            rmSync(stagingRoot, { recursive: true, force: true });
+        }
         const attachWarnings = [];
         await ensureMetadataCatalogFresh(projectRoot, { force: true });
         const app = collectAppsList(projectRoot).find((entry) => entry.id === committedPlan.appId) ?? null;
@@ -1518,6 +1853,13 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
             validation,
             generatedPaths: generated.paths,
             committedTileIds: Array.from(selected),
+            committedBrief: {
+                ...(isExistingPageBuild
+                    ? { pageTitle: committedPlan.pages[0]?.title }
+                    : { appName: committedPlan.name }),
+                audience: committedPlan.audience,
+                tileOverrides,
+            },
             warnings: [...session.warnings, ...attachWarnings],
         };
         writeAppAiBuildSession(projectRoot, next);
@@ -1578,6 +1920,11 @@ async function routeAppAskQuestion(ctx, appId, input) {
     const tile = dashboard?.layout.items.find((item) => item.i === input.tileId ||
         (input.blockId && item.block && 'blockId' in item.block && item.block.blockId === input.blockId));
     const blockId = cleanString(input.blockId) || (tile?.block && 'blockId' in tile.block ? tile.block.blockId : undefined);
+    const appContext = buildAppContextEnvelope(loaded.app, loaded.appDir, {
+        dashboardId,
+        tileId: cleanString(input.tileId) || undefined,
+        blockId,
+    });
     const citations = [
         { kind: 'app', name: loaded.app.name, path: loaded.appPath },
         ...(dashboard ? [{ kind: 'dashboard', name: dashboard.metadata.title, path: `${loaded.appPath}/dashboards/${dashboard.id}.dqld` }] : []),
@@ -1601,11 +1948,20 @@ async function routeAppAskQuestion(ctx, appId, input) {
             decision,
             proposal: {
                 type: 'app_change',
+                version: 1,
                 dashboardId,
                 tileId: input.tileId,
                 blockId,
                 question,
                 reviewRequired: true,
+                expectedDashboardFingerprint: dashboard
+                    ? `sha256:${createHash('sha256').update(JSON.stringify(dashboard)).digest('hex')}`
+                    : undefined,
+                operations: [{
+                        op: 'review_in_build_mode',
+                        target: cleanString(input.tileId) || dashboardId || appId,
+                        suggestion: appChangeSuggestion(question),
+                    }],
             },
         };
     }
@@ -1635,6 +1991,7 @@ async function routeAppAskQuestion(ctx, appId, input) {
                 variables: input.variables,
                 selectedTile: tile ? appAskTileContext(tile) : undefined,
                 userContext: input.context,
+                appContext,
             },
         };
         if (input.runInvestigation === false) {
@@ -1669,6 +2026,7 @@ async function routeAppAskQuestion(ctx, appId, input) {
                     variables: input.variables,
                     selectedTile: tile ? appAskTileContext(tile) : undefined,
                     userContext: input.context,
+                    appContext,
                     routeDecision: decision,
                 },
             });
@@ -1719,7 +2077,7 @@ async function routeAppAskQuestion(ctx, appId, input) {
     // surfaces use: question-first retrieval finds the best-matching certified block
     // across the app, generates review-required SQL, or digs deeper — instead of
     // narrating whichever tile happens to be focused.
-    const governed = await tryGovernedAppAnswer(ctx, question, { blockId, appName: loaded.app.name, citations });
+    const governed = await tryGovernedAppAnswer(ctx, question, { blockId, appName: loaded.app.name, citations, appContext });
     if (governed)
         return governed;
     // Offline / no AI provider: keep the focused tile as a graceful fallback.
@@ -1847,7 +2205,7 @@ async function tryGovernedAppAnswer(ctx, question, input) {
     if (!ctx.generateGovernedAnswer)
         return null;
     try {
-        const governed = await ctx.generateGovernedAnswer(question);
+        const governed = await ctx.generateGovernedAnswer(question, input.appContext);
         return governed ? mapGovernedToAppAsk(governed, { question, ...input }) : null;
     }
     catch {
@@ -2032,24 +2390,32 @@ export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
     const loaded = loadAppById(projectRoot, appId);
     if (!loaded)
         return { ok: false, error: `App "${appId}" not found` };
+    const dashboardSources = findDashboardsForApp(loaded.appDir)
+        .map((path) => ({ path, document: loadDashboardDocument(path).document }))
+        .filter((item) => Boolean(item.document));
+    const readiness = appPublicationReadiness(dashboardSources.map((item) => item.document));
+    if (!readiness.ready) {
+        return {
+            ok: false,
+            error: `App is not ready for shared publication: ${readiness.blockers.map((blocker) => blocker.message).join('; ')}`,
+            readiness,
+        };
+    }
     const lifecycle = input.lifecycle === 'certified' || input.lifecycle === 'deprecated' ? input.lifecycle : 'review';
     const app = {
         ...loaded.app,
         visibility: 'shared',
+        publicationIntent: 'shared_project',
         lifecycle,
     };
     const appPath = join(loaded.appDir, 'dql.app.json');
     const parsedApp = parseAppDocument(JSON.stringify(app), appPath);
     if (!parsedApp.document)
         return { ok: false, error: parsedApp.errors.map((err) => err.message).join('; ') };
-    writeFileSync(appPath, JSON.stringify(parsedApp.document, null, 2) + '\n', 'utf-8');
     let removedLocalTiles = 0;
-    const paths = [relative(projectRoot, appPath)];
-    for (const dashboardPath of findDashboardsForApp(loaded.appDir)) {
-        const loadedDashboard = loadDashboardDocument(dashboardPath).document;
-        if (!loadedDashboard)
-            continue;
-        const items = loadedDashboard.layout.items
+    const dashboards = [];
+    for (const source of dashboardSources) {
+        const items = source.document.layout.items
             .filter((item) => {
             if (item.aiPin) {
                 removedLocalTiles += 1;
@@ -2059,24 +2425,129 @@ export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
         })
             .map((item) => promoteSharedDashboardItem(item));
         const dashboard = {
-            ...loadedDashboard,
+            ...source.document,
             metadata: {
-                ...loadedDashboard.metadata,
+                ...source.document.metadata,
                 visibility: 'shared',
                 lifecycle,
             },
             layout: {
-                ...loadedDashboard.layout,
+                ...source.document.layout,
                 items,
             },
         };
-        const parsed = parseDashboardDocument(JSON.stringify(dashboard), dashboardPath);
+        const parsed = parseDashboardDocument(JSON.stringify(dashboard), source.path);
         if (!parsed.document)
             return { ok: false, error: parsed.errors.map((err) => err.message).join('; ') };
-        writeFileSync(dashboardPath, JSON.stringify(parsed.document, null, 2) + '\n', 'utf-8');
-        paths.push(relative(projectRoot, dashboardPath));
+        dashboards.push({ sourcePath: source.path, document: parsed.document });
+    }
+    // Stage and swap the whole App directory so validation or write failures do
+    // not leave a partially published manifest/dashboard set.
+    const stagingBase = join(projectRoot, '.dql', 'local', 'app-publish-staging');
+    const stagedAppDir = join(stagingBase, `${appId}-next`);
+    const backupAppDir = join(stagingBase, `${appId}-backup`);
+    rmSync(stagedAppDir, { recursive: true, force: true });
+    rmSync(backupAppDir, { recursive: true, force: true });
+    mkdirSync(stagingBase, { recursive: true });
+    cpSync(loaded.appDir, stagedAppDir, { recursive: true });
+    writeFileSync(join(stagedAppDir, 'dql.app.json'), JSON.stringify(parsedApp.document, null, 2) + '\n', 'utf-8');
+    for (const dashboard of dashboards) {
+        const stagedPath = join(stagedAppDir, relative(loaded.appDir, dashboard.sourcePath));
+        writeFileSync(stagedPath, JSON.stringify(dashboard.document, null, 2) + '\n', 'utf-8');
+    }
+    try {
+        renameSync(loaded.appDir, backupAppDir);
+        renameSync(stagedAppDir, loaded.appDir);
+        rmSync(backupAppDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (existsSync(backupAppDir) && !existsSync(loaded.appDir))
+            renameSync(backupAppDir, loaded.appDir);
+        throw error;
     }
-    return { ok: true, app: parsedApp.document, paths, removedLocalTiles };
+    const paths = [relative(projectRoot, appPath), ...dashboards.map((dashboard) => relative(projectRoot, dashboard.sourcePath))];
+    return { ok: true, app: parsedApp.document, paths, removedLocalTiles, readiness };
+}
+export function approveAppSemanticTiles(projectRoot, appId, dashboardId, input) {
+    const loaded = loadDashboardForApp(projectRoot, appId, dashboardId);
+    if (!loaded)
+        return { ok: false, error: `Dashboard "${dashboardId}" not found in App "${appId}".` };
+    const currentFingerprint = `sha256:${createHash('sha256').update(JSON.stringify(loaded.dashboard)).digest('hex')}`;
+    if (!input.expectedDashboardFingerprint || input.expectedDashboardFingerprint !== currentFingerprint) {
+        return { ok: false, error: 'The dashboard changed after the reviewed run. Run it again before approval.' };
+    }
+    const selected = new Set(input.tileIds);
+    const semanticIds = new Set(loaded.dashboard.layout.items.filter((item) => item.semantic).map((item) => item.i));
+    const invalid = input.tileIds.filter((tileId) => !semanticIds.has(tileId));
+    if (invalid.length > 0)
+        return { ok: false, error: `Only semantic tiles can be approved here: ${invalid.join(', ')}` };
+    const reviewedAt = new Date().toISOString();
+    const dashboard = {
+        ...loaded.dashboard,
+        layout: {
+            ...loaded.dashboard.layout,
+            items: loaded.dashboard.layout.items.map((item) => {
+                if (!selected.has(item.i) || !item.semantic)
+                    return item;
+                return {
+                    ...item,
+                    semantic: { ...item.semantic, snapshotId: input.snapshotId },
+                    review: {
+                        status: 'approved',
+                        sourceFingerprint: item.semantic.definitionFingerprint,
+                        preflightReceiptId: input.runId,
+                        reviewedAt,
+                        reviewedBy: input.reviewer,
+                    },
+                    trustState: 'review_required',
+                    reviewStatus: 'review_required',
+                };
+            }),
+        },
+    };
+    const parsed = parseDashboardDocument(JSON.stringify(dashboard), loaded.path);
+    if (!parsed.document)
+        return { ok: false, error: parsed.errors.map((error) => error.message).join('; ') };
+    writeFileSync(loaded.path, JSON.stringify(parsed.document, null, 2) + '\n', 'utf-8');
+    return { ok: true, dashboard: parsed.document, path: relative(projectRoot, loaded.path) };
+}
+function appPublicationReadiness(dashboards) {
+    const blockers = [];
+    let governedTiles = 0;
+    for (const dashboard of dashboards) {
+        for (const item of dashboard.layout.items) {
+            if (item.block)
+                governedTiles += 1;
+            if (item.draftAnalysis) {
+                blockers.push({
+                    dashboardId: dashboard.id,
+                    tileId: item.i,
+                    code: 'exploratory_source',
+                    message: `${dashboard.id}/${item.i} references app-scoped exploratory DQL; promote it to governed semantic logic or a certified block first.`,
+                });
+            }
+            if (item.semantic) {
+                governedTiles += 1;
+                if (item.review?.status !== 'approved') {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'semantic_review',
+                        message: `${dashboard.id}/${item.i} semantic result has not been explicitly approved.`,
+                    });
+                }
+                if (!item.semantic.snapshotId || !item.review?.preflightReceiptId) {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'semantic_preflight',
+                        message: `${dashboard.id}/${item.i} needs a snapshot-bound semantic preflight receipt.`,
+                    });
+                }
+            }
+        }
+    }
+    return { ready: blockers.length === 0, governedTiles, blockers };
 }
 function appAiBuildSessionDir(projectRoot) {
     return join(projectRoot, '.dql', 'local', 'app-ai-builds');
@@ -2163,6 +2634,10 @@ function appAskTileContext(tile) {
         tileId: tile.i,
         title: tile.title,
         blockId: tile.block && 'blockId' in tile.block ? tile.block.blockId : undefined,
+        semantic: tile.semantic,
+        draftAnalysis: tile.draftAnalysis,
+        sourceClass: tile.sourceClass ?? (tile.block ? 'certified_block' : tile.semantic ? 'governed_semantic' : tile.draftAnalysis ? 'exploratory_analysis' : 'narrative'),
+        review: tile.review,
         viz: tile.viz.type,
         trustState: tile.trustState ?? tile.display?.trustState,
         reviewStatus: tile.reviewStatus ?? tile.display?.reviewStatus,
@@ -2171,6 +2646,34 @@ function appAskTileContext(tile) {
         sourceEvidence: tile.sourceEvidence,
     };
 }
+function buildAppContextEnvelope(app, appDir, focus) {
+    const dashboards = findDashboardsForApp(appDir)
+        .map((path) => loadDashboardDocument(path).document)
+        .filter((document) => Boolean(document))
+        .map((document) => ({
+        id: document.id,
+        title: document.metadata.title,
+        filters: document.filters,
+        story: document.story,
+        tiles: document.layout.items.map(appAskTileContext),
+    }));
+    return {
+        version: 1,
+        app: {
+            id: app.id,
+            name: app.name,
+            domain: app.domain,
+            audience: app.audience,
+            lifecycle: app.lifecycle ?? 'draft',
+            visibility: app.visibility ?? 'shared',
+            publicationIntent: app.publicationIntent ?? (app.visibility === 'private' ? 'personal' : 'shared_project'),
+            businessOutcome: app.businessOutcome,
+            caveats: app.caveats ?? [],
+        },
+        dashboards,
+        focus,
+    };
+}
 function filterBindingsForBlockSource(projectRoot, block) {
     const absPath = join(projectRoot, block.path);
     if (!existsSync(absPath))
@@ -2354,6 +2857,35 @@ function promoteSharedDashboardItem(item) {
         reviewStatus,
     };
 }
+export function deleteAppPackage(projectRoot, id) {
+    const cleanId = cleanString(id);
+    if (!cleanId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cleanId)) {
+        return { ok: false, status: 400, error: 'A valid App id is required.' };
+    }
+    const loaded = loadAppById(projectRoot, cleanId);
+    if (!loaded)
+        return { ok: false, status: 404, error: `App "${cleanId}" not found.` };
+    const relativeAppDir = relative(projectRoot, loaded.appDir).replaceAll('\\', '/');
+    const isProjectApp = /^apps\/[^/]+$/.test(relativeAppDir);
+    const isDomainApp = /^domains\/(?:[^/]+\/)*apps\/[^/]+$/.test(relativeAppDir);
+    if ((!isProjectApp && !isDomainApp) || relativeAppDir.startsWith('../')) {
+        return { ok: false, status: 400, error: 'DQL refused to delete an App outside this project.' };
+    }
+    const trashRoot = join(projectRoot, '.dql', 'trash', 'apps');
+    mkdirSync(trashRoot, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    let trashDir = join(trashRoot, `${stamp}-${cleanId}`);
+    let suffix = 2;
+    while (existsSync(trashDir))
+        trashDir = join(trashRoot, `${stamp}-${cleanId}-${suffix++}`);
+    renameSync(loaded.appDir, trashDir);
+    return {
+        ok: true,
+        id: cleanId,
+        deletedPath: relativeAppDir,
+        trashPath: relative(projectRoot, trashDir).replaceAll('\\', '/'),
+    };
+}
 export function createAppPackage(projectRoot, input) {
     const name = cleanString(input.name);
     const domain = cleanString(input.ownerDomain) || cleanString(input.domain);
@@ -4474,6 +5006,15 @@ function asRecord(value) {
 function cleanString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
+function appAiBuildSessionId(requested) {
+    const clean = cleanString(requested);
+    if (clean) {
+        if (!/^app_build_[a-z0-9_:-]+$/i.test(clean))
+            throw new Error('Invalid App build session id.');
+        return clean;
+    }
+    return `app_build_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
 function stringArray(value) {
     if (!Array.isArray(value))
         return undefined;
@@ -4495,6 +5036,43 @@ function slugify(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+function uniqueAppPageId(base, existingIds) {
+    if (!existingIds.has(base))
+        return base;
+    for (let index = 2; index < 1000; index += 1) {
+        const candidate = `${base}-${index}`;
+        if (!existingIds.has(candidate))
+            return candidate;
+    }
+    return `${base}-${Date.now()}`;
+}
+/**
+ * API-009: bind an existing-App proposal to every Git-owned byte in the package. This is
+ * deliberately stricter than the metadata snapshot: page, notebook, draft, and
+ * App-document edits all invalidate approval before the atomic directory swap.
+ */
+function fingerprintAppDirectory(appDir) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolutePath = join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(absolutePath);
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                files.push({ path: absolutePath, symbolicLink: entry.isSymbolicLink() });
+            }
+        }
+    };
+    visit(appDir);
+    const hash = createHash('sha256');
+    for (const file of files.sort((left, right) => left.path.localeCompare(right.path))) {
+        hash.update(relative(appDir, file.path));
+        hash.update('\0');
+        hash.update(file.symbolicLink ? `link:${readlinkSync(file.path)}` : readFileSync(file.path));
+        hash.update('\0');
+    }
+    return `sha256:${hash.digest('hex')}`;
+}
 function resolveAppPackageDir(projectRoot, id) {
     return join(projectRoot, 'apps', id);
 }
@@ -5204,7 +5782,7 @@ function loadDashboardForApp(projectRoot, appId, dashboardId) {
         for (const d of findDashboardsForApp(appDir)) {
             const { document: dd } = loadDashboardDocument(d);
             if (dd && dd.id === dashboardId) {
-                return { app: document, dashboard: dd };
+                return { app: document, dashboard: dd, path: d };
             }
         }
     }