@duckcodeailabs/dql-cli 1.13.1 → 1.13.3

package/dist/apps-api.js

@@ -6,7 +6,7 @@
 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';
+import { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboardsForApp, parseAppDocument, parseDashboardDocument, normalizeDqlArtifactReference, suggestAppId, createAppBuildDraft, appBuildDraftHash, applyAppBuildDraftOperations, } from '@duckcodeailabs/dql-core';
 import { defaultPersonaRegistry, defaultLocalAppsDbPath, LocalAppStorage, personaFromMember, } from '@duckcodeailabs/dql-project';
 export async function handleAppsApi(ctx) {
     const { req, res, path, projectRoot } = ctx;
@@ -26,6 +26,342 @@ export async function handleAppsApi(ctx) {
         return true;
     }
     // ── Apps ────────────────────────────────────────────────────────────────
+    if (req.method === 'POST' && path === '/api/app-builds') {
+        try {
+            const body = await readJson(req);
+            const draft = createStoredAppBuildDraft(projectRoot, body);
+            sendJson(res, 201, { ok: true, draft });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    if (req.method === 'GET' && path === '/api/app-builds') {
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            const drafts = storage.listAppBuildDrafts().flatMap((stored) => {
+                const migrated = migrateLegacyAppBuildDraft(projectRoot, stored);
+                if (!migrated)
+                    return [];
+                if (stored.version !== migrated.version)
+                    storage.saveAppBuildDraft(migrated);
+                return [migrated];
+            });
+            sendJson(res, 200, { ok: true, drafts });
+        }
+        finally {
+            storage.close();
+        }
+        return true;
+    }
+    const sourceCandidatesMatch = path.match(/^\/api\/app-builds\/([^/]+)\/source-candidates$/);
+    if (sourceCandidatesMatch && req.method === 'GET') {
+        try {
+            const id = decodeURIComponent(sourceCandidatesMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const { ensureAgentProjectReady, queryAppSourceCatalog } = await import('@duckcodeailabs/dql-agent');
+            await ensureAgentProjectReady(projectRoot);
+            const lifecycles = splitQueryValues(ctx.url.searchParams.getAll('lifecycle'));
+            const domains = splitQueryValues(ctx.url.searchParams.getAll('domain'));
+            const page = queryAppSourceCatalog(projectRoot, {
+                query: ctx.url.searchParams.get('q') ?? undefined,
+                cursor: ctx.url.searchParams.get('cursor') ?? undefined,
+                limit: Number(ctx.url.searchParams.get('limit')) || 50,
+                lifecycles: lifecycles.length ? lifecycles : undefined,
+                domains: domains.length ? domains : undefined,
+                sourcePolicy: current.sourcePolicy,
+                includeDeprecated: ctx.url.searchParams.get('includeDeprecated') === 'true',
+            });
+            sendJson(res, 200, { ok: true, ...page });
+        }
+        catch (err) {
+            const error = err;
+            sendJson(res, error.code?.includes('CURSOR') ? 409 : 400, { ok: false, code: error.code, error: error.message });
+        }
+        return true;
+    }
+    if (sourceCandidatesMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(sourceCandidatesMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            const { ensureAgentProjectReady, resolveAppSourceCatalogRecords } = await import('@duckcodeailabs/dql-agent');
+            await ensureAgentProjectReady(projectRoot);
+            const result = resolveAppSourceCatalogRecords(projectRoot, body.sourceIds ?? [], current.sourcePolicy);
+            sendJson(res, 200, { ok: true, ...result });
+        }
+        catch (err) {
+            const error = err;
+            sendJson(res, 400, { ok: false, code: error.code, error: error.message });
+        }
+        return true;
+    }
+    let buildMatch = path.match(/^\/api\/app-builds\/([^/]+)$/);
+    if (buildMatch && req.method === 'GET') {
+        const draft = loadStoredAppBuildDraft(projectRoot, decodeURIComponent(buildMatch[1]));
+        sendJson(res, draft ? 200 : 404, draft ? { ok: true, draft } : { ok: false, error: 'App Build Draft not found.' });
+        return true;
+    }
+    if (buildMatch && req.method === 'PATCH') {
+        try {
+            const id = decodeURIComponent(buildMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedProposalHash && body.expectedProposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_PROPOSAL_CONFLICT: refresh the local draft before applying changes.' });
+                return true;
+            }
+            const next = applyAppBuildDraftOperations(current, body.expectedRevision ?? -1, body.operations ?? []);
+            writeStoredAppBuildDraft(projectRoot, next, {
+                expectedRevision: current.revision,
+                operations: body.operations ?? [],
+            });
+            sendJson(res, 200, { ok: true, draft: next });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('APP_BUILD_REVISION_CONFLICT') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
+    if (buildMatch && req.method === 'DELETE') {
+        try {
+            const id = decodeURIComponent(buildMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.proposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before deleting this local draft.' });
+                return true;
+            }
+            sendJson(res, 200, deleteStoredAppBuildDraft(projectRoot, current));
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    const askResultMatch = path.match(/^\/api\/app-builds\/([^/]+)\/ask-results$/);
+    if (askResultMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(askResultMatch[1]);
+            const body = await readJson(req);
+            const result = addAskResultToAppBuildDraft(projectRoot, id, body);
+            sendJson(res, result.deduped ? 200 : 201, result);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('APP_BUILD_') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
+    const draftAiProposalMatch = path.match(/^\/api\/app-builds\/([^/]+)\/ai-proposals$/);
+    if (draftAiProposalMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(draftAiProposalMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.proposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before asking AI to change this draft.' });
+                return true;
+            }
+            const proposal = await proposeAppBuildDraftOperations(projectRoot, current, {
+                prompt: cleanString(body.prompt) || current.frame.goal,
+                selectedBlockIds: body.selectedBlockIds,
+            }, { generateGovernedAnswer: ctx.generateGovernedAnswer, planAppBuild: ctx.planAppBuild });
+            writeAppBuildDraftAiProposal(projectRoot, proposal);
+            sendJson(res, 201, { ok: true, proposal });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    const composeBuildMatch = path.match(/^\/api\/app-builds\/([^/]+)\/compose$/);
+    if (composeBuildMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(composeBuildMatch[1]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.expectedProposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before composing this App.' });
+                return true;
+            }
+            const result = await composeStoredAppBuildDraft(projectRoot, current, body);
+            sendJson(res, 200, { ok: true, ...result });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('APP_BUILD_') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
+    const reviseProposalMatch = path.match(/^\/api\/app-builds\/([^/]+)\/ai-proposals\/([^/]+)\/revisions$/);
+    if (reviseProposalMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(reviseProposalMatch[1]);
+            const proposalId = decodeURIComponent(reviseProposalMatch[2]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            const previous = current ? loadAppBuildDraftAiProposal(projectRoot, id, proposalId) : null;
+            if (!current || !previous) {
+                sendJson(res, 404, { ok: false, error: 'App Build proposal not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.expectedProposalHash !== current.proposalHash
+                || previous.baseRevision !== current.revision || previous.baseProposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_PROPOSAL_CONFLICT: refresh before revising this proposal.' });
+                return true;
+            }
+            const answers = body.answers ?? {};
+            const answerText = previous.clarifications.flatMap((question) => {
+                const answerId = answers[question.id];
+                const choice = question.choices.find((candidate) => candidate.id === answerId);
+                return choice ? [`${question.question}: ${choice.label}`] : [];
+            });
+            const selectedSourceIds = unique([
+                ...(body.selectedSourceIds ?? previous.defaultSelectedSourceIds ?? []),
+                ...(body.additionalSourceIds ?? []),
+            ].map(cleanString).filter(Boolean));
+            const proposal = await proposeAppBuildDraftOperations(projectRoot, current, {
+                prompt: [current.frame.goal, answerText.length ? `Clarification decisions: ${answerText.join('; ')}` : ''].filter(Boolean).join('\n'),
+                selectedBlockIds: selectedSourceIds,
+            }, { generateGovernedAnswer: ctx.generateGovernedAnswer, planAppBuild: ctx.planAppBuild });
+            proposal.defaultSelectedSourceIds = selectedSourceIds.filter((sourceId) => proposal.operations.some((operation) => (operation.type === 'upsert_source' && operation.source.id === sourceId)));
+            writeAppBuildDraftAiProposal(projectRoot, proposal);
+            sendJson(res, 201, { ok: true, proposal });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    const generateGapMatch = path.match(/^\/api\/app-builds\/([^/]+)\/ai-proposals\/([^/]+)\/gaps$/);
+    if (generateGapMatch && req.method === 'POST') {
+        try {
+            const id = decodeURIComponent(generateGapMatch[1]);
+            const proposalId = decodeURIComponent(generateGapMatch[2]);
+            const current = loadStoredAppBuildDraft(projectRoot, id);
+            const previous = current ? loadAppBuildDraftAiProposal(projectRoot, id, proposalId) : null;
+            if (!current || !previous) {
+                sendJson(res, 404, { ok: false, error: 'App Build proposal not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.expectedProposalHash !== current.proposalHash
+                || previous.baseRevision !== current.revision || previous.baseProposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_PROPOSAL_CONFLICT: refresh before generating a gap.' });
+                return true;
+            }
+            if (current.sourcePolicy !== 'include_review_required') {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVIEW_POLICY_REQUIRED: enable review-required sources before generating a gap.' });
+                return true;
+            }
+            if (!ctx.generateGovernedAnswer)
+                throw new Error('The configured provider cannot generate an App gap in this runtime.');
+            const proposal = await generateExplicitAppBuildGap(projectRoot, current, previous, cleanString(body.requirementId), ctx.generateGovernedAnswer);
+            writeAppBuildDraftAiProposal(projectRoot, proposal);
+            sendJson(res, 201, { ok: true, proposal });
+        }
+        catch (err) {
+            sendJson(res, 400, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    buildMatch = path.match(/^\/api\/app-builds\/([^/]+)\/preflight$/);
+    if (buildMatch && req.method === 'POST') {
+        const current = loadStoredAppBuildDraft(projectRoot, decodeURIComponent(buildMatch[1]));
+        if (!current) {
+            sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+            return true;
+        }
+        const body = await readJson(req);
+        if ((body.expectedRevision !== undefined && body.expectedRevision !== current.revision)
+            || (body.proposalHash && body.proposalHash !== current.proposalHash)) {
+            sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh before preflight.' });
+            return true;
+        }
+        const errors = preflightAppBuildRequestErrors(projectRoot, current, ctx.verifyAppBuildPreview);
+        if (errors.length) {
+            sendJson(res, 400, {
+                ok: false,
+                code: 'APP_BUILD_NOT_READY',
+                message: 'This App is not ready to publish yet.',
+                draft: current,
+                errors,
+                details: { draft: current, errors },
+            });
+            return true;
+        }
+        const next = markStoredAppBuildDraftPreflighted(projectRoot, current);
+        sendJson(res, 200, { ok: true, draft: next, errors: [] });
+        return true;
+    }
+    buildMatch = path.match(/^\/api\/app-builds\/([^/]+)\/(publish-to-project|commit)$/);
+    if (buildMatch && req.method === 'POST') {
+        try {
+            const current = loadStoredAppBuildDraft(projectRoot, decodeURIComponent(buildMatch[1]));
+            if (!current) {
+                sendJson(res, 404, { ok: false, error: 'App Build Draft not found.' });
+                return true;
+            }
+            const body = await readJson(req);
+            if (body.expectedRevision !== current.revision || body.proposalHash !== current.proposalHash) {
+                sendJson(res, 409, { ok: false, error: 'APP_BUILD_REVISION_CONFLICT: refresh the Build Frame before committing.' });
+                return true;
+            }
+            const errors = preflightAppBuildRequestErrors(projectRoot, current, ctx.verifyAppBuildPreview);
+            if (errors.length) {
+                sendJson(res, 400, {
+                    ok: false,
+                    code: 'APP_BUILD_NOT_READY',
+                    message: 'This App is not ready to publish yet.',
+                    draft: current,
+                    errors,
+                    details: { draft: current, errors },
+                });
+                return true;
+            }
+            // The final confirmation consumes the exact receipt the user reviewed.
+            // Compatibility callers that arrive without one are preflighted once in
+            // this same request so they cannot enter a client-side recheck loop.
+            const prepared = hasCurrentAppBuildPreflightReceipt(current)
+                ? current
+                : markStoredAppBuildDraftPreflighted(projectRoot, current);
+            const result = publishStoredAppBuildDraft(projectRoot, prepared);
+            await refreshGeneratedMetadata(projectRoot);
+            sendJson(res, 201, { ...result, compatibilityRoute: buildMatch[2] === 'commit' });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendJson(res, message.includes('already exists') ? 409 : 400, { ok: false, error: message });
+        }
+        return true;
+    }
     if (req.method === 'GET' && path === '/api/apps') {
         const apps = collectAppsList(projectRoot);
         sendJson(res, 200, { apps });
@@ -34,7 +370,16 @@ export async function handleAppsApi(ctx) {
     if (req.method === 'POST' && path === '/api/apps/recommend-blocks') {
         try {
             const body = await readJson(req);
-            sendJson(res, 200, { blocks: recommendBlocks(projectRoot, body) });
+            const { ensureAgentProjectReady, queryAppSourceCatalog } = await import('@duckcodeailabs/dql-agent');
+            await ensureAgentProjectReady(projectRoot);
+            const page = queryAppSourceCatalog(projectRoot, {
+                query: [body.purpose, body.audience, ...(body.tags ?? [])].filter(Boolean).join(' '),
+                domains: body.domain && body.domain !== 'general' ? [body.domain] : undefined,
+                lifecycles: body.certifiedOnly ? ['certified'] : undefined,
+                sourcePolicy: body.certifiedOnly ? 'governed_only' : 'include_review_required',
+                limit: 50,
+            });
+            sendJson(res, 200, { blocks: page.items.map(appSourceCatalogRecordToLegacyRecommendation) });
         }
         catch (err) {
             sendJson(res, 500, { error: err.message });
@@ -156,7 +501,9 @@ export async function handleAppsApi(ctx) {
     if (req.method === 'POST' && path === '/api/apps') {
         try {
             const body = await readJson(req);
-            const result = createAppPackage(projectRoot, body);
+            // Compatibility adapter: the legacy manual endpoint now traverses the
+            // same versioned draft, preflight, and private commit service as Studio.
+            const result = createAppPackageViaBuildDraft(projectRoot, body);
             if (!result.ok) {
                 sendJson(res, 400, { error: result.error });
                 return true;
@@ -204,6 +551,24 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    m = path.match(/^\/api\/apps\/([^/]+)\/publish-to-project$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = promoteAppForStakeholders(projectRoot, appId, body);
+            if (!result.ok) {
+                sendJson(res, 409, result);
+                return true;
+            }
+            await refreshGeneratedMetadata(projectRoot);
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
     m = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/approve-semantic$/);
     if (m && req.method === 'POST') {
         const appId = decodeURIComponent(m[1]);
@@ -714,7 +1079,8 @@ export async function handleAppsApi(ctx) {
     if (m && req.method === 'DELETE') {
         const id = decodeURIComponent(m[1]);
         try {
-            const result = deleteAppPackage(projectRoot, id);
+            const body = await readJson(req);
+            const result = deleteAppPackage(projectRoot, id, body);
             if (!result.ok) {
                 sendJson(res, result.status, { ok: false, error: result.error });
                 return true;
@@ -727,8 +1093,25 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    if (m && req.method === 'PATCH') {
+        const id = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = renameApp(projectRoot, id, body);
+            if (!result.ok) {
+                sendJson(res, result.code === 'APP_NOT_FOUND' ? 404 : result.code === 'APP_CHANGED' ? 409 : 400, result);
+                return true;
+            }
+            ctx.scheduleProjectRefresh?.('app-renamed');
+            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 id = decodeURIComponent(m[1]);
         const result = loadAppById(projectRoot, id);
         if (!result) {
             sendJson(res, 404, { error: `App "${id}" not found` });
@@ -737,6 +1120,22 @@ export async function handleAppsApi(ctx) {
         sendJson(res, 200, result);
         return true;
     }
+    m = path.match(/^\/api\/app-recoveries\/([^/]+)\/restore$/);
+    if (m && req.method === 'POST') {
+        try {
+            const result = restoreAppRecovery(projectRoot, decodeURIComponent(m[1]));
+            if (!result.ok) {
+                sendJson(res, result.status, result);
+                return true;
+            }
+            ctx.scheduleProjectRefresh?.('app-restored');
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err.message });
+        }
+        return true;
+    }
     // /api/apps/:id/dashboards
     m = path.match(/^\/api\/apps\/([^/]+)\/dashboards$/);
     if (m && req.method === 'GET') {
@@ -830,6 +1229,7 @@ function collectAppsList(projectRoot) {
         out.push({
             id: document.id,
             name: document.name,
+            fingerprint: fingerprintAppDirectory(appDir),
             filePath: relative(projectRoot, appDir),
             domain: document.domain,
             ownerDomain: document.ownerDomain,
@@ -1242,13 +1642,51 @@ function buildAppProposal(plan) {
         seenGap.add(question.toLowerCase());
         gaps.push({ id: `gap_${gaps.length + 1}`, question, reason: 'No certified block covers this question.' });
     }
+    const metrics = Array.from(new Set(plan.requirements.flatMap((requirement) => requirement.measures)));
+    const dimensions = Array.from(new Set(plan.requirements.flatMap((requirement) => requirement.dimensions)));
+    const filters = Array.from(new Set(plan.requirements.flatMap((requirement) => requirement.filters)));
+    const clarifications = [];
+    if (metrics.length === 0) {
+        clarifications.push({
+            id: 'metric',
+            question: 'Which governed business metric should lead this App?',
+            choices: ['Choose a certified block', 'Choose a semantic metric', 'Describe the calculation as review-required analysis'],
+            required: true,
+        });
+    }
+    if (tiles.length === 0 || gaps.length > 0) {
+        clarifications.push({
+            id: 'coverage',
+            question: 'How should DQL handle requirements without governed coverage?',
+            choices: ['Refine metrics or dimensions', 'Use governed semantic coverage', 'Include review-required analysis', 'Keep visible gaps'],
+            required: tiles.length === 0,
+        });
+    }
+    if (!plan.prompt.match(/\b(day|week|month|quarter|year|today|yesterday|current|previous|over time)\b/i)) {
+        clarifications.push({
+            id: 'time',
+            question: 'What time window and comparison should the App use?',
+            choices: ['Current period vs previous period', 'Trailing 30 days', 'Year to date', 'No time comparison'],
+            required: false,
+        });
+    }
     return {
         intent: {
             target: plan.publicationIntent,
             initialVisibility: 'private',
         },
+        buildFrame: {
+            goal: plan.businessGoal,
+            audience: plan.audience,
+            metrics,
+            dimensions,
+            grain: plan.requirements.find((requirement) => requirement.grain)?.grain,
+            filters,
+            desiredOutput: plan.planning.displayStrategy,
+        },
         tiles,
         gaps,
+        clarifications,
         followUps: gaps.map((gap) => gap.question).slice(0, 4),
         coverage: {
             certifiedTiles: tiles.filter((tile) => tile.certification === 'certified').length,
@@ -1343,6 +1781,7 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 certification: 'ai_generated',
                 sourceClass: 'exploratory_analysis',
                 reviewStatus: 'required',
+                requirementIds: gap.id.startsWith('gap_') ? [gap.id.slice('gap_'.length)] : undefined,
                 preflight: {
                     status: preview ? 'passed' : unresolvedExecutionError ? 'blocked' : 'review_required',
                     sourceFingerprint: `sha256:${createHash('sha256').update(sql).digest('hex')}`,
@@ -1383,6 +1822,7 @@ async function fillProposalGaps(proposal, hooks, maxGeneratedTiles) {
                 certification: 'ai_generated',
                 sourceClass: 'exploratory_analysis',
                 reviewStatus: 'required',
+                requirementIds: gap.id.startsWith('gap_') ? [gap.id.slice('gap_'.length)] : undefined,
                 preflight: {
                     status: 'blocked',
                     message: 'Exploratory analysis generation failed.',
@@ -1530,52 +1970,452 @@ export async function proposeAppAiBuild(projectRoot, input, hooks) {
         kg.close();
     }
 }
-/**
- * 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 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'));
-    if (!dashboardPath)
-        return;
-    const absolutePath = join(projectRoot, dashboardPath);
-    if (!existsSync(absolutePath))
-        return;
-    const doc = JSON.parse(readFileSync(absolutePath, 'utf-8'));
-    // 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')) {
-        doc.sections.push({
-            id: 'appendix',
-            title: 'AI-generated analysis — needs review',
-            kind: 'appendix',
-            order: doc.sections.length,
-        });
+function appDraftSourceFromCatalog(source) {
+    const certified = source.lifecycle === 'certified';
+    return {
+        id: source.sourceId,
+        kind: 'block',
+        sourceRef: source.executionRef,
+        qualifiedIdentity: source.qualifiedIdentity,
+        sourcePath: source.sourcePath,
+        executionRef: source.executionRef,
+        snapshotId: source.snapshotId,
+        sourceRevision: source.sourceRevision,
+        sourceFingerprint: source.sourceRevision,
+        lifecycle: source.lifecycle,
+        capabilities: source.capabilities,
+        trustState: certified ? 'certified' : 'review_required',
+        reviewStatus: certified ? 'not_required' : 'required',
+    };
+}
+function appSourceCatalogRecordToLegacyRecommendation(source) {
+    return {
+        id: source.sourceId,
+        name: source.name,
+        domain: source.domain ?? 'uncategorized',
+        status: source.lifecycle,
+        owner: source.owner ?? null,
+        tags: source.tags,
+        path: source.executionRef,
+        fingerprint: source.sourceRevision,
+        lastModified: new Date(0).toISOString(),
+        description: source.description ?? '',
+        llmContext: null,
+        chartType: source.capabilities.chartType,
+        filterIds: source.capabilities.filters,
+        dimensionIds: source.capabilities.dimensions,
+        score: source.score ?? 0,
+        reasons: source.reasons,
+    };
+}
+function uniqueAppSourceRecords(sources) {
+    const seen = new Set();
+    return sources.filter((source) => {
+        if (seen.has(source.sourceId))
+            return false;
+        seen.add(source.sourceId);
+        return true;
+    });
+}
+function uniqueTileId(existing, preferred) {
+    const base = slugify(preferred) || 'component';
+    const ids = new Set(existing.map((item) => item.i));
+    if (!ids.has(base))
+        return base;
+    for (let index = 2; index < 10_000; index += 1) {
+        const candidate = `${base}-${index}`;
+        if (!ids.has(candidate))
+            return candidate;
     }
-    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`);
+    return `${base}-${Date.now()}`;
+}
+const APP_REQUIREMENT_STOP_WORDS = new Set([
+    'a', 'an', 'and', 'app', 'application', 'build', 'by', 'create', 'dashboard',
+    'for', 'from', 'in', 'last', 'me', 'of', 'on', 'report', 'show', 'showing',
+    'the', 'to', 'using', 'view', 'with',
+]);
+function appRequirementTokens(value) {
+    return new Set(value.toLowerCase().split(/[^a-z0-9]+/)
+        .map((token) => token.length > 3 && token.endsWith('s') ? token.slice(0, -1) : token)
+        .filter((token) => token.length > 1 && !APP_REQUIREMENT_STOP_WORDS.has(token)));
+}
+function catalogSourceSatisfiesRequirement(source, requirement) {
+    const normalized = (values) => new Set(values.flatMap((value) => Array.from(appRequirementTokens(value))));
+    const sourceMeasures = normalized(source.capabilities.measures);
+    const sourceDimensions = normalized(source.capabilities.dimensions);
+    const sourceFilters = normalized(source.capabilities.filters);
+    const requires = [
+        [normalized(requirement.measures), sourceMeasures],
+        [normalized(requirement.dimensions), sourceDimensions],
+        [normalized(requirement.filters), sourceFilters],
+    ];
+    const declaredCompatible = requires.every(([required, available]) => (required.size === 0 || (available.size > 0 && Array.from(required).every((field) => available.has(field)))));
+    const hasDeclaredRequirement = requires.some(([required]) => required.size > 0);
+    if (declaredCompatible && hasDeclaredRequirement)
+        return true;
+    const requirementTerms = appRequirementTokens(requirement.question);
+    if (requirementTerms.size === 0)
+        return false;
+    const sourceTerms = appRequirementTokens([
+        source.title,
+        source.name,
+        source.description ?? '',
+        source.qualifiedIdentity,
+        ...source.tags,
+        ...source.capabilities.measures,
+        ...source.capabilities.dimensions,
+    ].join(' '));
+    const overlap = Array.from(requirementTerms).filter((term) => sourceTerms.has(term)).length;
+    return overlap >= Math.min(2, requirementTerms.size);
+}
+function splitQueryValues(values) {
+    return unique(values.flatMap((value) => value.split(',')).map((value) => value.trim()).filter(Boolean));
+}
+function materializeAppBuildProposalReviewAnalyses(projectRoot, draft, plan, proposalId, candidates, inputDashboards) {
+    const eligible = candidates.filter((candidate) => (candidate.source === 'ai_generated'
+        && Boolean(candidate.sql)
+        && !candidate.error
+        && candidate.preflight.status === 'passed'));
+    if (eligible.length === 0 || inputDashboards.length === 0) {
+        return { dashboards: inputDashboards, sourceOperations: [], reviewTasks: [], coverageByRequirement: new Map() };
+    }
+    const proposalKey = slugify(proposalId) || `proposal-${Date.now()}`;
+    const relativeDraftDir = `proposals/${proposalKey}/drafts`;
+    const absoluteDraftDir = join(projectRoot, '.dql', 'local', 'app-builds', draft.id, relativeDraftDir);
+    mkdirSync(absoluteDraftDir, { recursive: true });
+    const sourceOperations = [];
+    const reviewTasks = [];
+    const coverageByRequirement = new Map();
+    const generatedItems = [];
+    const normalizeQuestion = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    for (const [index, candidate] of eligible.entries()) {
+        const sql = candidate.sql;
+        if (sql.includes('"""'))
+            throw new Error(`Exploratory SQL for "${candidate.title}" contains an unsupported triple-quote delimiter.`);
+        const candidateKey = slugify(candidate.id) || `analysis-${index + 1}`;
+        const blockName = `app_${slugify(draft.appId)}_${candidateKey}`;
+        const sourceRef = `${relativeDraftDir}/${candidateKey}.dql`;
         const source = [
-            `block "${escapeDqlString(draftId)}" {`,
+            `block "${escapeDqlString(blockName)}" {`,
             `  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)}" }]` : '',
+            `  description = "${escapeDqlString((candidate.answer ?? candidate.question ?? candidate.title).slice(0, 240))}"`,
+            candidate.question ? `  llmContext = "${escapeDqlString(`App-scoped exploratory analysis. Question: ${candidate.question}`)}"` : '',
+            '  caveats = ["AI-generated App analysis. Validate joins, filters, grain, and business interpretation before promotion."]',
+            '  tags = ["app-scoped", "ai-generated", "needs-review"]',
+            '',
+            '  query = """',
+            sql,
+            '  """',
+            '',
+            '  visualization {',
+            `    chart = "${escapeDqlString(normalizeGeneratedViz(candidate.viz))}"`,
+            '  }',
+            '}',
+            '',
+        ].filter(Boolean).join('\n');
+        const fingerprint = `sha256:${createHash('sha256').update(source).digest('hex')}`;
+        writeFileSync(join(absoluteDraftDir, `${candidateKey}.dql`), source, 'utf-8');
+        const sourceId = `review-dql:${candidate.id}`;
+        const componentId = `review_${candidateKey}`;
+        sourceOperations.push({
+            type: 'upsert_source',
+            source: {
+                id: sourceId,
+                kind: 'review_dql',
+                sourceRef,
+                qualifiedIdentity: candidate.title,
+                snapshotId: candidate.preflight.snapshotId ?? plan.snapshotId,
+                sourceFingerprint: fingerprint,
+                receiptId: candidate.preflight.receiptId,
+                trustState: 'review_required',
+                reviewStatus: 'required',
+            },
+        });
+        reviewTasks.push({
+            type: 'set_review_task',
+            task: {
+                id: `review-generated-${candidateKey}`,
+                message: `Validate the joins, grain, filters, and business interpretation for ${candidate.title}.`,
+                status: 'open',
+                sourceId,
+                pageId: inputDashboards[0].id,
+                tileId: componentId,
+            },
+        });
+        const requirementIds = candidate.requirementIds?.length
+            ? candidate.requirementIds
+            : plan.requirements.filter((requirement) => normalizeQuestion(requirement.question) === normalizeQuestion(candidate.question ?? '')).map((requirement) => requirement.id);
+        for (const requirementId of requirementIds) {
+            const current = coverageByRequirement.get(requirementId) ?? { sourceIds: [], componentIds: [] };
+            current.sourceIds.push(sourceId);
+            current.componentIds.push(componentId);
+            coverageByRequirement.set(requirementId, current);
+        }
+        generatedItems.push({
+            i: componentId,
+            x: (index % 2) * 6,
+            y: Math.floor(index / 2) * 4,
+            w: 6,
+            h: 4,
+            draftAnalysis: {
+                ref: sourceRef,
+                artifactFingerprint: fingerprint,
+                ...(candidate.preflight.snapshotId ?? plan.snapshotId ? { snapshotId: candidate.preflight.snapshotId ?? plan.snapshotId } : {}),
+                ...(candidate.preflight.receiptId ? { executionReceiptId: candidate.preflight.receiptId } : {}),
+            },
+            viz: { type: normalizeGeneratedViz(candidate.viz) },
+            title: candidate.title,
+            sourceClass: 'exploratory_analysis',
+            sourceEvidence: [
+                ...(candidate.sourceEvidence ?? []),
+                {
+                    source: sourceRef,
+                    reason: candidate.question
+                        ? `AI generated this private analysis for: ${candidate.question}`
+                        : 'AI generated this private analysis for a requirement without governed coverage.',
+                    kind: 'review_dql',
+                    trustState: 'review_required',
+                },
+            ],
+            review: { status: 'required', sourceFingerprint: fingerprint, ...(candidate.preflight.receiptId ? { preflightReceiptId: candidate.preflight.receiptId } : {}) },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+        });
+    }
+    const first = inputDashboards[0];
+    const baseY = first.layout.items.reduce((max, item) => Math.max(max, item.y + item.h), 0);
+    const items = [...first.layout.items, ...generatedItems.map((item) => ({ ...item, y: item.y + baseY }))];
+    const sections = first.sections
+        ? first.sections.some((section) => section.kind === 'appendix')
+            ? first.sections
+            : [...first.sections, { id: 'review-appendix', title: 'Review-required analysis', kind: 'appendix', order: first.sections.length }]
+        : undefined;
+    const appendixId = sections?.find((section) => section.kind === 'appendix')?.id;
+    const finalItems = appendixId
+        ? items.map((item) => generatedItems.some((generated) => generated.i === item.i) ? { ...item, sectionId: appendixId } : item)
+        : items;
+    const page = {
+        ...first,
+        ...(sections ? { sections } : {}),
+        layout: {
+            ...first.layout,
+            items: finalItems,
+            responsive: responsiveLayoutsForDashboardItems(finalItems),
+        },
+    };
+    return {
+        dashboards: [page, ...inputDashboards.slice(1)],
+        sourceOperations,
+        reviewTasks,
+        coverageByRequirement,
+    };
+}
+/**
+ * AI is a coauthor of the same local AppBuildDraft used by manual authoring.
+ * This adapter reuses the governed planner, compiles its result outside the
+ * project, and returns typed operations. It does not mutate the draft or write
+ * any canonical App source.
+ */
+export async function proposeAppBuildDraftOperations(projectRoot, draft, input, hooks) {
+    const prompt = cleanString(input.prompt) || draft.frame.goal;
+    const { ensureAgentProjectReady, planAppBuildBrief, resolveAppSourceCatalogRecords, shortlistAppSources, } = await import('@duckcodeailabs/dql-agent');
+    await ensureAgentProjectReady(projectRoot);
+    let candidates = shortlistAppSources(projectRoot, prompt, {
+        sourcePolicy: draft.sourcePolicy,
+        domains: draft.pages[0]?.metadata.domain && draft.pages[0].metadata.domain !== 'general'
+            ? [draft.pages[0].metadata.domain]
+            : undefined,
+    }).items;
+    const requestedIds = unique((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean));
+    if (requestedIds.length) {
+        const exactIds = requestedIds.filter((id) => id.startsWith('app:block:'));
+        const exact = exactIds.length
+            ? resolveAppSourceCatalogRecords(projectRoot, exactIds, draft.sourcePolicy).items
+            : [];
+        const requested = new Set(requestedIds);
+        candidates = uniqueAppSourceRecords([
+            ...exact,
+            ...candidates.filter((candidate) => requested.has(candidate.sourceId)
+                || requested.has(candidate.name)
+                || requested.has(candidate.sourcePath)
+                || requested.has(candidate.qualifiedIdentity)),
+            ...candidates,
+        ]).slice(0, 12);
+    }
+    const brief = await planAppBuildBrief({
+        prompt,
+        candidates,
+        sourcePolicy: draft.sourcePolicy,
+        domain: draft.pages[0]?.metadata.domain,
+        audience: draft.frame.audience,
+        complete: hooks?.planAppBuild,
+    });
+    const byId = new Map(candidates.map((candidate) => [candidate.sourceId, candidate]));
+    const plannedSources = brief.selectedSourceIds.flatMap((sourceId) => {
+        const source = byId.get(sourceId);
+        return source ? [source] : [];
+    });
+    const sourceOperations = plannedSources.map((source) => ({
+        type: 'upsert_source',
+        source: appDraftSourceFromCatalog(source),
+    }));
+    const page = draft.pages[0];
+    if (!page)
+        throw new Error('The App draft needs a page before AI can compose it.');
+    const structuralItems = page.layout.items.filter((item) => Boolean(item.text));
+    const baseY = structuralItems.reduce((max, item) => Math.max(max, item.y + item.h), 0);
+    const reservedItems = [...structuralItems];
+    const componentTileIdById = new Map();
+    const plannedItems = brief.components.flatMap((component, index) => {
+        const source = byId.get(component.sourceId);
+        if (!source)
+            return [];
+        const certified = source.lifecycle === 'certified';
+        const tileId = uniqueTileId(reservedItems, component.id || `component-${index + 1}`);
+        componentTileIdById.set(component.id, tileId);
+        const tile = {
+            i: tileId,
+            x: (index % 2) * 6,
+            y: baseY + Math.floor(index / 2) * 4,
+            w: component.view === 'kpi' ? 3 : 6,
+            h: component.view === 'kpi' ? 2 : 4,
+            sourceId: source.sourceId,
+            sourceRevision: source.sourceRevision,
+            block: { ref: source.executionRef },
+            viz: { type: component.view },
+            title: component.title,
+            sourceClass: certified ? 'certified_block' : 'exploratory_analysis',
+            filterBindings: source.capabilities.filters.map((filter) => ({
+                filter,
+                binding: filter,
+                mode: 'predicate',
+                capability: 'preflight_required',
+            })),
+            review: { status: certified ? 'not_required' : 'required', sourceFingerprint: source.sourceRevision },
+            trustState: certified ? 'certified' : 'review_required',
+            reviewStatus: certified ? 'certified' : 'review_required',
+        };
+        reservedItems.push(tile);
+        return [tile];
+    });
+    const nextPage = {
+        ...page,
+        metadata: { ...page.metadata, description: brief.frame.decision || brief.frame.goal },
+        layout: {
+            ...page.layout,
+            items: [...structuralItems, ...plannedItems],
+            responsive: responsiveLayoutsForDashboardItems([...structuralItems, ...plannedItems]),
+        },
+    };
+    const coverage = brief.requirements.map((requirement) => {
+        const components = brief.components.filter((component) => component.requirementIds.includes(requirement.id));
+        return {
+            requirementId: requirement.id,
+            status: components.length ? 'covered' : 'gap',
+            sourceIds: Array.from(new Set(components.map((component) => component.sourceId))),
+            componentIds: components.map((component) => componentTileIdById.get(component.id) ?? component.id),
+            reasons: components.length
+                ? ['Covered by a source-bound App component from the validated Build Brief.']
+                : ['No supplied source candidate covered this requirement.'],
+        };
+    });
+    const clarifications = brief.frame.clarificationQuestions ?? [];
+    const reviewTasks = plannedSources
+        .filter((source) => source.lifecycle !== 'certified')
+        .map((source) => ({
+        type: 'set_review_task',
+        task: {
+            id: `review-source-${createHash('sha256').update(source.sourceId).digest('hex').slice(0, 12)}`,
+            message: `${source.title} is ${source.lifecycle} and must be certified, replaced, or removed before Project publication.`,
+            status: 'open',
+            sourceId: source.sourceId,
+            pageId: page.id,
+        },
+    }));
+    const operations = [
+        {
+            type: 'set_frame',
+            frame: brief.frame,
+        },
+        {
+            type: 'set_requirements',
+            requirements: brief.requirements,
+            coverage,
+        },
+        { type: 'upsert_page', page: nextPage },
+        ...sourceOperations,
+        ...reviewTasks,
+    ];
+    return {
+        id: `proposal_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        draftId: draft.id,
+        baseRevision: draft.revision,
+        baseProposalHash: draft.proposalHash,
+        operations,
+        defaultSelectedSourceIds: plannedSources
+            .filter((source) => source.eligibility.localPreview)
+            .map((source) => source.sourceId),
+        clarifications,
+        candidateSourceIds: brief.candidateSourceIds,
+        warnings: brief.warnings,
+        summary: {
+            requirements: brief.requirements.length,
+            covered: coverage.filter((item) => item.status === 'covered').length,
+            gaps: coverage.filter((item) => item.status === 'gap').length,
+            certifiedSources: plannedSources.filter((source) => source.lifecycle === 'certified').length,
+            semanticSources: 0,
+        },
+    };
+}
+/**
+ * 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 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'));
+    if (!dashboardPath)
+        return;
+    const absolutePath = join(projectRoot, dashboardPath);
+    if (!existsSync(absolutePath))
+        return;
+    const doc = JSON.parse(readFileSync(absolutePath, 'utf-8'));
+    // 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')) {
+        doc.sections.push({
+            id: 'appendix',
+            title: 'AI-generated analysis — needs review',
+            kind: 'appendix',
+            order: doc.sections.length,
+        });
+    }
+    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"]',
             '',
@@ -1677,10 +2517,20 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
     if (selected.size === 0) {
         return { ok: false, error: 'Select at least one tile to create the app.', status: 400 };
     }
+    const plannedFilterIds = new Set([
+        ...(plan.globalFilters ?? []).map((filter) => filter.id),
+        ...plan.pages.flatMap((page) => (page.filters ?? []).map((filter) => filter.id)),
+    ]);
+    const selectedFilterIds = new Set((input.filterIds ?? Array.from(plannedFilterIds)).filter((filterId) => plannedFilterIds.has(filterId)));
     // Filter the plan's certified tiles down to the confirmed selection; structural
     // tiles (narrative, draft placeholders) stay — they document the story + gaps.
     const committedPlan = {
         ...plan,
+        globalFilters: (plan.globalFilters ?? []).filter((filter) => selectedFilterIds.has(filter.id)),
+        // `+ Add page` must not rewrite the App it is adding to (`UI-017`), but the
+        // fields were dropped with no error, so a name typed in that brief silently
+        // vanished. Adding a page keeps the App's own name; use `PATCH /api/apps/:id`
+        // to rename, and see `appliedNameWarnings` below for the reported diagnostic.
         ...(!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) => ({
@@ -1688,15 +2538,20 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
             ...(isExistingPageBuild && pageIndex === 0 && cleanString(input.pageTitle)
                 ? { title: cleanString(input.pageTitle).slice(0, 120) }
                 : {}),
+            filters: (page.filters ?? []).filter((filter) => selectedFilterIds.has(filter.id)),
             tiles: page.tiles
                 .filter((tile) => !['certified_block', 'semantic_query'].includes(tile.kind) || selected.has(tile.id))
                 .map((tile) => {
                 const override = tileOverrides[tile.id];
+                const filteredTile = {
+                    ...tile,
+                    filterBindings: (tile.filterBindings ?? []).filter((binding) => selectedFilterIds.has(binding.filter)),
+                };
                 if (!override)
-                    return tile;
+                    return filteredTile;
                 const viz = override.viz;
                 return {
-                    ...tile,
+                    ...filteredTile,
                     ...(override.title ? { title: override.title } : {}),
                     ...(viz ? { viz } : {}),
                     ...(viz && tile.display ? {
@@ -1721,7 +2576,15 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
     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) {
-        return { ok: false, error: 'Project sources changed after this proposal was created. Refresh and review the App proposal again.', status: 409 };
+        // This compares a whole-project index, so an unrelated block or model edit
+        // invalidates a pending proposal. Kept deliberately strict — the proposal's
+        // preflight receipts are bound to that snapshot — but the message now says
+        // what to do instead of only reporting a conflict.
+        return {
+            ok: false,
+            error: 'Project sources changed after this proposal was created, so its preflight evidence no longer applies. Re-run the build request to get a fresh proposal.',
+            status: 409,
+        };
     }
     const kg = new KGStore(defaultKgPath(projectRoot));
     try {
@@ -1747,7 +2610,10 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
         const stagedAppDir = isExistingPageBuild
             ? join(stagingRoot, 'candidate', 'apps', committedPlan.appId)
             : generatedAppDir;
-        const targetAppDir = join(projectRoot, 'apps', committedPlan.appId);
+        // Apps also resolve under `domains/**/apps/<id>`. Hardcoding the canonical
+        // root meant a domain-hosted App always failed the existence check below
+        // and could never have a page added.
+        const targetAppDir = existingApp?.appDir ?? join(projectRoot, 'apps', committedPlan.appId);
         const backupAppDir = join(projectRoot, '.dql', 'local', 'app-build-staging', `${session.id}-backup`);
         rmSync(stagingRoot, { recursive: true, force: true });
         try {
@@ -1841,6 +2707,15 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
             rmSync(stagingRoot, { recursive: true, force: true });
         }
         const attachWarnings = [];
+        // Adding a page deliberately cannot rename or re-audience the App it joins.
+        // Say so instead of discarding the input silently — this array existed and
+        // was never written to, so the drop had no surface at all.
+        if (isExistingPageBuild && cleanString(input.appName)) {
+            attachWarnings.push('The App name was not changed: adding a page cannot rename the App. Rename it from the App header.');
+        }
+        if (isExistingPageBuild && cleanString(input.audience)) {
+            attachWarnings.push('The audience was not changed: adding a page keeps the App\'s existing audience.');
+        }
         await ensureMetadataCatalogFresh(projectRoot, { force: true });
         const app = collectAppsList(projectRoot).find((entry) => entry.id === committedPlan.appId) ?? null;
         const next = {
@@ -1858,6 +2733,7 @@ export async function commitAppAiBuild(projectRoot, sessionId, input = {}, hooks
                     ? { pageTitle: committedPlan.pages[0]?.title }
                     : { appName: committedPlan.name }),
                 audience: committedPlan.audience,
+                filterIds: Array.from(selectedFilterIds),
                 tileOverrides,
             },
             warnings: [...session.warnings, ...attachWarnings],
@@ -1920,7 +2796,7 @@ 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, {
+    const appContext = buildAppContextEnvelope(ctx.projectRoot, loaded.app, loaded.appDir, {
         dashboardId,
         tileId: cleanString(input.tileId) || undefined,
         blockId,
@@ -2170,17 +3046,80 @@ function questionIsAboutFocusedTile(question) {
     return true;
 }
 /** Map a governed AgentAnswer into the App Copilot's response shape. */
+/** Overlap needed before a draft is offered as covering the question. */
+const APP_DRAFT_MATCH_MIN_OVERLAP = 2;
+const APP_DRAFT_STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'for', 'with', 'what', 'which', 'who', 'how', 'why', 'is', 'are',
+    'do', 'does', 'can', 'you', 'me', 'my', 'our', 'this', 'that', 'show', 'give', 'get', 'by', 'of',
+    'in', 'on', 'to', 'from', 'all', 'complete', 'view',
+]);
+function appDraftTokens(value) {
+    return new Set(value.toLowerCase().split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 2 && !APP_DRAFT_STOPWORDS.has(word)));
+}
+/**
+ * The app's own draft that best covers a question the governed loop could not answer.
+ *
+ * Drafts are review-required exploratory analyses saved in the app. They are not
+ * indexed into the manifest, so retrieval cannot find them — but when the loop
+ * has just refused for want of a certified path, the app frequently already
+ * contains a draft that does exactly the thing. Offering it is strictly better
+ * than explaining the gap and stopping, and it never launders trust: the answer
+ * stays review-required and says the source is an unreviewed draft.
+ */
+export function matchAppDraftForQuestion(drafts, question) {
+    const asked = appDraftTokens(question);
+    if (asked.size === 0)
+        return undefined;
+    let best;
+    for (const draft of drafts ?? []) {
+        const candidate = appDraftTokens([draft.name, draft.question ?? '', draft.description ?? ''].join(' '));
+        let score = 0;
+        for (const token of asked)
+            if (candidate.has(token))
+                score += 1;
+        if (score >= APP_DRAFT_MATCH_MIN_OVERLAP && (!best || score > best.score))
+            best = { draft, score };
+    }
+    return best?.draft;
+}
 function mapGovernedToAppAsk(governed, input) {
     const isCertified = governed.certification === 'certified' || governed.kind === 'certified';
     const noAnswer = governed.kind === 'no_answer';
-    const answer = cleanString(governed.answer) || cleanString(governed.text) || 'No governed answer was available for this question.';
+    const governedText = cleanString(governed.answer) || cleanString(governed.text) || 'No governed answer was available for this question.';
+    // The loop just declined for want of certified evidence. Before returning only
+    // the gap, check whether this app already saved a draft that covers it.
+    const draft = noAnswer ? matchAppDraftForQuestion(input.appContext?.drafts ?? [], input.question) : undefined;
+    // App drafts are often generated FROM a refusal like this one, so their
+    // description can be the same paragraph the loop just returned. Only add it
+    // when it actually says something new.
+    const normalize = (value) => value.toLowerCase().replace(/\s+/g, ' ').trim();
+    const draftAdds = draft?.description && !normalize(governedText).includes(normalize(draft.description).slice(0, 80))
+        ? draft.description
+        : '';
+    const answer = draft
+        ? [
+            governedText,
+            '',
+            `This app already has a saved draft for it: "${draft.name}" (${draft.status}).`,
+            draftAdds,
+            'It is an unreviewed draft, not a certified answer — open it under Drafts, check the join, grain, and filters, then certify it to make it governed.',
+        ].filter(Boolean).join('\n')
+        : governedText;
     const route = noAnswer ? 'metadata_answer' : isCertified ? 'certified_answer' : 'generated_answer';
-    const trustState = noAnswer ? 'draft_ready' : isCertified ? 'certified' : 'review_required';
+    // Offering a draft is actionable but unreviewed, so it is review_required
+    // rather than the bare draft_ready used when there is nothing to offer.
+    const trustState = draft ? 'review_required' : noAnswer ? 'draft_ready' : isCertified ? 'certified' : 'review_required';
     const govCitations = Array.isArray(governed.citations)
         ? governed.citations.map((c) => ({ kind: String(c.kind ?? 'source'), name: String(c.name ?? '') })).filter((c) => c.name)
         : [];
     const seen = new Set();
-    const citations = [...input.citations, ...govCitations].filter((c) => {
+    const citations = [
+        ...input.citations,
+        ...govCitations,
+        // Cite the draft so the user can open the exact file being offered.
+        ...(draft ? [{ kind: 'draft', name: draft.name, path: draft.path }] : []),
+    ].filter((c) => {
         const key = `${c.kind}:${c.name}`;
         if (seen.has(key))
             return false;
@@ -2194,9 +3133,11 @@ function mapGovernedToAppAsk(governed, input) {
         trustState,
         reviewStatus: trustState,
         citations,
-        followUps: noAnswer
-            ? ['Name the metric and grain', 'Pick a certified tile', 'Start driver analysis']
-            : ['Investigate drivers', 'Break this down further', 'Create a draft DQL block'],
+        followUps: draft
+            ? [`Open the "${draft.name}" draft`, 'Review its join and grain', 'Certify it to make it governed']
+            : noAnswer
+                ? ['Name the metric and grain', 'Pick a certified tile', 'Start driver analysis']
+                : ['Investigate drivers', 'Break this down further', 'Create a draft DQL block'],
         decision: buildAppAskDecision(route, { question: input.question, blockId: input.blockId, appName: input.appName }),
     };
 }
@@ -2386,6 +3327,75 @@ export function recommendDashboardTile(projectRoot, appId, dashboardId, input) {
         warnings: recommendation.warnings,
     };
 }
+/**
+ * Rename an App, and optionally a page inside it.
+ *
+ * `dql.app.json` previously had exactly two writers — create and publish — so
+ * an App could never be renamed after it was built. Only the display `name`
+ * changes here: the App **id** is also its folder name and is referenced by
+ * notebooks, product context, and deep links, so renaming must not move it.
+ *
+ * The write is staged and swapped like the publish path, and guarded by the
+ * caller-supplied fingerprint so a concurrent edit cannot be clobbered.
+ */
+export function renameApp(projectRoot, appId, input) {
+    const loaded = loadAppById(projectRoot, appId);
+    if (!loaded)
+        return { ok: false, error: `App "${appId}" not found`, code: 'APP_NOT_FOUND' };
+    if (input.expectedFingerprint && fingerprintAppDirectory(loaded.appDir) !== input.expectedFingerprint) {
+        return { ok: false, error: 'This App changed since it was loaded. Refresh and rename again.', code: 'APP_CHANGED' };
+    }
+    const name = cleanString(input.name);
+    const pageTitle = cleanString(input.pageTitle);
+    if (!name && !pageTitle)
+        return { ok: false, error: 'Provide a name or a pageTitle.', code: 'INVALID_REQUEST' };
+    const appPath = join(loaded.appDir, 'dql.app.json');
+    const parsedApp = parseAppDocument(JSON.stringify({ ...loaded.app, ...(name ? { name } : {}) }), appPath);
+    if (!parsedApp.document)
+        return { ok: false, error: parsedApp.errors.map((err) => err.message).join('; ') };
+    const renamedDashboards = [];
+    if (pageTitle) {
+        const homepage = loaded.app.homepage;
+        const dashboardId = cleanString(input.dashboardId)
+            || (homepage?.type === 'dashboard' ? homepage.id : undefined);
+        const source = findDashboardsForApp(loaded.appDir)
+            .map((path) => ({ path, document: loadDashboardDocument(path).document }))
+            .find((item) => item.document && (!dashboardId || item.document.id === dashboardId));
+        if (!source?.document)
+            return { ok: false, error: `Dashboard "${dashboardId ?? ''}" not found in app "${appId}"`, code: 'DASHBOARD_NOT_FOUND' };
+        const next = { ...source.document, metadata: { ...source.document.metadata, title: pageTitle } };
+        const parsed = parseDashboardDocument(JSON.stringify(next), source.path);
+        if (!parsed.document)
+            return { ok: false, error: parsed.errors.map((err) => err.message).join('; ') };
+        renamedDashboards.push({ sourcePath: source.path, document: parsed.document });
+    }
+    const stagingBase = join(projectRoot, '.dql', 'local', 'app-rename-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 renamedDashboards) {
+        writeFileSync(join(stagedAppDir, relative(loaded.appDir, dashboard.sourcePath)), 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: [relative(projectRoot, appPath), ...renamedDashboards.map((item) => relative(projectRoot, item.sourcePath))],
+    };
+}
 export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
     const loaded = loadAppById(projectRoot, appId);
     if (!loaded)
@@ -2393,7 +3403,7 @@ export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
     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));
+    const readiness = appPublicationReadiness(projectRoot, dashboardSources.map((item) => item.document));
     if (!readiness.ready) {
         return {
             ok: false,
@@ -2456,101 +3466,1449 @@ export function promoteAppForStakeholders(projectRoot, appId, input = {}) {
         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 });
+        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;
+    }
+    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(projectRoot, dashboards, options = {}) {
+    const blockers = [];
+    let governedTiles = 0;
+    const blocks = collectBlockCandidates(projectRoot, { preserveDuplicates: true });
+    for (const dashboard of dashboards) {
+        for (const item of dashboard.layout.items) {
+            if (item.block) {
+                governedTiles += 1;
+                const blockRef = item.block;
+                const boundRevision = item.sourceRevision ?? item.review?.sourceFingerprint;
+                const block = blocks.find((candidate) => ('blockId' in blockRef
+                    ? candidate.id === blockRef.blockId || candidate.name === blockRef.blockId
+                    : candidate.path === blockRef.ref));
+                if (!block || block.status !== 'certified') {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'block_not_certified',
+                        message: `${dashboard.id}/${item.i} no longer resolves to a certified block.`,
+                    });
+                }
+                else if (!boundRevision) {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'block_source_unversioned',
+                        message: `${dashboard.id}/${item.i} has no bound source revision; refresh the certified block before publication.`,
+                    });
+                }
+                else if (boundRevision !== block.fingerprint) {
+                    blockers.push({
+                        dashboardId: dashboard.id,
+                        tileId: item.i,
+                        code: 'block_source_changed',
+                        message: `${dashboard.id}/${item.i} changed after it was selected; review the current certified block before publication.`,
+                    });
+                }
+            }
+            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.`,
+                    });
+                }
+            }
+            if (dashboard.version === 2 && (item.block || item.semantic || item.draftAnalysis)) {
+                for (const filter of dashboard.filters ?? []) {
+                    if (filter.scope?.tileIds && !filter.scope.tileIds.includes(item.i))
+                        continue;
+                    const binding = item.filterBindings?.find((candidate) => candidate.filter === filter.id);
+                    // An explicit unsupported binding is a governed exclusion, not a
+                    // missing binding. Studio shows the reason on the affected tile and
+                    // the filter deliberately leaves that tile unchanged.
+                    if (binding?.capability === 'unsupported' && binding.unsupportedReason?.trim())
+                        continue;
+                    const settled = options.settledPageIds?.has(dashboard.id) ?? false;
+                    if (!binding || (!binding.binding && binding.mode !== 'parameter') || (binding.capability === 'preflight_required' && !settled)) {
+                        blockers.push({
+                            dashboardId: dashboard.id,
+                            tileId: item.i,
+                            code: 'filter_not_preflighted',
+                            message: `${dashboard.id}/${item.i} does not have a preflighted binding for filter ${filter.label ?? filter.id}.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return { ready: blockers.length === 0, governedTiles, blockers };
+}
+function appAiBuildSessionDir(projectRoot) {
+    return join(projectRoot, '.dql', 'local', 'app-ai-builds');
+}
+function appBuildDraftDir(projectRoot) {
+    // Read-only migration location for AppBuildDraft v1 JSON files. New drafts
+    // are persisted transactionally in .dql/local/apps.sqlite.
+    return join(projectRoot, '.dql', 'local', 'app-builds');
+}
+function appBuildProposalDir(projectRoot, draftId) {
+    return join(appBuildDraftDir(projectRoot), draftId, 'proposals');
+}
+function writeAppBuildDraftAiProposal(projectRoot, proposal) {
+    if (!/^[a-z0-9_:-]+$/i.test(proposal.draftId) || !/^[a-z0-9_:-]+$/i.test(proposal.id)) {
+        throw new Error('APP_BUILD_PROPOSAL_INVALID: proposal identity is invalid.');
+    }
+    const dir = appBuildProposalDir(projectRoot, proposal.draftId);
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${proposal.id}.json`);
+    const candidate = `${path}.candidate`;
+    writeFileSync(candidate, `${JSON.stringify(proposal, null, 2)}\n`, 'utf8');
+    renameSync(candidate, path);
+}
+function loadAppBuildDraftAiProposal(projectRoot, draftId, proposalId) {
+    if (!/^[a-z0-9_:-]+$/i.test(draftId) || !/^[a-z0-9_:-]+$/i.test(proposalId))
+        return null;
+    const path = join(appBuildProposalDir(projectRoot, draftId), `${proposalId}.json`);
+    if (!existsSync(path))
+        return null;
+    try {
+        const proposal = JSON.parse(readFileSync(path, 'utf8'));
+        return proposal.draftId === draftId && proposal.id === proposalId ? proposal : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function generateExplicitAppBuildGap(projectRoot, draft, previous, requirementId, generate) {
+    const requirementOperation = previous.operations.find((operation) => operation.type === 'set_requirements');
+    const requirement = requirementOperation?.type === 'set_requirements'
+        ? requirementOperation.requirements.find((candidate) => candidate.id === requirementId)
+        : undefined;
+    const coverage = requirementOperation?.type === 'set_requirements'
+        ? requirementOperation.coverage?.find((candidate) => candidate.requirementId === requirementId)
+        : undefined;
+    if (!requirement || coverage?.status === 'covered') {
+        throw new Error('APP_BUILD_GAP_NOT_FOUND: choose an uncovered App requirement.');
+    }
+    const answer = await generate(requirement.question);
+    const sql = cleanString(answer.sql);
+    if (!sql)
+        throw new Error('APP_BUILD_GAP_NO_QUERY: the provider did not return executable review DQL.');
+    if (sql.includes('"""'))
+        throw new Error('APP_BUILD_GAP_INVALID_QUERY: generated SQL contains an unsupported triple-quote delimiter.');
+    const proposalId = `proposal_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const key = slugify(requirement.id) || createHash('sha256').update(requirement.question).digest('hex').slice(0, 12);
+    const sourceRef = `proposals/${proposalId}/drafts/${key}.dql`;
+    const source = [
+        `block "app_${slugify(draft.appId)}_${key}" {`,
+        `  domain = "${escapeDqlString(draft.pages[0]?.metadata.domain ?? 'general')}"`,
+        '  type = "custom"',
+        '  status = "review"',
+        '  owner = "local-app-builder"',
+        `  description = "${escapeDqlString(answer.text?.slice(0, 240) || requirement.question)}"`,
+        `  llmContext = "${escapeDqlString(`Explicitly generated App gap: ${requirement.question}`)}"`,
+        '  caveats = ["AI-generated App gap. Validate joins, grain, filters, and interpretation before promotion."]',
+        '  tags = ["app-scoped", "ai-generated", "needs-review"]',
+        '',
+        '  query = """',
+        sql,
+        '  """',
+        '',
+        '  visualization {',
+        `    chart = "${escapeDqlString(normalizeGeneratedViz(answer.suggestedViz))}"`,
+        '  }',
+        '}',
+        '',
+    ].join('\n');
+    const fingerprint = `sha256:${createHash('sha256').update(source).digest('hex')}`;
+    const absolute = join(projectRoot, '.dql', 'local', 'app-builds', draft.id, sourceRef);
+    mkdirSync(dirname(absolute), { recursive: true });
+    writeFileSync(absolute, source, 'utf8');
+    const sourceId = `review-dql:gap:${createHash('sha256').update(`${proposalId}:${requirement.id}`).digest('hex').slice(0, 16)}`;
+    const pageOperation = previous.operations.find((operation) => operation.type === 'upsert_page');
+    if (!pageOperation || pageOperation.type !== 'upsert_page')
+        throw new Error('APP_BUILD_PAGE_REQUIRED: the proposal has no App page.');
+    const tileId = uniqueTileId(pageOperation.page.layout.items, `gap-${requirement.id}`);
+    const y = pageOperation.page.layout.items.reduce((max, tile) => Math.max(max, tile.y + tile.h), 0);
+    const tile = {
+        i: tileId,
+        x: 0,
+        y,
+        w: 6,
+        h: 4,
+        sourceId,
+        sourceRevision: fingerprint,
+        draftAnalysis: { ref: sourceRef, artifactFingerprint: fingerprint },
+        viz: { type: normalizeGeneratedViz(answer.suggestedViz) },
+        title: titleForGapQuestion(requirement.question),
+        sourceClass: 'exploratory_analysis',
+        review: { status: 'required', sourceFingerprint: fingerprint },
+        trustState: 'review_required',
+        reviewStatus: 'review_required',
+    };
+    const operations = previous.operations.map((operation) => {
+        if (operation === pageOperation && operation.type === 'upsert_page') {
+            const items = [...operation.page.layout.items, tile];
+            return { type: 'upsert_page', page: { ...operation.page, layout: { ...operation.page.layout, items, responsive: responsiveLayoutsForDashboardItems(items) } } };
+        }
+        if (operation.type === 'set_requirements') {
+            return {
+                ...operation,
+                coverage: (operation.coverage ?? []).map((item) => item.requirementId === requirement.id
+                    ? { ...item, status: 'covered', sourceIds: [sourceId], componentIds: [tileId], reasons: ['Covered by explicitly generated review-required App DQL.'] }
+                    : item),
+            };
+        }
+        return operation;
+    });
+    operations.push({
+        type: 'upsert_source',
+        source: {
+            id: sourceId,
+            kind: 'review_dql',
+            sourceRef,
+            qualifiedIdentity: tile.title,
+            sourceRevision: fingerprint,
+            sourceFingerprint: fingerprint,
+            lifecycle: 'review',
+            capabilities: { measures: requirement.measures, dimensions: requirement.dimensions, outputs: [], filters: requirement.filters, allowedVisualizations: [tile.viz.type], parameters: [] },
+            trustState: 'review_required',
+            reviewStatus: 'required',
+        },
+    });
+    operations.push({
+        type: 'set_review_task',
+        task: {
+            id: `review-gap-${key}`,
+            message: `Validate the joins, grain, filters, and business interpretation for ${tile.title}.`,
+            status: 'open',
+            sourceId,
+            pageId: pageOperation.page.id,
+            tileId,
+        },
+    });
+    return {
+        ...previous,
+        id: proposalId,
+        operations,
+        warnings: Array.from(new Set([...(previous.warnings ?? []), 'Generated gap remains review-required and local-only.'])),
+        summary: {
+            ...previous.summary,
+            covered: previous.summary.covered + 1,
+            gaps: Math.max(0, previous.summary.gaps - 1),
+        },
+    };
+}
+async function composeStoredAppBuildDraft(projectRoot, current, request) {
+    if (request.mode === 'ai') {
+        const proposal = loadAppBuildDraftAiProposal(projectRoot, current.id, cleanString(request.proposalId));
+        if (!proposal)
+            throw new Error('APP_BUILD_PROPOSAL_NOT_FOUND: ask AI to rebuild the proposal.');
+        if (proposal.baseRevision !== current.revision || proposal.baseProposalHash !== current.proposalHash) {
+            throw new Error('APP_BUILD_PROPOSAL_CONFLICT: the proposal is based on an older draft revision.');
+        }
+        const selected = new Set(unique((request.selectedSourceIds ?? []).map(cleanString).filter(Boolean)));
+        const available = new Map(proposal.operations.flatMap((operation) => (operation.type === 'upsert_source' ? [[operation.source.id, operation.source]] : [])));
+        const missing = Array.from(selected).filter((sourceId) => !available.has(sourceId));
+        if (missing.length)
+            throw new Error(`APP_BUILD_SOURCE_NOT_IN_PROPOSAL: ${missing.join(', ')}`);
+        for (const sourceId of selected) {
+            const source = available.get(sourceId);
+            if (current.sourcePolicy === 'governed_only' && source.trustState !== 'certified') {
+                throw new Error(`APP_BUILD_REVIEW_POLICY_REQUIRED: enable review-required sources before adding ${source.qualifiedIdentity ?? source.sourceRef}.`);
+            }
+        }
+        const operations = operationsForSelectedAppBuildSources(proposal.operations, selected);
+        const next = applyAppBuildDraftOperations(current, current.revision, operations);
+        writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: current.revision, operations });
+        const pages = operations.flatMap((operation) => operation.type === 'upsert_page' ? [operation.page] : []);
+        return {
+            draft: next,
+            pageIds: pages.map((page) => page.id),
+            tileIds: pages.flatMap((page) => page.layout.items.filter((item) => item.sourceId && selected.has(item.sourceId)).map((item) => item.i)),
+        };
+    }
+    const selections = request.selections ?? [];
+    if (selections.length === 0)
+        throw new Error('APP_BUILD_SOURCE_REQUIRED: choose at least one source.');
+    if (selections.length > 100)
+        throw new Error('APP_BUILD_SOURCE_LIMIT: at most 100 components can be composed at once.');
+    const { ensureAgentProjectReady, resolveAppSourceCatalogRecords } = await import('@duckcodeailabs/dql-agent');
+    await ensureAgentProjectReady(projectRoot);
+    const resolved = resolveAppSourceCatalogRecords(projectRoot, selections.map((selection) => selection.sourceId), current.sourcePolicy);
+    if (resolved.missingSourceIds.length) {
+        throw new Error(`APP_BUILD_SOURCE_DRIFT: these sources no longer resolve: ${resolved.missingSourceIds.join(', ')}`);
+    }
+    const byId = new Map(resolved.items.map((source) => [source.sourceId, source]));
+    const workingItems = new Map(current.pages.map((page) => [page.id, [...page.layout.items]]));
+    const operations = [];
+    const pageIds = new Set();
+    const tileIds = [];
+    const coverageAdditions = new Map();
+    for (const [index, selection] of selections.entries()) {
+        const source = byId.get(selection.sourceId);
+        if (!source)
+            throw new Error(`APP_BUILD_SOURCE_DRIFT: ${selection.sourceId} no longer resolves.`);
+        if (!source.eligibility.localPreview) {
+            throw new Error(`APP_BUILD_REVIEW_POLICY_REQUIRED: ${source.title} is ${source.lifecycle}; enable review-required sources to add it locally.`);
+        }
+        const page = current.pages.find((candidate) => candidate.id === cleanString(selection.pageId)) ?? current.pages[0];
+        if (!page)
+            throw new Error('APP_BUILD_PAGE_REQUIRED: add a page before adding a source.');
+        const pageItems = workingItems.get(page.id) ?? [...page.layout.items];
+        const tileId = uniqueTileId(pageItems, `${source.name}-${selection.view}`);
+        const y = pageItems.reduce((max, item) => Math.max(max, item.y + item.h), 0);
+        const certified = source.lifecycle === 'certified';
+        const view = selection.view === 'chart'
+            ? normalizeVizType(source.capabilities.chartType ?? source.capabilities.allowedVisualizations?.[0] ?? 'bar')
+            : selection.view === 'kpi' ? 'kpi' : 'table';
+        const tile = {
+            i: tileId,
+            x: (index % 2) * 6,
+            y,
+            w: selection.view === 'kpi' ? 3 : 6,
+            h: selection.view === 'kpi' ? 2 : 4,
+            sourceId: source.sourceId,
+            sourceRevision: source.sourceRevision,
+            block: { ref: source.executionRef },
+            viz: { type: view },
+            title: source.title,
+            sourceClass: certified ? 'certified_block' : 'exploratory_analysis',
+            filterBindings: source.capabilities.filters.map((filter) => ({ filter, binding: filter, mode: 'predicate', capability: 'preflight_required' })),
+            review: { status: certified ? 'not_required' : 'required', sourceFingerprint: source.sourceRevision },
+            trustState: certified ? 'certified' : 'review_required',
+            reviewStatus: certified ? 'certified' : 'review_required',
+        };
+        pageItems.push(tile);
+        workingItems.set(page.id, pageItems);
+        operations.push({ type: 'upsert_source', source: appDraftSourceFromCatalog(source) });
+        operations.push({ type: 'add_tile', pageId: page.id, tile });
+        if (!certified) {
+            operations.push({
+                type: 'set_review_task',
+                task: {
+                    id: `review-source-${createHash('sha256').update(source.sourceId).digest('hex').slice(0, 12)}`,
+                    message: `${source.title} is ${source.lifecycle} and must be certified, replaced, or removed before Project publication.`,
+                    status: 'open',
+                    sourceId: source.sourceId,
+                    pageId: page.id,
+                    tileId,
+                },
+            });
+        }
+        pageIds.add(page.id);
+        tileIds.push(tileId);
+        for (const requirement of current.requirements) {
+            if (!catalogSourceSatisfiesRequirement(source, requirement))
+                continue;
+            const addition = coverageAdditions.get(requirement.id) ?? { sourceIds: [], componentIds: [] };
+            addition.sourceIds.push(source.sourceId);
+            addition.componentIds.push(tileId);
+            coverageAdditions.set(requirement.id, addition);
+        }
+    }
+    if (current.requirements.length > 0) {
+        const existingByRequirement = new Map(current.coverage.map((item) => [item.requirementId, item]));
+        operations.push({
+            type: 'set_coverage',
+            coverage: current.requirements.map((requirement) => {
+                const existing = existingByRequirement.get(requirement.id);
+                const addition = coverageAdditions.get(requirement.id);
+                const sourceIds = unique([...(existing?.sourceIds ?? []), ...(addition?.sourceIds ?? [])]);
+                const componentIds = unique([...(existing?.componentIds ?? []), ...(addition?.componentIds ?? [])]);
+                const newlyCovered = Boolean(addition?.sourceIds.length && addition.componentIds.length);
+                return {
+                    requirementId: requirement.id,
+                    status: newlyCovered ? 'covered' : existing?.status ?? 'gap',
+                    sourceIds,
+                    componentIds,
+                    reasons: newlyCovered
+                        ? unique([...(existing?.reasons ?? []), 'Covered by a server-resolved source added during manual composition.'])
+                        : existing?.reasons ?? ['No selected App source covers this requirement.'],
+                };
+            }),
+        });
+    }
+    const next = applyAppBuildDraftOperations(current, current.revision, operations);
+    writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: current.revision, operations });
+    return { draft: next, pageIds: Array.from(pageIds), tileIds };
+}
+function operationsForSelectedAppBuildSources(operations, selected) {
+    const keptComponentIds = new Set(operations.flatMap((operation) => {
+        if (operation.type === 'upsert_page') {
+            return operation.page.layout.items.filter((item) => !item.sourceId || selected.has(item.sourceId)).map((item) => item.i);
+        }
+        if (operation.type === 'add_tile' && (!operation.tile.sourceId || selected.has(operation.tile.sourceId)))
+            return [operation.tile.i];
+        return [];
+    }));
+    return operations.flatMap((operation) => {
+        if (operation.type === 'upsert_source')
+            return selected.has(operation.source.id) ? [operation] : [];
+        if (operation.type === 'set_review_task') {
+            return !operation.task.sourceId || selected.has(operation.task.sourceId) ? [operation] : [];
+        }
+        if (operation.type === 'upsert_page') {
+            const items = operation.page.layout.items.filter((item) => !item.sourceId || selected.has(item.sourceId));
+            return [{
+                    ...operation,
+                    page: {
+                        ...operation.page,
+                        layout: {
+                            ...operation.page.layout,
+                            items,
+                            responsive: responsiveLayoutsForDashboardItems(items),
+                        },
+                    },
+                }];
+        }
+        if (operation.type === 'set_requirements') {
+            const coverage = (operation.coverage ?? []).map((item) => {
+                const sourceIds = item.sourceIds.filter((sourceId) => selected.has(sourceId));
+                const componentIds = item.componentIds.filter((componentId) => keptComponentIds.has(componentId));
+                return {
+                    ...item,
+                    sourceIds,
+                    componentIds,
+                    status: sourceIds.length && componentIds.length ? item.status : 'gap',
+                };
+            });
+            return [{ ...operation, coverage }];
+        }
+        if (operation.type === 'set_coverage') {
+            return [{
+                    ...operation,
+                    coverage: operation.coverage.map((item) => {
+                        const sourceIds = item.sourceIds.filter((sourceId) => selected.has(sourceId));
+                        const componentIds = item.componentIds.filter((componentId) => keptComponentIds.has(componentId));
+                        return { ...item, sourceIds, componentIds, status: sourceIds.length && componentIds.length ? item.status : 'gap' };
+                    }),
+                }];
+        }
+        return [operation];
+    });
+}
+/**
+ * Rehydrate the canonical v3 source registry when a Git-owned App is opened in
+ * Studio. Published dashboard documents intentionally keep the immutable
+ * source binding on each tile; the mutable local draft must restore that
+ * registry before core aggregate validation runs. This is metadata-only and
+ * performs no request-time block scan. Current lifecycle/fingerprint checks
+ * remain the responsibility of preview and publication preflight.
+ */
+function rehydratePublishedAppSources(pages) {
+    const sources = new Map();
+    const reviewTasks = new Map();
+    let requiresReviewPolicy = false;
+    const normalizedPages = pages.map((page) => ({
+        ...page,
+        layout: {
+            ...page.layout,
+            items: page.layout.items.map((tile) => {
+                const hasDataSource = Boolean(tile.block || tile.semantic || tile.draftAnalysis || tile.aiPin);
+                if (!hasDataSource)
+                    return tile;
+                const blockRef = tile.block ? ('ref' in tile.block ? tile.block.ref : tile.block.blockId) : undefined;
+                const sourceRef = blockRef
+                    ?? tile.draftAnalysis?.ref
+                    ?? tile.semantic?.id
+                    ?? tile.aiPin?.id
+                    ?? `${page.id}/${tile.i}`;
+                const sourceRevision = tile.sourceRevision
+                    ?? tile.review?.sourceFingerprint
+                    ?? tile.draftAnalysis?.artifactFingerprint
+                    ?? tile.semantic?.definitionFingerprint;
+                const sourceId = tile.sourceId
+                    ?? `published:${createHash('sha256').update(`${page.id}\0${tile.i}\0${sourceRef}`).digest('hex').slice(0, 20)}`;
+                const certified = Boolean(tile.block
+                    && sourceRevision
+                    && tile.trustState === 'certified'
+                    && tile.review?.status !== 'required');
+                const kind = tile.semantic
+                    ? 'governed_semantic'
+                    : tile.draftAnalysis
+                        ? 'review_dql'
+                        : tile.block
+                            ? 'block'
+                            : 'text';
+                const nextSource = {
+                    id: sourceId,
+                    kind,
+                    sourceRef,
+                    qualifiedIdentity: tile.title || sourceRef,
+                    ...(tile.block ? { sourcePath: sourceRef, executionRef: sourceRef } : {}),
+                    ...(sourceRevision ? { sourceRevision, sourceFingerprint: sourceRevision } : {}),
+                    lifecycle: certified ? 'certified' : tile.draftAnalysis ? 'review' : 'unknown',
+                    capabilities: {
+                        measures: [],
+                        dimensions: [],
+                        outputs: [],
+                        filters: Array.from(new Set((tile.filterBindings ?? [])
+                            .filter((binding) => binding.capability !== 'unsupported')
+                            .map((binding) => binding.filter))),
+                        allowedVisualizations: Array.from(new Set([
+                            tile.viz.type,
+                            ...(tile.display?.allowedVisualizations ?? []),
+                        ])),
+                        parameters: [],
+                    },
+                    trustState: certified ? 'certified' : 'review_required',
+                    reviewStatus: certified ? 'not_required' : 'required',
+                };
+                const previous = sources.get(sourceId);
+                if (!previous) {
+                    sources.set(sourceId, nextSource);
+                }
+                else if (previous.sourceRef !== nextSource.sourceRef
+                    || previous.sourceRevision !== nextSource.sourceRevision
+                    || previous.trustState !== nextSource.trustState) {
+                    requiresReviewPolicy = true;
+                    sources.set(sourceId, {
+                        ...previous,
+                        lifecycle: 'unknown',
+                        trustState: 'review_required',
+                        reviewStatus: 'required',
+                    });
+                    reviewTasks.set(`published-source-${sourceId}`, {
+                        id: `published-source-${createHash('sha256').update(sourceId).digest('hex').slice(0, 12)}`,
+                        message: `${tile.title || sourceRef} has conflicting published source bindings. Refresh or replace it before publication.`,
+                        status: 'open',
+                        sourceId,
+                        pageId: page.id,
+                        tileId: tile.i,
+                    });
+                }
+                if (!certified) {
+                    requiresReviewPolicy = true;
+                    reviewTasks.set(`published-source-${sourceId}`, {
+                        id: `published-source-${createHash('sha256').update(sourceId).digest('hex').slice(0, 12)}`,
+                        message: sourceRevision
+                            ? `${tile.title || sourceRef} must be refreshed against the current project source before publication.`
+                            : `${tile.title || sourceRef} has no published source revision. Replace or refresh it before publication.`,
+                        status: 'open',
+                        sourceId,
+                        pageId: page.id,
+                        tileId: tile.i,
+                    });
+                }
+                return tile.sourceId === sourceId ? tile : { ...tile, sourceId, ...(sourceRevision ? { sourceRevision } : {}) };
+            }),
+        },
+    }));
+    return {
+        pages: normalizedPages,
+        sources: Array.from(sources.values()),
+        reviewTasks: Array.from(reviewTasks.values()),
+        requiresReviewPolicy,
+    };
+}
+export function createStoredAppBuildDraft(projectRoot, input) {
+    const baseAppId = cleanString(input.baseAppId);
+    const base = baseAppId ? loadAppById(projectRoot, baseAppId) : null;
+    if (baseAppId && !base)
+        throw new Error(`App "${baseAppId}" not found.`);
+    const name = cleanString(input.name) || base?.app.name || cleanString(input.goal) || 'Untitled App';
+    const appId = base?.app.id || cleanString(input.appId) || suggestAppId(name);
+    const id = `build_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const pageId = 'overview';
+    const emptyItems = [];
+    const blankPage = {
+        version: 2,
+        id: pageId,
+        metadata: {
+            title: 'Overview',
+            description: cleanString(input.goal) || `Local draft canvas for ${name}`,
+            domain: cleanString(input.domain) || base?.app.domain || 'general',
+            audience: cleanString(input.audience) || base?.app.audience || 'stakeholders',
+            visibility: 'private',
+            lifecycle: 'draft',
+        },
+        layout: {
+            kind: 'grid', cols: 12, rowHeight: 80, items: emptyItems,
+            responsive: {
+                wide: { kind: 'grid', cols: 12, rowHeight: 80, items: emptyItems },
+                medium: { kind: 'grid', cols: 6, rowHeight: 80, items: emptyItems },
+                narrow: { kind: 'grid', cols: 1, rowHeight: 80, items: emptyItems },
+            },
+        },
+    };
+    const basePages = base
+        ? findDashboardsForApp(base.appDir)
+            .map((path) => loadDashboardDocument(path).document)
+            .filter((page) => Boolean(page))
+        : [];
+    const template = input.template ?? 'blank';
+    const published = rehydratePublishedAppSources(basePages);
+    const pages = published.pages.length ? published.pages : [applyAppStudioTemplate(blankPage, template, name)];
+    const draft = createAppBuildDraft({
+        id,
+        appId,
+        name,
+        ...(base ? { baseApp: { appId: base.app.id, fingerprint: fingerprintAppDirectory(base.appDir) } } : {}),
+        authoringMode: input.authoringMode === 'manual' ? 'manual' : 'ai',
+        template,
+        sourcePolicy: published.requiresReviewPolicy ? 'include_review_required' : input.sourcePolicy,
+        frame: {
+            goal: cleanString(input.goal) || `Create ${name}`,
+            audience: cleanString(input.audience) || base?.app.audience || 'stakeholders',
+            metrics: [], dimensions: [], filters: [], desiredOutput: 'One responsive analytical page',
+            // Clarifications are returned only when the App-specific planner finds a
+            // material ambiguity. A synthetic unanswered question here used to make
+            // every new AI draft enter a UI dead-end before planning even ran.
+            clarificationQuestions: [],
+        },
+        sources: published.sources,
+        pages,
+        reviewTasks: published.reviewTasks,
+    });
+    writeStoredAppBuildDraft(projectRoot, draft);
+    return draft;
+}
+/**
+ * Adds an Ask result to the same local AppBuildDraft used by manual and AI
+ * authoring. Certified answers retain their block identity. Exploratory DQL is
+ * materialized as an app-scoped local artifact and remains review-required;
+ * SQL is never embedded in the dashboard JSON or written to Project source.
+ */
+export function addAskResultToAppBuildDraft(projectRoot, draftId, input) {
+    const draft = loadStoredAppBuildDraft(projectRoot, draftId);
+    if (!draft)
+        throw new Error('App Build Draft not found.');
+    if (input.expectedRevision !== draft.revision || input.expectedProposalHash !== draft.proposalHash) {
+        throw new Error('APP_BUILD_REVISION_CONFLICT: refresh the local draft before adding this Ask result.');
+    }
+    const page = draft.pages.find((candidate) => candidate.id === cleanString(input.pageId)) ?? draft.pages[0];
+    if (!page)
+        throw new Error('The local App draft needs a page before adding an Ask result.');
+    const question = cleanString(input.question).slice(0, 500);
+    const answer = cleanString(input.answer).slice(0, 40_000);
+    const title = (cleanString(input.title) || titleForGapQuestion(question || 'Ask result')).slice(0, 120);
+    const requestedBlockId = cleanString(input.certifiedBlockId);
+    const dqlSource = cleanString(input.dqlSource);
+    const sql = cleanString(input.sql);
+    if (dqlSource.length > 400_000 || sql.length > 200_000)
+        throw new Error('Ask result source exceeds the local App artifact limit.');
+    const sourceIdentity = requestedBlockId || dqlSource || sql || `${question}\n${answer}`;
+    if (!sourceIdentity)
+        throw new Error('The Ask result did not include reusable evidence.');
+    const identity = createHash('sha256').update(sourceIdentity).digest('hex').slice(0, 16);
+    const tileId = `ask-${identity}`;
+    if (draft.pages.some((candidate) => candidate.layout.items.some((tile) => tile.i === tileId))) {
+        return { ok: true, draft, pageId: page.id, tileId, deduped: true };
+    }
+    const nextY = page.layout.items.reduce((max, tile) => Math.max(max, tile.y + tile.h), 0);
+    const viz = normalizeGeneratedViz(input.visualization);
+    const operations = [];
+    let artifactPath;
+    let artifactWasCreated = false;
+    let tile;
+    if (requestedBlockId) {
+        const block = collectBlockCandidates(projectRoot).find((candidate) => candidate.status === 'certified'
+            && (candidate.id === requestedBlockId || candidate.name === requestedBlockId || candidate.path === requestedBlockId));
+        if (!block)
+            throw new Error(`Certified block "${requestedBlockId}" is no longer available.`);
+        const sourceId = `block:${block.id}`;
+        operations.push({
+            type: 'upsert_source',
+            source: {
+                id: sourceId,
+                kind: 'certified_block',
+                sourceRef: block.id,
+                sourceFingerprint: block.fingerprint,
+                trustState: 'certified',
+                reviewStatus: 'not_required',
+            },
+        });
+        tile = {
+            i: tileId, x: 0, y: nextY, w: 6, h: 4,
+            block: { blockId: block.id },
+            viz: { type: viz === 'table' ? normalizeVizType(block.chartType) : viz },
+            title,
+            sourceClass: 'certified_block',
+            filterBindings: block.filterIds.map((filter) => ({ filter, binding: filter, mode: 'predicate', capability: 'preflight_required' })),
+            sourceEvidence: [{ source: block.id, reason: question ? `Ask answer for: ${question}` : 'Added from a certified Ask answer.', kind: 'certified_block', trustState: 'certified' }],
+            review: { status: 'not_required', sourceFingerprint: block.fingerprint },
+            trustState: 'certified',
+            reviewStatus: 'certified',
+        };
+    }
+    else if (dqlSource || sql) {
+        const sourceId = `review-dql:ask-${identity}`;
+        const sourceRef = `analysis/ask-${identity}.dql`;
+        const source = dqlSource || [
+            `block "ask_${identity}" {`,
+            `  domain = "${escapeDqlString(page.metadata.domain ?? 'general')}"`,
+            '  type = "custom"',
+            '  status = "review"',
+            '  owner = "local-ask"',
+            `  description = "${escapeDqlString(answer || question || title)}"`,
+            question ? `  llmContext = "${escapeDqlString(`Ask result: ${question}`)}"` : '',
+            '  caveats = ["Ask-generated local analysis. Validate joins, grain, filters, and interpretation before promotion."]',
+            '  tags = ["app-scoped", "ask-generated", "needs-review"]',
+            '',
+            '  query = """',
+            sql,
+            '  """',
+            '',
+            '  visualization {',
+            `    chart = "${escapeDqlString(normalizeGeneratedViz(input.visualization))}"`,
+            '  }',
+            '}',
+            '',
+        ].filter(Boolean).join('\n');
+        const fingerprint = `sha256:${createHash('sha256').update(source).digest('hex')}`;
+        artifactPath = join(projectRoot, '.dql', 'local', 'app-builds', draft.id, sourceRef);
+        operations.push(...(draft.sourcePolicy === 'include_review_required'
+            ? []
+            : [{ type: 'set_source_policy', sourcePolicy: 'include_review_required' }]), {
+            type: 'upsert_source',
+            source: {
+                id: sourceId,
+                kind: 'review_dql',
+                sourceRef,
+                qualifiedIdentity: title,
+                sourceFingerprint: fingerprint,
+                trustState: 'review_required',
+                reviewStatus: 'required',
+            },
+        }, {
+            type: 'set_review_task',
+            task: {
+                id: `review-ask-${identity}`,
+                message: `Validate the joins, grain, filters, and business interpretation for ${title}.`,
+                status: 'open',
+                sourceId,
+                pageId: page.id,
+                tileId,
+            },
+        });
+        tile = {
+            i: tileId, x: 0, y: nextY, w: 6, h: 4,
+            draftAnalysis: { ref: sourceRef, artifactFingerprint: fingerprint },
+            viz: { type: viz },
+            title,
+            sourceClass: 'exploratory_analysis',
+            sourceEvidence: [{ source: sourceRef, reason: question ? `Ask generated this private analysis for: ${question}` : 'Ask generated this private analysis.', kind: 'review_dql', trustState: 'review_required' }],
+            review: { status: 'required', sourceFingerprint: fingerprint },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+        };
+        if (!existsSync(artifactPath)) {
+            mkdirSync(dirname(artifactPath), { recursive: true });
+            writeFileSync(artifactPath, source, 'utf-8');
+            artifactWasCreated = true;
+        }
+    }
+    else {
+        const sourceId = `text:ask-${identity}`;
+        operations.push(...(draft.sourcePolicy === 'include_review_required'
+            ? []
+            : [{ type: 'set_source_policy', sourcePolicy: 'include_review_required' }]), { type: 'upsert_source', source: { id: sourceId, kind: 'text', sourceRef: `ask:${identity}`, trustState: 'review_required', reviewStatus: 'required' } }, { type: 'set_review_task', task: { id: `review-ask-${identity}`, message: `Review the Ask narrative ${title} before publication.`, status: 'open', sourceId, pageId: page.id, tileId } });
+        tile = {
+            i: tileId, x: 0, y: nextY, w: 12, h: 2,
+            text: { markdown: answer || question },
+            viz: { type: 'text' },
+            title,
+            sourceClass: 'narrative',
+            sourceEvidence: [{ source: `ask:${identity}`, reason: 'Saved from Ask as an editable review-required narrative.', kind: 'text', trustState: 'review_required' }],
+            review: { status: 'required' },
+            trustState: 'review_required',
+            reviewStatus: 'review_required',
+        };
+    }
+    operations.push({ type: 'add_tile', pageId: page.id, tile });
+    try {
+        const next = applyAppBuildDraftOperations(draft, draft.revision, operations);
+        writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: draft.revision, operations });
+        return { ok: true, draft: next, pageId: page.id, tileId, deduped: false };
+    }
+    catch (error) {
+        if (artifactWasCreated && artifactPath)
+            rmSync(artifactPath, { force: true });
+        throw error;
+    }
+}
+function applyAppStudioTemplate(page, template, appName) {
+    if (template === 'blank')
+        return page;
+    const intro = template === 'executive_brief'
+        ? `# ${appName}\n\nState the decision this brief supports, then add governed evidence below.`
+        : template === 'operational_dashboard'
+            ? `# ${appName}\n\nMonitor current performance, changes, and the details that require action.`
+            : `# ${appName}\n\nDocument the question, findings, caveats, and evidence for this investigation.`;
+    const items = [{
+            i: 'template-introduction', x: 0, y: 0, w: 12, h: 2,
+            title: template === 'investigation' ? 'Investigation question' : 'Executive context',
+            sectionId: 'exec_summary',
+            text: { markdown: intro },
+            viz: { type: 'text' },
+            sourceClass: 'narrative',
+            trustState: 'draft_ready',
+            reviewStatus: 'draft_ready',
+        }];
+    const sections = template === 'investigation'
+        ? [
+            { id: 'exec_summary', title: 'Question', kind: 'exec_summary', order: 0 },
+            { id: 'insight', title: 'Findings and comparisons', kind: 'insight', order: 1 },
+            { id: 'appendix', title: 'Caveats and evidence', kind: 'appendix', order: 2 },
+        ]
+        : [
+            { id: 'exec_summary', title: 'Executive summary', kind: 'exec_summary', order: 0 },
+            { id: 'kpi_band', title: 'Key metrics', kind: 'kpi_band', order: 1 },
+            { id: 'insight', title: template === 'executive_brief' ? 'Decision evidence' : 'Trends and drivers', kind: 'insight', order: 2 },
+            { id: 'appendix', title: 'Detail and evidence', kind: 'appendix', order: 3 },
+        ];
+    return {
+        ...page,
+        sections,
+        layout: {
+            ...page.layout,
+            items,
+            responsive: responsiveLayoutsForDashboardItems(items),
+        },
+    };
+}
+function loadStoredAppBuildDraft(projectRoot, id) {
+    const clean = cleanString(id);
+    if (!clean || !/^[a-z0-9_:-]+$/i.test(clean))
+        return null;
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        const stored = storage.getAppBuildDraft(clean);
+        if (stored) {
+            const migrated = migrateLegacyAppBuildDraft(projectRoot, stored);
+            if (migrated && stored.version !== migrated.version)
+                storage.saveAppBuildDraft(migrated);
+            return migrated;
+        }
+        const legacyPath = join(appBuildDraftDir(projectRoot), `${clean}.json`);
+        if (!existsSync(legacyPath))
+            return null;
+        const migrated = migrateLegacyAppBuildDraft(projectRoot, JSON.parse(readFileSync(legacyPath, 'utf-8')));
+        if (!migrated)
+            return null;
+        storage.saveAppBuildDraft(migrated);
+        return migrated;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        storage.close();
+    }
+}
+export function writeStoredAppBuildDraft(projectRoot, draft, input = {}) {
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        storage.saveAppBuildDraft(draft, input);
+    }
+    finally {
+        storage.close();
+    }
+}
+function migrateLegacyAppBuildDraft(projectRoot, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const legacy = value;
+    if (legacy.version === 3)
+        return legacy;
+    if (legacy.version === 2)
+        return migrateV2AppBuildDraft(projectRoot, legacy);
+    if (legacy.version !== 1 || typeof legacy.id !== 'string' || typeof legacy.appId !== 'string')
+        return null;
+    const frame = (legacy.frame && typeof legacy.frame === 'object' ? legacy.frame : {});
+    const clarificationQuestions = Array.isArray(frame.clarificationQuestions)
+        ? frame.clarificationQuestions.flatMap((raw) => {
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                return [];
+            const question = raw;
+            if (typeof question.id !== 'string' || typeof question.question !== 'string')
+                return [];
+            const choices = Array.isArray(question.choices)
+                ? question.choices.map((choice, index) => typeof choice === 'string'
+                    ? { id: slugify(choice) || `choice-${index + 1}`, label: choice }
+                    : choice).filter((choice) => Boolean(choice && typeof choice === 'object' && 'id' in choice && 'label' in choice))
+                : [];
+            return [{ id: question.id, question: question.question, choices, required: question.required !== false }];
+        })
+        : [];
+    const migrated = createAppBuildDraft({
+        id: legacy.id,
+        appId: legacy.appId,
+        name: typeof legacy.name === 'string' ? legacy.name : (typeof frame.goal === 'string' ? frame.goal : legacy.appId),
+        authoringMode: legacy.authoringMode === 'manual' ? 'manual' : 'ai',
+        sourcePolicy: legacy.sourcePolicy === 'include_review_required' ? 'include_review_required' : 'governed_only',
+        frame: {
+            goal: typeof frame.goal === 'string' ? frame.goal : `Create ${legacy.appId}`,
+            decision: typeof frame.decision === 'string' ? frame.decision : undefined,
+            audience: typeof frame.audience === 'string' ? frame.audience : undefined,
+            metrics: Array.isArray(frame.metrics) ? frame.metrics.filter((item) => typeof item === 'string') : [],
+            dimensions: Array.isArray(frame.dimensions) ? frame.dimensions.filter((item) => typeof item === 'string') : [],
+            filters: Array.isArray(frame.filters) ? frame.filters.filter((item) => typeof item === 'string') : [],
+            desiredOutput: typeof frame.desiredOutput === 'string' ? frame.desiredOutput : undefined,
+            clarificationQuestions,
+        },
+        sources: Array.isArray(legacy.sources) ? legacy.sources : [],
+        pages: Array.isArray(legacy.pages) ? legacy.pages : [],
+        reviewTasks: Array.isArray(legacy.reviewTasks) ? legacy.reviewTasks : [],
+        now: typeof legacy.createdAt === 'string' ? legacy.createdAt : undefined,
+    });
+    return {
+        ...migrated,
+        revision: typeof legacy.revision === 'number' ? legacy.revision : migrated.revision,
+        updatedAt: typeof legacy.updatedAt === 'string' ? legacy.updatedAt : migrated.updatedAt,
+    };
+}
+function migrateV2AppBuildDraft(projectRoot, legacy) {
+    if (typeof legacy.id !== 'string' || typeof legacy.appId !== 'string')
+        return null;
+    const declarations = collectBlockCandidates(projectRoot, { preserveDuplicates: true });
+    const oldSources = Array.isArray(legacy.sources) ? legacy.sources : [];
+    const idMap = new Map();
+    const revisionById = new Map();
+    const pathById = new Map();
+    const migrationTasks = [];
+    const sources = oldSources.flatMap((raw, index) => {
+        const oldId = cleanString(raw.id) || `legacy-source-${index + 1}`;
+        const kind = cleanString(raw.kind);
+        if (!['block', 'certified_block', 'review_block'].includes(kind)) {
+            idMap.set(oldId, oldId);
+            return [{ ...raw, id: oldId }];
+        }
+        const sourceRef = cleanString(raw.sourceRef);
+        const fingerprint = cleanString(raw.sourceFingerprint);
+        const matches = declarations.filter((candidate) => (candidate.path === sourceRef
+            || candidate.id === sourceRef
+            || candidate.name === sourceRef
+            || candidate.path.endsWith(`/${sourceRef}`)) && (!fingerprint || candidate.fingerprint === fingerprint));
+        if (matches.length === 1) {
+            const candidate = matches[0];
+            const id = canonicalAppBlockSourceId(candidate);
+            idMap.set(oldId, id);
+            revisionById.set(id, candidate.fingerprint);
+            pathById.set(id, candidate.path);
+            const certified = candidate.status === 'certified';
+            return [{
+                    id,
+                    kind: 'block',
+                    sourceRef: candidate.path,
+                    qualifiedIdentity: `${candidate.domain || 'global'}::block::${candidate.name}`,
+                    sourcePath: candidate.path,
+                    executionRef: candidate.path,
+                    sourceRevision: candidate.fingerprint,
+                    sourceFingerprint: candidate.fingerprint,
+                    lifecycle: certified ? 'certified' : candidate.status === 'review' ? 'review' : 'draft',
+                    capabilities: {
+                        measures: [],
+                        dimensions: candidate.dimensionIds,
+                        outputs: [],
+                        filters: candidate.filterIds,
+                        chartType: candidate.chartType,
+                        allowedVisualizations: candidate.chartType ? [candidate.chartType] : [],
+                        parameters: [],
+                    },
+                    trustState: certified ? 'certified' : 'review_required',
+                    reviewStatus: certified ? 'not_required' : 'required',
+                }];
+        }
+        idMap.set(oldId, oldId);
+        migrationTasks.push({
+            id: `legacy-source-${createHash('sha256').update(oldId).digest('hex').slice(0, 12)}`,
+            message: matches.length > 1
+                ? `Legacy source ${sourceRef || oldId} is ambiguous. Select the exact path and revision before previewing or publishing.`
+                : `Legacy source ${sourceRef || oldId} no longer resolves. Replace or remove it before previewing or publishing.`,
+            status: 'open',
+            sourceId: oldId,
+        });
+        return [{
+                id: oldId,
+                kind: 'block',
+                sourceRef: sourceRef || oldId,
+                qualifiedIdentity: cleanString(raw.qualifiedIdentity) || sourceRef || oldId,
+                sourceRevision: fingerprint || undefined,
+                sourceFingerprint: fingerprint || undefined,
+                lifecycle: 'unknown',
+                capabilities: { measures: [], dimensions: [], outputs: [], filters: [], allowedVisualizations: [], parameters: [] },
+                trustState: 'review_required',
+                reviewStatus: 'required',
+            }];
+    });
+    const pages = (Array.isArray(legacy.pages) ? legacy.pages : []).map((page) => ({
+        ...page,
+        layout: {
+            ...page.layout,
+            items: page.layout.items.map((item) => {
+                if (item.sourceId)
+                    return item;
+                const blockRef = item.block
+                    ? ('ref' in item.block ? item.block.ref : item.block.blockId)
+                    : undefined;
+                if (!blockRef)
+                    return item;
+                const oldSource = oldSources.find((source) => {
+                    const ref = cleanString(source.sourceRef);
+                    return ref === blockRef || cleanString(source.id) === `block:${blockRef}` || cleanString(source.id) === `review-block:${blockRef}`;
+                });
+                const sourceId = oldSource ? idMap.get(cleanString(oldSource.id)) : undefined;
+                if (!sourceId)
+                    return item;
+                return {
+                    ...item,
+                    sourceId,
+                    sourceRevision: revisionById.get(sourceId) ?? (cleanString(oldSource?.sourceFingerprint) || undefined),
+                    ...(pathById.get(sourceId) ? { block: { ref: pathById.get(sourceId) } } : {}),
+                };
+            }),
+        },
+    }));
+    const coverage = (Array.isArray(legacy.coverage) ? legacy.coverage : []).map((item) => ({
+        ...item,
+        sourceIds: item.sourceIds.map((id) => idMap.get(id) ?? id),
+    }));
+    const migratedWithoutHash = {
+        ...legacy,
+        version: 3,
+        sources,
+        pages,
+        coverage,
+        reviewTasks: [
+            ...(Array.isArray(legacy.reviewTasks) ? legacy.reviewTasks : []),
+            ...migrationTasks,
+        ],
+    };
+    return {
+        ...migratedWithoutHash,
+        proposalHash: appBuildDraftHash({ ...migratedWithoutHash, proposalHash: undefined }),
+    };
+}
+export function deleteStoredAppBuildDraft(projectRoot, draft) {
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    let deleted;
+    try {
+        deleted = storage.deleteAppBuildDraft(draft.id);
+    }
+    finally {
+        storage.close();
+    }
+    if (!deleted)
+        throw new Error(`App Build Draft not found: ${draft.id}`);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const recoveryId = `draft-${stamp}-${draft.id}`;
+    const recoveryDir = join(projectRoot, '.dql', 'local', 'trash', 'app-drafts', recoveryId);
+    const localArtifactsDir = join(projectRoot, '.dql', 'local', 'app-builds', draft.id);
+    const recoveryArtifactsDir = join(recoveryDir, 'artifacts');
+    let artifactsMoved = false;
+    try {
+        mkdirSync(recoveryDir, { recursive: true });
+        if (existsSync(localArtifactsDir)) {
+            renameSync(localArtifactsDir, recoveryArtifactsDir);
+            artifactsMoved = true;
+        }
+        writeFileSync(join(recoveryDir, 'recovery.json'), JSON.stringify({
+            version: 1,
+            kind: 'app_build_draft',
+            recoveryId,
+            deletedAt: new Date().toISOString(),
+            draft: deleted.draft,
+            operations: deleted.operations,
+        }, null, 2) + '\n', 'utf-8');
+    }
+    catch (error) {
+        if (artifactsMoved && existsSync(recoveryArtifactsDir)) {
+            mkdirSync(dirname(localArtifactsDir), { recursive: true });
+            renameSync(recoveryArtifactsDir, localArtifactsDir);
+        }
+        const restore = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            restore.restoreAppBuildDraft(deleted.draft, deleted.operations);
+        }
+        finally {
+            restore.close();
+        }
+        rmSync(recoveryDir, { recursive: true, force: true });
+        throw error;
+    }
+    return { ok: true, id: draft.id, recoveryId, recoverableUntilRestart: false };
+}
+function restoreStoredAppBuildDraft(projectRoot, recoveryId) {
+    const recoveryDir = join(projectRoot, '.dql', 'local', 'trash', 'app-drafts', recoveryId);
+    const recoveryPath = join(recoveryDir, 'recovery.json');
+    if (!existsSync(recoveryPath))
+        return { ok: false, status: 404, error: 'App recovery bundle not found.' };
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(recoveryPath, 'utf-8'));
+    }
+    catch {
+        return { ok: false, status: 400, error: 'App draft recovery bundle is invalid.' };
+    }
+    if (payload.kind !== 'app_build_draft' || !payload.draft)
+        return { ok: false, status: 400, error: 'App draft recovery bundle is invalid.' };
+    const recoveredArtifactsDir = join(recoveryDir, 'artifacts');
+    const localArtifactsDir = join(projectRoot, '.dql', 'local', 'app-builds', payload.draft.id);
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    let artifactsRestored = false;
+    try {
+        if (storage.getAppBuildDraft(payload.draft.id))
+            return { ok: false, status: 409, error: `App Build Draft already exists: ${payload.draft.id}` };
+        if (existsSync(localArtifactsDir))
+            return { ok: false, status: 409, error: `App Build Draft artifacts already exist: ${payload.draft.id}` };
+        if (existsSync(recoveredArtifactsDir)) {
+            mkdirSync(dirname(localArtifactsDir), { recursive: true });
+            renameSync(recoveredArtifactsDir, localArtifactsDir);
+            artifactsRestored = true;
+        }
+        storage.restoreAppBuildDraft(payload.draft, payload.operations ?? []);
     }
     catch (error) {
-        if (existsSync(backupAppDir) && !existsSync(loaded.appDir))
-            renameSync(backupAppDir, loaded.appDir);
+        if (artifactsRestored && existsSync(localArtifactsDir))
+            renameSync(localArtifactsDir, recoveredArtifactsDir);
         throw error;
     }
-    const paths = [relative(projectRoot, appPath), ...dashboards.map((dashboard) => relative(projectRoot, dashboard.sourcePath))];
-    return { ok: true, app: parsedApp.document, paths, removedLocalTiles, readiness };
+    finally {
+        storage.close();
+    }
+    rmSync(recoveryDir, { recursive: true, force: true });
+    return { ok: true, id: payload.draft.id, restoredPath: '.dql/local/apps.sqlite', draft: payload.draft };
 }
-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.' };
+export function preflightStoredAppBuildDraft(projectRoot, draft) {
+    const errors = [];
+    const blocks = collectBlockCandidates(projectRoot);
+    if (draft.state === 'clarification_required')
+        errors.push('Resolve required Build Frame clarifications before publication.');
+    if (draft.pages.length === 0)
+        errors.push('App Build Draft needs at least one page.');
+    for (const requirement of draft.requirements.filter((item) => appBuildRequirementBlocksPublication(draft, item))) {
+        const coverage = draft.coverage.find((item) => item.requirementId === requirement.id);
+        if (!coverage || coverage.status !== 'covered')
+            errors.push(`Required App question is unresolved: ${requirement.question}`);
+    }
+    for (const task of draft.reviewTasks.filter((item) => appBuildReviewTaskBlocksPublication(draft, item))) {
+        errors.push(`Review task is still open: ${task.message}`);
+    }
+    if (draft.baseApp) {
+        const base = loadAppById(projectRoot, draft.baseApp.appId);
+        if (!base || fingerprintAppDirectory(base.appDir) !== draft.baseApp.fingerprint) {
+            errors.push('The published App changed after this local draft was created. Refresh the draft before publishing.');
+        }
+    }
+    for (const page of draft.pages) {
+        const parsed = parseDashboardDocument(JSON.stringify(page), `<app-build:${draft.id}/${page.id}>`);
+        if (!parsed.document)
+            errors.push(...parsed.errors.map((error) => error.message));
+    }
+    const analysisPages = draft.pages.filter((page) => page.layout.items.some((tile) => !tile.text && !tile.aiPin));
+    const receipts = draft.previewReceipts ?? (draft.previewReceipt ? [draft.previewReceipt] : []);
+    for (const page of analysisPages) {
+        const receipt = receipts.find((candidate) => candidate.pageId === page.id);
+        if (!receipt || receipt.revision !== draft.revision)
+            errors.push(`Run a current settled preview for page ${page.metadata.title || page.id} before Project publication.`);
+    }
+    for (const source of draft.sources) {
+        if (source.kind === 'block' || source.kind === 'certified_block') {
+            const block = blocks.find((candidate) => candidate.id === source.sourceRef || candidate.name === source.sourceRef || candidate.path === source.sourceRef);
+            const lifecycle = source.lifecycle ?? (source.kind === 'certified_block' ? 'certified' : block?.status);
+            const boundRevision = source.sourceRevision ?? source.sourceFingerprint;
+            if (!block)
+                errors.push(`Source ${source.id} no longer resolves at ${source.sourceRef}.`);
+            if (block && canonicalAppBlockSourceId(block) !== source.id && source.kind === 'block')
+                errors.push(`Source ${source.id} no longer matches its qualified path identity.`);
+            if (!block || block.status !== 'certified' || lifecycle !== 'certified' || source.trustState !== 'certified') {
+                errors.push(`Source ${source.qualifiedIdentity ?? source.id} is ${lifecycle ?? 'unknown'} and cannot be published to the Project.`);
+            }
+            if (block && !boundRevision) {
+                errors.push(`Source ${source.qualifiedIdentity ?? source.id} has no bound source revision; refresh it before Project publication.`);
+            }
+            else if (block && boundRevision !== block.fingerprint) {
+                errors.push(`Source ${source.qualifiedIdentity ?? source.id} changed after selection.`);
+            }
+        }
+        if (source.kind === 'governed_semantic' || source.kind === 'semantic_query') {
+            if (source.reviewStatus !== 'approved' || !source.snapshotId || !source.receiptId) {
+                errors.push(`Source ${source.id} requires snapshot-bound semantic approval before Project publication.`);
+            }
+        }
+        if ((source.kind === 'block' && source.trustState !== 'certified') || source.kind === 'review_block' || source.kind === 'review_dql' || source.kind === 'exploratory_sql') {
+            errors.push(`Source ${source.id} is review-required and cannot be published to the Project.`);
+        }
+        if (((source.kind === 'block' && source.trustState !== 'certified') || source.kind === 'review_block' || source.kind === 'review_dql' || source.kind === 'exploratory_sql') && draft.sourcePolicy !== 'include_review_required') {
+            errors.push(`Source ${source.id} requires include_review_required policy.`);
+        }
     }
-    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 settledPageIds = new Set(receipts.filter((receipt) => receipt.revision === draft.revision).map((receipt) => receipt.pageId));
+    const readiness = appPublicationReadiness(projectRoot, draft.pages, { settledPageIds });
+    errors.push(...readiness.blockers.map((blocker) => blocker.message));
+    return Array.from(new Set(errors));
+}
+function preflightAppBuildRequestErrors(projectRoot, draft, verifyPreview) {
+    const errors = preflightStoredAppBuildDraft(projectRoot, draft);
+    const analysisPages = draft.pages
+        .map((page) => ({
+        pageId: page.id,
+        tileIds: page.layout.items.filter((tile) => !tile.text && !tile.aiPin).map((tile) => tile.i),
+    }))
+        .filter((page) => page.tileIds.length > 0);
+    const receipts = draft.previewReceipts ?? (draft.previewReceipt ? [draft.previewReceipt] : []);
+    if (analysisPages.length > 0 && !verifyPreview) {
+        errors.push('The runtime cannot verify the settled App preview receipts.');
+    }
+    for (const page of analysisPages) {
+        const receipt = receipts.find((candidate) => candidate.pageId === page.pageId);
+        if (!receipt || !verifyPreview)
+            continue;
+        const verified = verifyPreview({
+            runId: receipt.id,
+            draftId: draft.id,
+            dashboardId: page.pageId,
+            tileIds: page.tileIds,
+        });
+        if (!verified.ok
+            || verified.snapshotId !== receipt.snapshotId
+            || verified.resultFingerprint !== receipt.resultFingerprint) {
+            errors.push(verified.ok
+                ? `The saved preview receipt for ${page.pageId} no longer matches the settled run.`
+                : verified.error);
+        }
+    }
+    return Array.from(new Set(errors));
+}
+function appBuildRequirementBlocksPublication(draft, requirement) {
+    if (!requirement.required)
+        return false;
+    if (draft.authoringMode === 'manual' && draft.frame.metrics.length === 0 && requirement.measures.length === 0)
+        return false;
+    return true;
+}
+function appBuildReviewTaskBlocksPublication(draft, task) {
+    if (task.status !== 'open')
+        return false;
+    if (task.sourceId && draft.sources.some((source) => source.id === task.sourceId))
+        return true;
+    if (task.tileId && draft.pages.some((page) => page.layout.items.some((tile) => tile.i === task.tileId)))
+        return true;
+    if (task.pageId && draft.pages.some((page) => page.id === task.pageId))
+        return true;
+    // v2 AI plans previously persisted general guidance as open tasks without an
+    // attached source, page, or tile. Keep those reminders readable, but do not
+    // turn them into an unexplained hard publication gate.
+    return false;
+}
+function hasCurrentAppBuildPreflightReceipt(draft) {
+    return Boolean(draft.preflightReceipt
+        && draft.preflightReceipt.revision === draft.revision
+        && draft.preflightReceipt.proposalHash === draft.proposalHash
+        && draft.preflightReceipt.sourceFingerprint === appBuildSourceFingerprint(draft));
+}
+export function markStoredAppBuildDraftPreflighted(projectRoot, draft) {
+    const errors = preflightStoredAppBuildDraft(projectRoot, draft);
+    if (errors.length)
+        throw new Error(`App Build preflight failed: ${errors.join(' ')}`);
+    const now = new Date().toISOString();
+    const next = {
+        ...draft,
+        state: 'preflight_ready',
+        preflightReceipt: {
+            id: `app_preflight_${createHash('sha256').update(`${draft.id}:${draft.revision}:${draft.proposalHash}`).digest('hex').slice(0, 16)}`,
+            revision: draft.revision,
+            proposalHash: draft.proposalHash,
+            sourceFingerprint: appBuildSourceFingerprint(draft),
+            createdAt: now,
         },
+        updatedAt: now,
     };
-    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) };
+    writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: draft.revision });
+    return next;
 }
-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.`,
-                });
+function appBuildSourceFingerprint(draft) {
+    const sources = [...draft.sources]
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((source) => ({
+        id: source.id,
+        kind: source.kind,
+        sourceRef: source.sourceRef,
+        snapshotId: source.snapshotId,
+        sourceFingerprint: source.sourceFingerprint,
+        receiptId: source.receiptId,
+        reviewStatus: source.reviewStatus,
+    }));
+    return `sha256:${createHash('sha256').update(JSON.stringify(sources)).digest('hex')}`;
+}
+export function publishStoredAppBuildDraft(projectRoot, draft) {
+    const errors = preflightStoredAppBuildDraft(projectRoot, draft);
+    if (errors.length)
+        throw new Error(`App Build preflight failed: ${errors.join(' ')}`);
+    if (!hasCurrentAppBuildPreflightReceipt(draft)) {
+        throw new Error('App Build Draft needs a current preflight receipt before publication.');
+    }
+    const destination = resolveAppPackageDir(projectRoot, draft.appId);
+    if (!draft.baseApp && existsSync(destination))
+        throw new Error(`App already exists: ${draft.appId}`);
+    if (draft.baseApp && (!existsSync(destination) || draft.baseApp.appId !== draft.appId)) {
+        throw new Error('Published App base no longer exists at the expected path.');
+    }
+    const stage = join(projectRoot, '.dql', 'local', 'app-build-staging', `${draft.id}-${Date.now()}`);
+    const dashboardDir = join(stage, 'dashboards');
+    const owner = `${process.env.USER ?? 'owner'}@local`;
+    const domain = draft.pages[0]?.metadata.domain || 'general';
+    const name = draft.name.trim() || draft.appId;
+    const containsSemantic = draft.sources.some((source) => source.kind === 'governed_semantic' || source.kind === 'semantic_query');
+    const hasCertifiedAnalysis = draft.sources.some((source) => (source.kind === 'block' || source.kind === 'certified_block') && source.trustState === 'certified');
+    const lifecycle = hasCertifiedAnalysis && !containsSemantic ? 'certified' : 'review';
+    const app = {
+        version: 1,
+        id: draft.appId,
+        name,
+        description: draft.frame.decision || `Governed analytical App for ${name}`,
+        visibility: 'shared',
+        publicationIntent: 'shared_project',
+        ownerDomain: domain,
+        usesDomains: [domain],
+        requiredExports: [],
+        domain,
+        audience: draft.frame.audience,
+        lifecycle,
+        owners: [owner],
+        members: [{ userId: owner, displayName: owner, roles: ['owner', 'analyst'] }],
+        roles: [
+            { id: 'owner', displayName: 'Owner' },
+            { id: 'analyst', displayName: 'Analyst' },
+            { id: 'viewer', displayName: 'Viewer' },
+        ],
+        policies: [
+            { id: 'viewers-read', domain, minClassification: 'internal', allowedRoles: ['viewer', 'analyst', 'owner'], accessLevel: 'read', enabled: true },
+            { id: 'analyst-execute', domain, minClassification: 'internal', allowedRoles: ['analyst', 'owner'], accessLevel: 'execute', enabled: true },
+            { id: 'owner-admin', domain, minClassification: 'restricted', allowedRoles: ['owner'], accessLevel: 'admin', enabled: true },
+        ],
+        rlsBindings: [],
+        schedules: [],
+        homepage: { type: 'dashboard', id: draft.pages[0].id },
+    };
+    const committedPages = draft.pages.map((page) => ({
+        ...page,
+        version: 2,
+        metadata: { ...page.metadata, visibility: 'shared', lifecycle },
+    }));
+    mkdirSync(dashboardDir, { recursive: true });
+    mkdirSync(join(stage, 'notebooks'), { recursive: true });
+    mkdirSync(join(stage, 'drafts'), { recursive: true });
+    try {
+        writeFileSync(join(stage, 'dql.app.json'), JSON.stringify(app, null, 2) + '\n', 'utf-8');
+        for (const page of committedPages) {
+            writeFileSync(join(dashboardDir, `${page.id}.dqld`), JSON.stringify(page, null, 2) + '\n', 'utf-8');
+        }
+        writeFileSync(join(stage, 'README.md'), appReadme(app, draft.frame.audience ?? '', [], committedPages[0].id), 'utf-8');
+        mkdirSync(dirname(destination), { recursive: true });
+        if (draft.baseApp) {
+            const backup = join(projectRoot, '.dql', 'local', 'app-build-staging', `${draft.id}-backup-${Date.now()}`);
+            renameSync(destination, backup);
+            try {
+                renameSync(stage, destination);
+                rmSync(backup, { recursive: true, force: true });
             }
-            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.`,
-                    });
-                }
+            catch (error) {
+                if (!existsSync(destination) && existsSync(backup))
+                    renameSync(backup, destination);
+                throw error;
             }
         }
+        else {
+            renameSync(stage, destination);
+        }
     }
-    return { ready: blockers.length === 0, governedTiles, blockers };
+    catch (error) {
+        rmSync(stage, { recursive: true, force: true });
+        throw error;
+    }
+    const next = {
+        ...draft,
+        revision: draft.revision + 1,
+        state: 'project_published',
+        publishedFingerprint: fingerprintAppDirectory(destination),
+        updatedAt: new Date().toISOString(),
+        proposalHash: draft.proposalHash,
+    };
+    writeStoredAppBuildDraft(projectRoot, next, { expectedRevision: draft.revision });
+    const created = collectAppsList(projectRoot).find((entry) => entry.id === draft.appId);
+    if (!created)
+        throw new Error(`App was committed but could not be reloaded: ${draft.appId}`);
+    return {
+        ok: true,
+        app: created,
+        draft: next,
+        paths: ['dql.app.json', 'README.md', ...committedPages.map((page) => `dashboards/${page.id}.dqld`)].map((path) => `apps/${draft.appId}/${path}`),
+    };
 }
-function appAiBuildSessionDir(projectRoot) {
-    return join(projectRoot, '.dql', 'local', 'app-ai-builds');
+/** @deprecated Compatibility adapter for callers that still use the old name. */
+export function commitStoredAppBuildDraft(projectRoot, draft) {
+    return publishStoredAppBuildDraft(projectRoot, draft);
 }
 function writeAppAiBuildSession(projectRoot, session) {
     const dir = appAiBuildSessionDir(projectRoot);
@@ -2646,7 +5004,7 @@ function appAskTileContext(tile) {
         sourceEvidence: tile.sourceEvidence,
     };
 }
-function buildAppContextEnvelope(app, appDir, focus) {
+function buildAppContextEnvelope(projectRoot, app, appDir, focus) {
     const dashboards = findDashboardsForApp(appDir)
         .map((path) => loadDashboardDocument(path).document)
         .filter((document) => Boolean(document))
@@ -2671,6 +5029,7 @@ function buildAppContextEnvelope(app, appDir, focus) {
             caveats: app.caveats ?? [],
         },
         dashboards,
+        drafts: loadAppDraftContext(projectRoot, appDir),
         focus,
     };
 }
@@ -2683,6 +5042,9 @@ function filterBindingsForBlockSource(projectRoot, block) {
     const parameterSection = sectionBody(source, 'parameterPolicy');
     const bindings = Array.from(filterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"([^"]+)"/gm))
         .map((match) => ({ filter: match[1], binding: match[2], mode: 'predicate' }));
+    const allowedFilterBindings = matchArray(source, /allowedFilters\s*=\s*\[([^\]]*)\]/)
+        .filter((filter) => !bindings.some((binding) => binding.filter === filter))
+        .map((filter) => ({ filter, binding: filter, mode: 'predicate' }));
     const parameterNames = Array.from(parameterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"dynamic"/gm))
         .map((match) => match[1]);
     const parameterBindings = parameterNames.map((param) => ({
@@ -2691,7 +5053,7 @@ function filterBindingsForBlockSource(projectRoot, block) {
         mode: 'parameter',
         paramNames: [param],
     }));
-    return uniqueFilterBindings([...bindings, ...parameterBindings]);
+    return uniqueFilterBindings([...bindings, ...allowedFilterBindings, ...parameterBindings]);
 }
 function sectionBody(source, sectionName) {
     const match = new RegExp(`${sectionName}\\s*\\{([\\s\\S]*?)\\n\\s*\\}`, 'm').exec(source);
@@ -2857,7 +5219,7 @@ function promoteSharedDashboardItem(item) {
         reviewStatus,
     };
 }
-export function deleteAppPackage(projectRoot, id) {
+export function deleteAppPackage(projectRoot, id, input = {}) {
     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.' };
@@ -2865,27 +5227,130 @@ export function deleteAppPackage(projectRoot, id) {
     const loaded = loadAppById(projectRoot, cleanId);
     if (!loaded)
         return { ok: false, status: 404, error: `App "${cleanId}" not found.` };
+    const currentFingerprint = fingerprintAppDirectory(loaded.appDir);
+    if (!input.expectedFingerprint) {
+        return { ok: false, status: 409, error: 'App deletion requires the fingerprint shown during confirmation.' };
+    }
+    if (input.expectedFingerprint !== currentFingerprint) {
+        return { ok: false, status: 409, error: 'This App changed since deletion was requested. Refresh and review it again.' };
+    }
     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');
+    const trashRoot = join(projectRoot, '.dql', 'local', 'trash', 'apps');
     mkdirSync(trashRoot, { recursive: true });
     const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    let trashDir = join(trashRoot, `${stamp}-${cleanId}`);
+    let recoveryId = `${stamp}-${cleanId}`;
+    let trashDir = join(trashRoot, recoveryId);
     let suffix = 2;
-    while (existsSync(trashDir))
-        trashDir = join(trashRoot, `${stamp}-${cleanId}-${suffix++}`);
-    renameSync(loaded.appDir, trashDir);
+    while (existsSync(trashDir)) {
+        recoveryId = `${stamp}-${cleanId}-${suffix++}`;
+        trashDir = join(trashRoot, recoveryId);
+    }
+    mkdirSync(trashDir, { recursive: true });
+    const packageDir = join(trashDir, 'package');
+    renameSync(loaded.appDir, packageDir);
+    let localArchive;
+    try {
+        const dbPath = defaultLocalAppsDbPath(projectRoot);
+        if (existsSync(dbPath)) {
+            const storage = new LocalAppStorage(dbPath);
+            try {
+                localArchive = storage.archiveAndDeleteAppState(cleanId);
+            }
+            finally {
+                storage.close();
+            }
+            writeFileSync(join(trashDir, 'local-state.json'), JSON.stringify(localArchive, null, 2) + '\n', 'utf-8');
+        }
+        writeFileSync(join(trashDir, 'recovery.json'), JSON.stringify({
+            version: 1,
+            recoveryId,
+            appId: cleanId,
+            originalPath: relativeAppDir,
+            appFingerprint: currentFingerprint,
+            deletedAt: new Date().toISOString(),
+        }, null, 2) + '\n', 'utf-8');
+    }
+    catch (error) {
+        if (localArchive) {
+            const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+            try {
+                storage.restoreAppState(localArchive);
+            }
+            finally {
+                storage.close();
+            }
+        }
+        if (!existsSync(loaded.appDir) && existsSync(packageDir))
+            renameSync(packageDir, loaded.appDir);
+        rmSync(trashDir, { recursive: true, force: true });
+        throw error;
+    }
+    const localRowsArchived = localArchive
+        ? Object.values(localArchive.rows).reduce((count, rows) => count + rows.length, 0)
+        : 0;
     return {
         ok: true,
         id: cleanId,
         deletedPath: relativeAppDir,
         trashPath: relative(projectRoot, trashDir).replaceAll('\\', '/'),
+        recoveryId,
+        localRowsArchived,
+        sourceControlImpact: 'delete',
     };
 }
+export function restoreAppPackage(projectRoot, recoveryId) {
+    const cleanRecoveryId = cleanString(recoveryId);
+    if (!cleanRecoveryId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cleanRecoveryId)) {
+        return { ok: false, status: 400, error: 'A valid recovery id is required.' };
+    }
+    const recoveryDir = join(projectRoot, '.dql', 'local', 'trash', 'apps', cleanRecoveryId);
+    const manifestPath = join(recoveryDir, 'recovery.json');
+    const packageDir = join(recoveryDir, 'package');
+    if (!existsSync(manifestPath) || !existsSync(packageDir))
+        return { ok: false, status: 404, error: 'App recovery bundle not found.' };
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (!manifest.appId || !manifest.originalPath || manifest.originalPath.startsWith('../')) {
+        return { ok: false, status: 400, error: 'App recovery bundle is invalid.' };
+    }
+    const destination = join(projectRoot, manifest.originalPath);
+    if (existsSync(destination))
+        return { ok: false, status: 409, error: `Cannot restore because ${manifest.originalPath} already exists.` };
+    mkdirSync(dirname(destination), { recursive: true });
+    renameSync(packageDir, destination);
+    try {
+        const localStatePath = join(recoveryDir, 'local-state.json');
+        if (existsSync(localStatePath)) {
+            const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+            try {
+                storage.restoreAppState(JSON.parse(readFileSync(localStatePath, 'utf-8')));
+            }
+            finally {
+                storage.close();
+            }
+        }
+    }
+    catch (error) {
+        renameSync(destination, packageDir);
+        throw error;
+    }
+    rmSync(recoveryDir, { recursive: true, force: true });
+    return { ok: true, id: manifest.appId, restoredPath: manifest.originalPath };
+}
+export function restoreAppRecovery(projectRoot, recoveryId) {
+    const cleanRecoveryId = cleanString(recoveryId);
+    if (!cleanRecoveryId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(cleanRecoveryId)) {
+        return { ok: false, status: 400, error: 'A valid recovery id is required.' };
+    }
+    const draftRecovery = join(projectRoot, '.dql', 'local', 'trash', 'app-drafts', cleanRecoveryId, 'recovery.json');
+    return existsSync(draftRecovery)
+        ? restoreStoredAppBuildDraft(projectRoot, cleanRecoveryId)
+        : restoreAppPackage(projectRoot, cleanRecoveryId);
+}
 export function createAppPackage(projectRoot, input) {
     const name = cleanString(input.name);
     const domain = cleanString(input.ownerDomain) || cleanString(input.domain);
@@ -2903,16 +5368,23 @@ export function createAppPackage(projectRoot, input) {
     const audience = cleanString(input.audience);
     const subdomain = cleanString(input.subdomain);
     const groups = normalizeTags(input.groups ?? []);
-    const visibility = input.visibility === 'private' || input.visibility === 'template' ? input.visibility : 'shared';
-    const lifecycle = input.lifecycle === 'certified' || input.lifecycle === 'review' || input.lifecycle === 'deprecated'
-        ? input.lifecycle
-        : 'draft';
+    // API-013: authoring always starts as a private draft. Project visibility is
+    // available only through the publication endpoint and its live trust checks.
+    const visibility = 'private';
+    const lifecycle = 'draft';
     const tags = normalizeTags([...(input.tags ?? []), audience ? `audience:${slugify(audience)}` : '']);
     const selectedIds = Array.from(new Set((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean)));
     const blocks = collectBlockCandidates(projectRoot);
     const selectedBlocks = selectedIds
         .map((blockId) => blocks.find((block) => block.id === blockId || block.name === blockId))
         .filter((block) => Boolean(block));
+    const missingBlocks = selectedIds.filter((blockId) => !selectedBlocks.some((block) => block.id === blockId || block.name === blockId));
+    if (missingBlocks.length)
+        return { ok: false, error: `Unknown block selection: ${missingBlocks.join(', ')}` };
+    const uncertifiedBlocks = selectedBlocks.filter((block) => block.status !== 'certified');
+    if (uncertifiedBlocks.length) {
+        return { ok: false, error: `Manual App creation accepts certified blocks only: ${uncertifiedBlocks.map((block) => block.name).join(', ')}` };
+    }
     const app = {
         version: 1,
         id,
@@ -2970,7 +5442,7 @@ export function createAppPackage(projectRoot, input) {
         homepage: { type: 'dashboard', id: dashboardId },
     };
     const dashboard = {
-        version: 1,
+        version: 2,
         id: dashboardId,
         metadata: {
             title: dashboardTitle,
@@ -2983,11 +5455,13 @@ export function createAppPackage(projectRoot, input) {
             lifecycle,
             tags,
         },
+        filters: dashboardFiltersForBlocks(selectedBlocks),
         layout: {
             kind: 'grid',
             cols: 12,
             rowHeight: 80,
-            items: buildDashboardItems(selectedBlocks),
+            items: buildDashboardItems(projectRoot, selectedBlocks),
+            responsive: responsiveLayoutsForDashboardItems(buildDashboardItems(projectRoot, selectedBlocks)),
         },
     };
     const paths = [
@@ -3013,7 +5487,81 @@ export function createAppPackage(projectRoot, input) {
         dashboardId,
     };
 }
-function buildDashboardItems(blocks) {
+function createAppPackageViaBuildDraft(projectRoot, input) {
+    const name = cleanString(input.name);
+    const domain = cleanString(input.ownerDomain) || cleanString(input.domain);
+    if (!name)
+        return { ok: false, error: 'name is required' };
+    if (!domain)
+        return { ok: false, error: 'domain is required' };
+    const appId = suggestAppId(name);
+    if (existsSync(resolveAppPackageDir(projectRoot, appId)))
+        return { ok: false, error: `App already exists: ${appId}` };
+    const selectedIds = unique((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean));
+    const blocks = collectBlockCandidates(projectRoot);
+    const selectedBlocks = selectedIds
+        .map((id) => blocks.find((block) => block.id === id || block.name === id))
+        .filter((block) => Boolean(block));
+    const missing = selectedIds.filter((id) => !selectedBlocks.some((block) => block.id === id || block.name === id));
+    if (missing.length)
+        return { ok: false, error: `Unknown block selection: ${missing.join(', ')}` };
+    const uncertified = selectedBlocks.filter((block) => block.status !== 'certified');
+    if (uncertified.length)
+        return { ok: false, error: `Manual App creation accepts certified blocks only: ${uncertified.map((block) => block.name).join(', ')}` };
+    const draft = createStoredAppBuildDraft(projectRoot, {
+        appId,
+        name,
+        goal: name,
+        audience: cleanString(input.audience),
+        domain,
+        authoringMode: 'manual',
+        sourcePolicy: 'governed_only',
+    });
+    const items = buildDashboardItems(projectRoot, selectedBlocks);
+    const page = {
+        ...draft.pages[0],
+        id: slugify(cleanString(input.dashboardTitle) || 'Overview') || 'overview',
+        metadata: {
+            ...draft.pages[0].metadata,
+            title: cleanString(input.dashboardTitle) || 'Overview',
+            description: cleanString(input.purpose) || `Starter dashboard for ${name}`,
+            domain,
+            audience: cleanString(input.audience) || undefined,
+        },
+        filters: dashboardFiltersForBlocks(selectedBlocks),
+        layout: {
+            ...draft.pages[0].layout,
+            items,
+            responsive: responsiveLayoutsForDashboardItems(items),
+        },
+    };
+    const operations = [
+        ...(page.id === draft.pages[0].id ? [] : [{ type: 'remove_page', pageId: draft.pages[0].id }]),
+        { type: 'upsert_page', page },
+        ...selectedBlocks.map((block) => ({
+            type: 'upsert_source',
+            source: {
+                id: `block:${block.id}`,
+                kind: 'certified_block',
+                sourceRef: block.id,
+                sourceFingerprint: block.fingerprint,
+                trustState: 'certified',
+                reviewStatus: 'not_required',
+            },
+        })),
+    ];
+    const revised = applyAppBuildDraftOperations(draft, draft.revision, operations);
+    writeStoredAppBuildDraft(projectRoot, revised, { expectedRevision: draft.revision, operations });
+    try {
+        const preflighted = markStoredAppBuildDraftPreflighted(projectRoot, revised);
+        const committed = publishStoredAppBuildDraft(projectRoot, preflighted);
+        return { ok: true, app: committed.app, paths: committed.paths, dashboardId: page.id };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function buildDashboardItems(projectRoot, blocks) {
     let x = 0;
     let y = 0;
     let rowH = 0;
@@ -3027,13 +5575,51 @@ function buildDashboardItems(blocks) {
             y += rowH || size.h;
             rowH = 0;
         }
-        const item = dashboardItemForBlock(block, chartType, x, y, size, index);
+        const item = dashboardItemForBlock(block, chartType, x, y, size, index, filterBindingsForBlockSource(projectRoot, block));
         x += size.w;
         rowH = Math.max(rowH, size.h);
         return item;
     });
 }
-function dashboardItemForBlock(block, chartType, x, y, size, index) {
+function dashboardFiltersForBlocks(blocks) {
+    return unique(blocks.flatMap((block) => block.filterIds)).map((id) => ({
+        id,
+        label: id.replace(/[_-]+/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase()),
+        type: /(?:^|_)(?:top_n|limit|count|amount|number|minimum|maximum)(?:_|$)/i.test(id)
+            ? 'number'
+            : /(?:date|time|period|month|quarter|year)/i.test(id)
+                ? 'date'
+                : /(?:^|_)(?:name|id|search|email)(?:_|$)/i.test(id)
+                    ? 'search'
+                    : 'select',
+        bindsTo: id,
+    }));
+}
+function responsiveLayoutsForDashboardItems(items) {
+    const project = (cols) => {
+        let x = 0;
+        let y = 0;
+        let rowHeight = 0;
+        return [...items].sort((left, right) => left.y - right.y || left.x - right.x).map((item) => {
+            const width = cols === 1 ? 1 : Math.min(cols, Math.max(2, Math.ceil(item.w / 2)));
+            if (x + width > cols) {
+                x = 0;
+                y += rowHeight || item.h;
+                rowHeight = 0;
+            }
+            const next = { ...item, x, y, w: width };
+            x += width;
+            rowHeight = Math.max(rowHeight, item.h);
+            return next;
+        });
+    };
+    return {
+        wide: { kind: 'grid', cols: 12, rowHeight: 80, items },
+        medium: { kind: 'grid', cols: 6, rowHeight: 80, items: project(6) },
+        narrow: { kind: 'grid', cols: 1, rowHeight: 80, items: project(1) },
+    };
+}
+function dashboardItemForBlock(block, chartType, x, y, size, index, filterBindings = []) {
     return {
         i: slugify(block.name) || `tile-${index + 1}`,
         x,
@@ -3043,7 +5629,12 @@ function dashboardItemForBlock(block, chartType, x, y, size, index) {
         block: { blockId: block.name },
         viz: { type: chartType },
         display: displayForBlockHint(block, chartType),
+        sourceClass: 'certified_block',
+        review: { status: 'not_required', sourceFingerprint: block.fingerprint },
+        trustState: 'certified',
+        reviewStatus: 'certified',
         title: block.name,
+        ...(filterBindings.length ? { filterBindings } : {}),
     };
 }
 function vizRank(chartType) {
@@ -3209,8 +5800,13 @@ function visualizationFitsResult(viz, columns, rows) {
     const hasTime = columns.some((column) => /\b(date|time|week|month|quarter|year|season|period)\b/i.test(column.name));
     if (viz === 'table' || viz === 'pivot' || viz === 'text' || viz === 'heading')
         return true;
+    // An empty row sample means "cannot judge", not "does not fit". Returning
+    // false here silently rewrote every requested visualization to `table`
+    // whenever no rows were supplied — which is the normal case when a tile is
+    // configured before its first run, so authored and AI-chosen charts were
+    // routinely discarded. Keep the request; the renderer copes with the shape.
     if (rows.length === 0)
-        return false;
+        return true;
     if (viz === 'single_value' || viz === 'kpi' || viz === 'gauge')
         return rows.length === 1 && measures.length >= 1;
     if (viz === 'line' || viz === 'area')
@@ -3399,7 +5995,7 @@ function appReadme(app, audience, blocks, dashboardId = 'overview') {
         '',
     ].join('\n');
 }
-function collectBlockCandidates(projectRoot) {
+function collectBlockCandidates(projectRoot, options = {}) {
     const blocks = [];
     const seen = new Set();
     const scanDir = (dir) => {
@@ -3415,7 +6011,12 @@ function collectBlockCandidates(projectRoot) {
                     seen.add(filePath);
                     const source = readFileSync(filePath, 'utf-8');
                     const stat = statSyncSafe(filePath);
-                    const name = matchString(source, /block\s+"([^"]+)"/) ?? entry.name.replace(/\.dql$/, '');
+                    const name = matchString(source, /block\s+"([^"]+)"/);
+                    // The App source picker is an executable-block catalog. Domain terms,
+                    // skills, and other .dql context remain available to planning, but they
+                    // must not appear as addable dashboard data sources.
+                    if (!name)
+                        continue;
                     const tags = matchArray(source, /tags\s*=\s*\[([^\]]*)\]/);
                     blocks.push({
                         id: name,
@@ -3425,10 +6026,13 @@ function collectBlockCandidates(projectRoot) {
                         owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
                         tags,
                         path: relative(projectRoot, filePath).replaceAll('\\', '/'),
+                        fingerprint: `sha256:${createHash('sha256').update(source).digest('hex')}`,
                         lastModified: stat?.mtime.toISOString() ?? new Date(0).toISOString(),
                         description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
                         llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
                         chartType: matchString(source, /chart\s*=\s*"([^"]+)"/) ?? matchString(source, /chart\.(\w+)\s*\(/) ?? undefined,
+                        filterIds: declaredAppFilterIds(source),
+                        dimensionIds: declaredAppDimensionIds(source),
                         score: 0,
                         reasons: [],
                     });
@@ -3441,7 +6045,37 @@ function collectBlockCandidates(projectRoot) {
     };
     scanDir(join(projectRoot, 'blocks'));
     scanDir(join(projectRoot, 'domains'));
-    return blocks;
+    if (options.preserveDuplicates)
+        return blocks.sort((left, right) => left.path.localeCompare(right.path));
+    const byId = new Map();
+    for (const block of blocks) {
+        const current = byId.get(block.id);
+        if (!current) {
+            byId.set(block.id, block);
+            continue;
+        }
+        const blockRank = (block.status === 'certified' ? 4 : 0) + (block.path.startsWith('domains/') ? 2 : 0);
+        const currentRank = (current.status === 'certified' ? 4 : 0) + (current.path.startsWith('domains/') ? 2 : 0);
+        if (blockRank > currentRank || (blockRank === currentRank && block.lastModified > current.lastModified))
+            byId.set(block.id, block);
+    }
+    return Array.from(byId.values());
+}
+function canonicalAppBlockSourceId(block) {
+    const pathIdentity = createHash('sha256').update(`${block.path}\u0000${block.name}`).digest('hex').slice(0, 20);
+    return `app:block:${block.domain || 'global'}:${pathIdentity}`;
+}
+function declaredAppFilterIds(source) {
+    const filterSection = sectionBody(source, 'filterBindings');
+    const parameterSection = sectionBody(source, 'parameterPolicy');
+    return unique([
+        ...matchArray(source, /allowedFilters\s*=\s*\[([^\]]*)\]/),
+        ...Array.from(filterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"[^"]+"/gm)).map((match) => match[1]),
+        ...Array.from(parameterSection.matchAll(/^\s*([A-Za-z_][\w-]*)\s*=\s*"(?:dynamic|optional|business)"/gm)).map((match) => match[1]),
+    ]);
+}
+function declaredAppDimensionIds(source) {
+    return unique(matchArray(source, /dimensions\s*=\s*\[([^\]]*)\]/));
 }
 function readdirSyncSafe(dir) {
     try {
@@ -4111,10 +6745,13 @@ function resolveSelectedBlock(projectRoot, selected, sourceBlockId) {
                 owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
                 tags: matchArray(source, /tags\s*=\s*\[([^\]]*)\]/),
                 path: normalizedPath,
+                fingerprint: `sha256:${createHash('sha256').update(source).digest('hex')}`,
                 lastModified: statSyncSafe(join(projectRoot, normalizedPath))?.mtime.toISOString() ?? new Date(0).toISOString(),
                 description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
                 llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
                 chartType: matchString(source, /chart\s*=\s*"([^"]+)"/) ?? undefined,
+                filterIds: declaredAppFilterIds(source),
+                dimensionIds: declaredAppDimensionIds(source),
                 score: 0,
                 reasons: [],
             };
@@ -5051,14 +7688,29 @@ function uniqueAppPageId(base, existingIds) {
  * deliberately stricter than the metadata snapshot: page, notebook, draft, and
  * App-document edits all invalidate approval before the atomic directory swap.
  */
+/**
+ * Fingerprint the parts of an App package a write can actually conflict with:
+ * the manifest and the dashboard documents.
+ *
+ * Hashing every byte under the App directory made the guard far too sensitive —
+ * a notebook run output, a README edit, or an attached notebook would
+ * invalidate a page proposal that could not possibly conflict with them, and
+ * the commit failed with an unexplained 409.
+ */
 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())
+            if (entry.isDirectory()) {
+                // Only `dashboards/` participates; notebooks, drafts and generated prose do not.
+                if (directory === appDir && entry.name !== 'dashboards')
+                    continue;
                 visit(absolutePath);
+            }
             else if (entry.isFile() || entry.isSymbolicLink()) {
+                if (directory === appDir && entry.name !== 'dql.app.json')
+                    continue;
                 files.push({ path: absolutePath, symbolicLink: entry.isSymbolicLink() });
             }
         }
@@ -5679,6 +8331,32 @@ function readNotebookRunSnapshot(absNotebookPath) {
 function normalizeNotebookRole(value) {
     return value === 'source' || value === 'analysis' ? value : 'supporting';
 }
+/** Longest draft SQL carried into a prompt; drafts are context, not the answer. */
+const APP_DRAFT_SQL_PROMPT_LIMIT = 1200;
+/**
+ * The app's drafts, with enough of each to be usable as context.
+ *
+ * `listAppDrafts` reads the same files for the Drafts panel but keeps only a
+ * name and review status, which is why the drafts were visible in the UI and
+ * invisible to the copilot even once the envelope carried them.
+ */
+function loadAppDraftContext(projectRoot, appDir) {
+    return scanFiles(join(appDir, 'drafts'), '.dql').map((file) => {
+        const source = readFileSync(file, 'utf-8');
+        const path = relative(projectRoot, file).replaceAll('\\', '/');
+        const query = matchString(source, /query\s*=\s*"""([\s\S]*?)"""/)?.trim();
+        return {
+            name: matchString(source, /block\s+"([^"]+)"/) ?? titleFromPath(path),
+            path,
+            status: matchString(source, /status\s*=\s*"([^"]+)"/) ?? 'review',
+            description: matchString(source, /description\s*=\s*"([^"]*)"/) ?? undefined,
+            question: matchString(source, /question\s*=\s*"([^"]*)"/) ?? undefined,
+            sql: query
+                ? query.length > APP_DRAFT_SQL_PROMPT_LIMIT ? `${query.slice(0, APP_DRAFT_SQL_PROMPT_LIMIT)}\n-- …truncated` : query
+                : undefined,
+        };
+    }).sort((a, b) => a.name.localeCompare(b.name));
+}
 function listAppDrafts(projectRoot, appDir) {
     return scanFiles(join(appDir, 'drafts'), '.dql').map((file) => {
         const source = readFileSync(file, 'utf-8');
@@ -5788,6 +8466,7 @@ function loadDashboardForApp(projectRoot, appId, dashboardId) {
     }
     return null;
 }
+export { writeDashboard as writeDashboardForTest };
 function writeDashboard(projectRoot, appId, dashboardId, payload) {
     // Validate against the dashboard schema before touching disk.
     const { document, errors } = parseDashboardDocument(JSON.stringify(payload), '<incoming>');
@@ -5803,6 +8482,22 @@ function writeDashboard(projectRoot, appId, dashboardId, payload) {
         return { ok: false, error: `App "${appId}" not found` };
     const appDir = loaded.appDir;
     const dashboardPath = join(appDir, 'dashboards', `${dashboardId}.dqld`);
+    // Dashboard ids are unique only within an App — `overview` is a common name —
+    // so a caller holding one App's document and another App's id would silently
+    // overwrite the wrong file. Only accept a title change to an existing page,
+    // never a wholesale replacement of a different App's page of the same name.
+    if (existsSync(dashboardPath)) {
+        const existing = loadDashboardDocument(dashboardPath).document;
+        const incomingBlocks = new Set(document.layout.items.map((item) => item.i));
+        const existingBlocks = new Set((existing?.layout.items ?? []).map((item) => item.i));
+        const overlap = [...incomingBlocks].filter((tileId) => existingBlocks.has(tileId)).length;
+        if (existingBlocks.size > 0 && incomingBlocks.size > 0 && overlap === 0) {
+            return {
+                ok: false,
+                error: `Refusing to overwrite "${appId}/${dashboardId}": the incoming page shares no tiles with the one on disk, so it is very likely a different App's page of the same name.`,
+            };
+        }
+    }
     mkdirSync(dirname(dashboardPath), { recursive: true });
     writeFileSync(dashboardPath, JSON.stringify(document, null, 2) + '\n', 'utf-8');
     return { ok: true, path: dashboardPath };