@duckcodeailabs/dql-cli 1.6.20 → 1.6.22

package/dist/local-runtime.js

@@ -7,21 +7,23 @@ import { dirname, extname, join, normalize, relative, resolve } from 'node:path'
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, getDialect, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, writeDomainDeclaration, deleteDomainDeclaration, domainFolderSlug, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, recordQueryRun, recordRuntimeSchemaSnapshot, } from '@duckcodeailabs/dql-agent';
-import { handleAppsApi, recommendVisualization } from './apps-api.js';
+import { ClaudeProvider, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, } from '@duckcodeailabs/dql-agent';
+import { gatherProposeEnrichment } from './propose-enrich.js';
+import { createAppAiBuildSession, handleAppsApi, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
 import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
 import { LocalAppStorage, LocalNotebookResearchStorage, defaultLocalAppsDbPath, defaultNotebookResearchDbPath } from '@duckcodeailabs/dql-project';
-import { Certifier, ENTERPRISE_RULES } from '@duckcodeailabs/dql-governance';
+import { Certifier, ENTERPRISE_RULES, evaluateInvariants, hasInvariantViolation, } from '@duckcodeailabs/dql-governance';
 import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
 import { clearBlockStudioImportSessions, createBlockStudioImportSession, deleteBlockStudioImportSession, listBlockStudioImportSessions, loadBlockStudioImportSession, readBlockStudioImportCandidate, parameterizeSqlForDqlImport, updateBlockStudioImportCandidate, writeBlockStudioImportSession, writeBlockStudioImportCandidate, } from './block-studio-import.js';
 import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, } from './metricflow.js';
 const NOTEBOOK_EXECUTE_PREVIEW_ROW_LIMIT = 500;
+const NOTEBOOK_FAVICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#6d5dfc"/><path d="M9 9h14v14H9z" fill="none" stroke="#fff" stroke-width="2"/><path d="M13 13h6M13 17h6M13 21h4" stroke="#fff" stroke-width="2" stroke-linecap="round"/></svg>';
 export function resolveProjectSemanticConfig(projectConfig, projectRoot) {
     const configured = projectConfig.semanticLayer;
     const dbtProjectDir = projectConfig.dbt?.projectDir;
@@ -51,6 +53,82 @@ function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir) {
     }
     return false;
 }
+const AGENT_RUN_REQUESTED_MODES = new Set(['auto', 'ask', 'research', 'sql', 'block', 'app']);
+const AGENT_RUN_SELECTED_OBJECT_KINDS = new Set([
+    'notebook',
+    'cell',
+    'block',
+    'app',
+    'dashboard',
+    'research',
+    'workspace',
+]);
+function agentRunRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function agentRunString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function parseAgentRunRequestedMode(value) {
+    return typeof value === 'string' && AGENT_RUN_REQUESTED_MODES.has(value)
+        ? value
+        : undefined;
+}
+function parseAgentRunSelectedObject(value) {
+    const record = agentRunRecord(value);
+    if (!record)
+        return undefined;
+    const kind = agentRunString(record.kind);
+    if (!kind || !AGENT_RUN_SELECTED_OBJECT_KINDS.has(kind))
+        return undefined;
+    return {
+        kind: kind,
+        id: agentRunString(record.id),
+        title: agentRunString(record.title),
+        path: agentRunString(record.path),
+    };
+}
+function parseAgentRunHistory(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const history = value.flatMap((item) => {
+        const record = agentRunRecord(item);
+        if (!record)
+            return [];
+        const role = record.role === 'user' || record.role === 'assistant' ? record.role : undefined;
+        const text = agentRunString(record.text) ?? agentRunString(record.content);
+        return role && text ? [{ role, text }] : [];
+    });
+    return history.length > 0 ? history.slice(-20) : undefined;
+}
+function parseAgentRunRequestBody(body) {
+    const record = agentRunRecord(body);
+    if (!record)
+        return { error: 'Invalid JSON body.' };
+    const question = agentRunString(record.question) ?? agentRunString(record.prompt) ?? agentRunString(record.message);
+    if (!question)
+        return { error: 'question is required.' };
+    const selectedObject = parseAgentRunSelectedObject(record.selectedObject);
+    const workspaceContext = agentRunRecord(record.workspaceContext) ?? agentRunRecord(record.context);
+    const signals = agentRunRecord(record.signals);
+    const requestedMode = parseAgentRunRequestedMode(record.requestedMode) ?? parseAgentRunRequestedMode(record.mode);
+    const audience = record.audience === 'stakeholder' || record.audience === 'analyst'
+        ? record.audience
+        : undefined;
+    return {
+        request: {
+            question,
+            requestedMode,
+            audience,
+            intent: agentRunString(record.intent),
+            signals: signals,
+            selectedObject,
+            workspaceContext,
+            history: parseAgentRunHistory(record.history),
+            runId: agentRunString(record.runId),
+        },
+    };
+}
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
@@ -126,6 +204,582 @@ export async function startLocalServer(opts) {
         const result = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
         return normalizeQueryResult(result, semantic.semanticRefs);
     };
+    const runBlockReflectionProbe = async ({ sql, invariants }) => {
+        const activeConnection = requireActiveConnection();
+        const prepared = prepareLocalExecution(sql, activeConnection, projectRoot, projectConfig);
+        const probeSql = `SELECT * FROM (${stripSqlTerminator(prepared.sql)}) _dql_probe LIMIT 2000`;
+        const probeResult = await executor.executeQuery(probeSql, [], runtimeVariables({}), prepared.connection);
+        const rows = (Array.isArray(probeResult?.rows) ? probeResult.rows : []);
+        const rawColumns = Array.isArray(probeResult?.columns)
+            ? probeResult.columns
+            : [];
+        const actualColumns = rawColumns.length > 0
+            ? rawColumns.map((c) => (typeof c === 'string' ? c : c?.name ?? String(c)))
+            : (rows[0] ? Object.keys(rows[0]) : []);
+        const invariantResults = evaluateInvariants(invariants, { columns: actualColumns, rows });
+        const passed = invariantResults.filter((r) => r.passed && !r.uncheckable).length;
+        const failed = invariantResults.filter((r) => !r.passed && !r.uncheckable).length;
+        return {
+            actualColumns,
+            invariantResults,
+            tests: invariants.length > 0
+                ? { passed, failed, assertionCount: invariantResults.length }
+                : undefined,
+        };
+    };
+    const agentRunWorkspaceValue = (request, key) => {
+        const workspace = request.workspaceContext ?? {};
+        const nested = agentRunRecord(workspace.context);
+        return agentRunString(workspace[key]) ?? (nested ? agentRunString(nested[key]) : undefined);
+    };
+    const agentRunNotebookPath = (request, runId) => (agentRunWorkspaceValue(request, 'notebookPath')
+        ?? (request.selectedObject?.kind === 'notebook' || request.selectedObject?.kind === 'cell' ? request.selectedObject.path : undefined)
+        ?? `notebooks/agent-research/${runId}.dqlnb`);
+    const agentRunResearchIntent = (request) => {
+        switch (request.intent) {
+            case 'diagnose_change':
+                return 'diagnose_change';
+            case 'driver_breakdown':
+                return 'driver_breakdown';
+            case 'segment_compare':
+                return 'segment_compare';
+            case 'entity_drilldown':
+                return 'entity_drilldown';
+            case 'anomaly_investigation':
+                return 'anomaly_investigation';
+            case 'trust_gap_review':
+                return 'trust_gap_review';
+            default:
+                if (/\b(driver|why|cause|contributor|breakdown)\b/i.test(request.question))
+                    return 'driver_breakdown';
+                if (/\b(anomaly|spike|drop|outlier)\b/i.test(request.question))
+                    return 'anomaly_investigation';
+                if (/\b(compare|segment|cohort)\b/i.test(request.question))
+                    return 'segment_compare';
+                return 'ad_hoc_analysis';
+        }
+    };
+    const agentRunSourceCell = (request) => {
+        const sourceCellId = agentRunWorkspaceValue(request, 'sourceCellId') ?? request.selectedObject?.id;
+        if (!sourceCellId)
+            return undefined;
+        return {
+            id: sourceCellId,
+            sourceCellId,
+            name: agentRunWorkspaceValue(request, 'sourceCellName') ?? request.selectedObject?.title,
+            sourceCellName: agentRunWorkspaceValue(request, 'sourceCellName') ?? request.selectedObject?.title,
+            type: agentRunWorkspaceValue(request, 'sourceCellType'),
+            sql: agentRunWorkspaceValue(request, 'cellSql'),
+            fingerprint: agentRunWorkspaceValue(request, 'sourceCellFingerprint'),
+        };
+    };
+    const agentRunTitle = (question, fallback) => {
+        const cleaned = question.replace(/\s+/g, ' ').trim();
+        if (!cleaned)
+            return fallback;
+        return cleaned.length > 90 ? `${cleaned.slice(0, 87)}...` : cleaned;
+    };
+    const parseAgentRunSelectedBlockIds = (request) => {
+        const workspace = request.workspaceContext ?? {};
+        const value = workspace.selectedBlockIds ?? workspace.blockIds;
+        if (!Array.isArray(value))
+            return [];
+        return Array.from(new Set(value.flatMap((item) => {
+            const id = agentRunString(item);
+            return id ? [id] : [];
+        })));
+    };
+    const formatAgentRunInfrastructureError = (error, scope) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/Could not locate the bindings file/i.test(message) || /better[-_]sqlite3/i.test(message)) {
+            return `${scope} is unavailable because the local SQLite native bindings are not installed for this Node.js runtime.`;
+        }
+        return message;
+    };
+    const formatNotebookResearchStorageError = (error) => (formatAgentRunInfrastructureError(error, 'Notebook research storage'));
+    const buildAgentPromptArtifact = async (request, target, repair) => {
+        try {
+            await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
+        }
+        catch {
+            // Best-effort: buildFromPrompt can still use any existing KG/cache state.
+        }
+        const skills = loadSkills(projectRoot).skills;
+        // On a repair re-run, target the prior failure and (for blocks) revise in place.
+        const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
+        const mode = target === 'block' && (isRepair || agentRunWorkspaceValue(request, 'mode') === 'edit')
+            ? 'edit'
+            : 'create';
+        const prompt = isRepair
+            ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}`
+            : request.question;
+        return buildFromPrompt({
+            projectRoot,
+            prompt,
+            context: {
+                cellSql: agentRunWorkspaceValue(request, 'cellSql'),
+                selection: agentRunWorkspaceValue(request, 'selection'),
+            },
+            target,
+            mode,
+            blockPath: target === 'block'
+                ? agentRunWorkspaceValue(request, 'blockPath') ?? request.selectedObject?.path
+                : undefined,
+            owner: agentRunWorkspaceValue(request, 'owner'),
+            domain: target === 'block' ? agentRunWorkspaceValue(request, 'domain') : undefined,
+            userId: agentRunWorkspaceValue(request, 'userId'),
+            skills,
+            dbtManifestPath: resolveDbtManifestPath(projectRoot, projectConfig),
+            executionProbe: target === 'block' ? runBlockReflectionProbe : undefined,
+        });
+    };
+    const agentRunEvaluation = (id, label, passed, severity, message, evidence) => ({ id, label, passed, severity, message, evidence });
+    const agentRunArtifact = (kind, title, payload, ref, trustState = 'review_required') => ({
+        id: `${kind}:${Date.now()}`,
+        kind,
+        title,
+        trustState,
+        ref,
+        payload,
+    });
+    const coerceNarrateResultData = (value) => {
+        const record = agentRunRecord(value);
+        if (!record)
+            return undefined;
+        const columns = Array.isArray(record.columns)
+            ? record.columns.map((c) => (typeof c === 'string' ? c : agentRunRecord(c)?.name ?? String(c)))
+            : [];
+        const rows = Array.isArray(record.rows) ? record.rows.filter((r) => Boolean(agentRunRecord(r))) : [];
+        if (rows.length === 0)
+            return undefined;
+        return { columns: columns.length > 0 ? columns : Object.keys(rows[0]), rows };
+    };
+    // Provider-backed narration for stakeholder stories. Reuses the same provider
+    // adapter as the planner; narrateResult always returns (deterministic fallback).
+    const narrateForAgentRun = async (input) => narrateResult(input, {
+        complete: async ({ system, user, signal }) => {
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider)
+                throw new Error('No AI provider configured for narration.');
+            return provider.generate([{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 600, temperature: 0.2, signal });
+        },
+    });
+    async function runGovernedAgentAnswerForRun(request, repair) {
+        const resolvedProvider = resolveDefaultLLMProvider(projectRoot);
+        const runner = resolvedProvider ? getLLMRunner(resolvedProvider) : null;
+        if (!resolvedProvider || !runner) {
+            throw new Error('No AI provider is configured. Configure OpenAI, Gemini, Ollama, or a custom OpenAI-compatible endpoint in Settings.');
+        }
+        let governedAnswer;
+        let providerError;
+        const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
+        const contextEnvelope = {
+            mode: 'agent_run',
+            selectedObject: request.selectedObject,
+            workspaceContext: request.workspaceContext,
+            instruction: [
+                'Route through the governed DQL answer loop.',
+                'Prefer certified DQL blocks when they exactly cover the question.',
+                'Generated SQL remains review-required and must use the bounded preview executor.',
+                'If the question needs investigation, return the clearest answer and next review action without certifying generated work.',
+                ...(isRepair ? [`This is a repair attempt — fix the previous failure: ${repair?.repairHint}`] : []),
+            ].join(' '),
+        };
+        const controller = new AbortController();
+        await runner.run({
+            provider: resolvedProvider,
+            messages: [
+                ...(request.history ?? []).map((message) => ({ role: message.role, content: message.text })),
+                { role: 'user', content: isRepair ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}` : request.question },
+            ],
+            upstream: {
+                cellId: `agent-run:${request.selectedObject?.kind ?? 'workspace'}:${request.selectedObject?.id ?? request.runId ?? 'auto'}`,
+                sql: JSON.stringify(contextEnvelope, null, 2),
+            },
+            projectRoot,
+            executeCertifiedBlock: executeCertifiedBlockForAgent,
+            executeGeneratedSql: executeGeneratedSqlForAgent,
+            getSchemaContext: getSchemaContextForAgent,
+        }, (turn) => {
+            if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
+                governedAnswer = turn.output;
+            }
+            if (turn.kind === 'error') {
+                providerError = turn.message;
+            }
+        }, controller.signal);
+        if (!governedAnswer) {
+            throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
+        }
+        return governedAnswer;
+    }
+    const answerRunExecutor = async ({ request, routeDecision, attempt, repairHint }) => {
+        let governedAnswer;
+        try {
+            governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint });
+            // Surface the approved Hint-Graph corrections that shaped this answer so the
+            // UI can show an "applied learnings" chip (memoryContext is already on the answer).
+            if (!governedAnswer.appliedHints) {
+                governedAnswer.appliedHints = governedAnswer.contextPack?.appliedHints;
+            }
+        }
+        catch (error) {
+            const message = formatAgentRunInfrastructureError(error, 'AI answer provider');
+            return {
+                summary: message,
+                status: 'blocked',
+                trustState: 'blocked',
+                stopReason: 'blocked',
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
+                    agentRunEvaluation('ai-provider', 'AI provider', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
+                ],
+                nextActions: [
+                    { id: 'retry-ask-after-provider', label: 'Retry after provider setup', route: 'generated_answer' },
+                    { id: 'research-without-answer', label: 'Research with available metadata', route: 'research', artifactKind: 'research_run' },
+                ],
+            };
+        }
+        const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
+        const needsClarification = governedAnswer.kind === 'no_answer';
+        const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
+        const status = needsClarification ? 'needs_clarification' : isCertified ? 'completed' : 'needs_review';
+        const trustState = needsClarification ? 'not_applicable' : isCertified ? 'certified' : 'review_required';
+        const stopReason = needsClarification ? 'needs_clarification' : isCertified ? 'certified_answer_found' : 'human_review_required';
+        const nextActions = needsClarification
+            ? [{ id: 'clarify', label: 'Clarify question', route: 'generated_answer' }]
+            : [
+                ...(sql ? [{ id: 'insert-sql', label: 'Insert SQL cell', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
+                { id: 'research-gap', label: 'Research deeper', route: 'research' },
+                { id: 'create-block', label: 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+            ];
+        return {
+            summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : 'Answered with review-required generated analysis.'),
+            answer: governedAnswer.answer ?? governedAnswer.text,
+            status,
+            trustState,
+            stopReason,
+            artifacts: needsClarification
+                ? []
+                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : 'review_required')],
+            evaluations: [
+                agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.'),
+                agentRunEvaluation('trust-boundary', 'Trust boundary', isCertified, isCertified ? 'info' : 'warning', isCertified
+                    ? 'The answer came from certified DQL context.'
+                    : needsClarification
+                        ? 'The answer loop needs more context before producing a governed answer.'
+                        : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
+                ...(governedAnswer.executionError ? [
+                    agentRunEvaluation('execution-error', 'Execution error', false, 'warning', governedAnswer.executionError),
+                ] : []),
+            ],
+            nextActions,
+        };
+    };
+    const agentRunExecutors = {
+        certified_answer: answerRunExecutor,
+        generated_answer: answerRunExecutor,
+        research: async ({ runId, request, routeDecision, emit }) => {
+            const metrics = loadSemanticMetrics(projectRoot);
+            let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+            const usedCertifiedOnly = blocks.length > 0;
+            if (blocks.length === 0)
+                blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+            emit({
+                type: 'executor.started',
+                message: 'Building catalog-grounded research plan.',
+                route: 'research',
+            });
+            const plan = await planResearch({
+                question: request.question,
+                metrics,
+                blocks,
+                intent: request.intent,
+                isFollowUp: Boolean(request.history?.length),
+                history: request.history,
+            });
+            const needsClarification = Boolean(plan.followUp);
+            const notebookPath = agentRunNotebookPath(request, runId);
+            const researchIntent = agentRunResearchIntent(request);
+            let researchRun;
+            let researchWorkspaceError;
+            if (!needsClarification) {
+                try {
+                    const storage = openNotebookResearchStorage();
+                    try {
+                        const sourceCell = agentRunSourceCell(request);
+                        const sourceCellId = notebookResearchSourceCellId(sourceCell);
+                        const sourceCellName = notebookResearchSourceCellName(sourceCell);
+                        const sourceCellFingerprint = notebookResearchSourceCellFingerprint(sourceCell);
+                        const created = storage.createRun({
+                            notebookPath,
+                            title: agentRunTitle(request.question, 'Agent research'),
+                            question: request.question,
+                            sourceCell,
+                            sourceCellId,
+                            sourceCellName,
+                            sourceCellFingerprint,
+                            intent: researchIntent,
+                            domain: agentRunWorkspaceValue(request, 'domain'),
+                            owner: agentRunWorkspaceValue(request, 'owner'),
+                            context: {
+                                surface: 'unified_agent_run',
+                                agentRunId: runId,
+                                routeDecision,
+                                selectedObject: request.selectedObject,
+                                workspaceContext: request.workspaceContext,
+                                plan,
+                            },
+                        });
+                        emit({
+                            type: 'artifact.created',
+                            message: 'Saved notebook research workspace record.',
+                            route: 'research',
+                            trustState: 'review_required',
+                            payload: { researchRunId: created.id, notebookPath },
+                        });
+                        const executed = await runNotebookResearch(storage, created, {
+                            domain: agentRunWorkspaceValue(request, 'domain'),
+                            owner: agentRunWorkspaceValue(request, 'owner'),
+                            sourceCellFingerprint,
+                            question: request.question,
+                            intent: researchIntent,
+                            context: {
+                                surface: 'unified_agent_run',
+                                agentRunId: runId,
+                                routeDecision,
+                                selectedObject: request.selectedObject,
+                                workspaceContext: request.workspaceContext,
+                                plan,
+                            },
+                        });
+                        researchRun = withNotebookResearchChecklist(executed);
+                    }
+                    finally {
+                        storage.close();
+                    }
+                }
+                catch (error) {
+                    researchWorkspaceError = formatNotebookResearchStorageError(error);
+                }
+            }
+            const researchResultData = coerceNarrateResultData(researchRun?.resultPreview);
+            const narration = !needsClarification && researchResultData
+                ? await narrateForAgentRun({
+                    question: request.question,
+                    intent: request.intent,
+                    result: researchResultData,
+                    evidence: plan.sources,
+                    reviewRequired: true,
+                })
+                : undefined;
+            const summary = needsClarification
+                ? 'Needs clarification before running deeper research.'
+                : narration?.summary
+                    ?? (researchRun?.status === 'ready'
+                        ? 'Saved a grounded research dossier with context evidence and next review actions.'
+                        : researchRun?.status === 'error'
+                            ? 'Saved a research dossier, but the preview needs review before promotion.'
+                            : researchWorkspaceError
+                                ? 'Prepared a grounded research plan; durable research storage is unavailable in this runtime.'
+                                : plan.done
+                                    ? 'Prepared a direct grounded-answer plan.'
+                                    : 'Prepared a grounded research plan over real DQL assets.');
+            return {
+                summary,
+                answer: plan.followUp?.question ?? narration?.summary ?? researchRun?.summary,
+                status: needsClarification ? 'needs_clarification' : 'needs_review',
+                trustState: needsClarification ? 'not_applicable' : 'review_required',
+                stopReason: needsClarification ? 'needs_clarification' : 'human_review_required',
+                artifacts: needsClarification
+                    ? []
+                    : [agentRunArtifact('research_run', 'Research plan', {
+                            plan,
+                            researchRun,
+                            researchRunId: researchRun?.id,
+                            notebookPath,
+                            workspaceError: researchWorkspaceError,
+                            routeDecision,
+                            narration,
+                            resultPreview: researchResultData,
+                            blockCount: blocks.length,
+                            metricCount: metrics.length,
+                            certifiedOnly: usedCertifiedOnly,
+                        }, researchRun?.id)],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to research.'),
+                    agentRunEvaluation('catalog-grounding', 'Catalog grounding', plan.sources.length > 0 || Boolean(researchRun?.evidence), plan.sources.length > 0 || Boolean(researchRun?.evidence) ? 'info' : 'warning', plan.sources.length > 0 || Boolean(researchRun?.evidence)
+                        ? 'Research dossier is grounded to catalog or context-pack evidence.'
+                        : 'No certified catalog source was found; output remains exploratory.', { sources: plan.sources, researchRunId: researchRun?.id, evidence: researchRun?.evidence }),
+                    agentRunEvaluation('research-workspace', 'Research workspace', Boolean(researchRun?.id), researchRun?.id ? 'info' : 'warning', researchRun?.id
+                        ? 'A durable notebook research record was saved for review and DQL promotion.'
+                        : researchWorkspaceError
+                            ? 'Research workspace storage is unavailable; the plan remains available in this agent run.'
+                            : 'No durable research record was created because the run needs clarification first.', { notebookPath, researchRunId: researchRun?.id, error: researchWorkspaceError }),
+                ],
+                nextActions: needsClarification
+                    ? [{ id: 'answer-follow-up', label: 'Answer follow-up', route: 'research' }]
+                    : [
+                        ...(researchRun?.id ? [{ id: 'open-research', label: 'Open research dossier', artifactKind: 'research_run' }] : []),
+                        ...(researchRun?.generatedSql || researchRun?.reviewedSql ? [{ id: 'insert-sql', label: 'Insert SQL cell', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
+                        { id: 'create-block', label: 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ],
+            };
+        },
+        sql_cell: async ({ request, routeDecision, attempt, repairHint }) => {
+            const result = await buildAgentPromptArtifact(request, 'cell', { attempt, repairHint });
+            return {
+                summary: 'Created a review-required SQL cell draft.',
+                answer: result.target === 'cell' ? result.explanation : undefined,
+                artifacts: [agentRunArtifact('sql_cell', 'Generated SQL cell', result)],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to SQL cell generation.'),
+                    agentRunEvaluation('review-boundary', 'Review boundary', true, 'warning', 'Generated SQL must be reviewed before it becomes certified analytics.'),
+                ],
+                nextActions: [
+                    { id: 'insert-sql', label: 'Insert SQL cell', artifactKind: 'sql_cell' },
+                    { id: 'create-block', label: 'Promote to DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                ],
+            };
+        },
+        dql_block_draft: async ({ request, routeDecision, attempt, repairHint }) => {
+            const result = await buildAgentPromptArtifact(request, 'block', { attempt, repairHint });
+            const ready = result.target === 'block' ? result.certifierVerdict.ready : false;
+            return {
+                summary: ready
+                    ? 'Created a DQL block draft that is ready for human certification review.'
+                    : 'Created a DQL block draft with review blockers or warnings.',
+                artifacts: [agentRunArtifact('dql_block_draft', result.target === 'block' ? result.name : 'DQL block draft', result, result.target === 'block' ? result.path : undefined)],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to DQL block draft generation.'),
+                    agentRunEvaluation('certification-boundary', 'Certification boundary', ready, 'warning', ready
+                        ? 'The draft has no automatic certifier blockers, but certification still requires human review.'
+                        : 'The draft has certifier blockers that must be resolved before certification review.', result),
+                ],
+                nextActions: [
+                    { id: 'open-review', label: 'Open review checklist', artifactKind: 'dql_block_draft' },
+                    { id: 'build-app', label: 'Build app from block', route: 'app_build', artifactKind: 'app_draft' },
+                ],
+            };
+        },
+        app_build: async ({ request, routeDecision, emit }) => {
+            emit({
+                type: 'executor.started',
+                message: 'Creating app build session from governed app builder.',
+                route: 'app_build',
+            });
+            let session;
+            try {
+                session = await createAppAiBuildSession(projectRoot, {
+                    prompt: request.question,
+                    domain: agentRunWorkspaceValue(request, 'domain'),
+                    owner: agentRunWorkspaceValue(request, 'owner'),
+                    notebookPath: agentRunWorkspaceValue(request, 'notebookPath') ?? request.selectedObject?.path,
+                    selectedBlockIds: parseAgentRunSelectedBlockIds(request),
+                    plannerMode: 'deterministic',
+                });
+            }
+            catch (error) {
+                const message = formatAgentRunInfrastructureError(error, 'App build storage');
+                return {
+                    summary: message,
+                    status: 'blocked',
+                    trustState: 'blocked',
+                    stopReason: 'blocked',
+                    evaluations: [
+                        agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to app build.'),
+                        agentRunEvaluation('app-build-storage', 'App build storage', false, 'blocking', message, { originalErrorType: error instanceof Error ? error.name : typeof error }),
+                    ],
+                    nextActions: [
+                        { id: 'research-coverage', label: 'Research missing coverage', route: 'research', artifactKind: 'research_run' },
+                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ],
+                };
+            }
+            const ready = session.status === 'ready';
+            const sessionPlan = agentRunRecord(session.plan);
+            const appTitle = agentRunString(sessionPlan?.name) ?? 'App draft';
+            // A coverage gap is NOT terminal — leave status open so the gate can escalate to
+            // drafting the missing blocks. Only genuine infra errors (the catch above) block.
+            return {
+                summary: ready
+                    ? 'Created a review-required app draft session from certified DQL assets.'
+                    : 'App build needs more certified DQL coverage before files can be generated.',
+                status: ready ? 'needs_review' : undefined,
+                trustState: ready ? 'review_required' : undefined,
+                stopReason: ready ? 'human_review_required' : undefined,
+                artifacts: ready ? [agentRunArtifact('app_draft', appTitle, {
+                        session,
+                        sessionId: session.id,
+                        appId: session.appId,
+                        dashboardId: session.dashboardId,
+                        generatedPaths: session.generatedPaths,
+                        plan: session.plan,
+                        validation: session.validation,
+                    }, session.appId)] : [],
+                evaluations: [
+                    agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to app build.'),
+                    agentRunEvaluation('app-coverage', 'Certified coverage', ready, ready ? 'info' : 'blocking', ready
+                        ? 'Generated app files are backed by certified block tiles and saved as a draft app session.'
+                        : session.error ?? 'No certified app tiles matched the request.', session),
+                ],
+                nextActions: ready
+                    ? [
+                        { id: 'open-app', label: 'Open app draft', artifactKind: 'app_draft' },
+                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ]
+                    : [
+                        { id: 'research-coverage', label: 'Research missing coverage', route: 'research', artifactKind: 'research_run' },
+                        { id: 'create-gap-blocks', label: 'Create DQL drafts for gaps', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
+                    ],
+            };
+        },
+    };
+    // Compact, catalog-grounded context the LLM planner decomposes `auto` turns against.
+    const buildAgentRunCatalogContext = () => {
+        try {
+            const blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+            const sourceBlocks = blocks.length > 0 ? blocks : collectPlanBlocks(projectRoot, { certifiedOnly: false });
+            const blockLines = sourceBlocks.slice(0, 24).map((block) => {
+                const domain = block.domain ? ` [${block.domain}]` : '';
+                const detail = block.description ? `: ${block.description}` : '';
+                return `- ${block.name}${domain}${detail}`;
+            });
+            const metrics = loadSemanticMetrics(projectRoot).slice(0, 24);
+            const metricLines = metrics.map((metric) => {
+                const node = metric;
+                return `- ${node.name ?? node.label ?? node.id ?? 'metric'}`;
+            });
+            return [
+                blockLines.length > 0 ? `Available DQL blocks:\n${blockLines.join('\n')}` : 'Available DQL blocks: none',
+                metricLines.length > 0 ? `Governed metrics:\n${metricLines.join('\n')}` : '',
+            ].filter(Boolean).join('\n\n');
+        }
+        catch {
+            return '';
+        }
+    };
+    // Provider-agnostic completion the planner injects. Reuses the configured provider
+    // adapter; throwing here makes the planner fall back to its deterministic path.
+    const agentRunPlanner = createLlmAgentRunPlanner({
+        complete: async ({ system, user, signal }) => {
+            const provider = await createBlockStudioAssistProvider(projectRoot);
+            if (!provider)
+                throw new Error('No AI provider configured for planning.');
+            return provider.generate([
+                { role: 'system', content: system },
+                { role: 'user', content: user },
+            ], { maxTokens: 700, temperature: 0.1, signal });
+        },
+        getCatalogContext: buildAgentRunCatalogContext,
+    });
+    const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
+    const agentRunEngine = new AgentRunEngine({
+        store: agentRunStore,
+        executors: agentRunExecutors,
+        gates: defaultAgentRunGates,
+        planner: agentRunPlanner,
+    });
     const runNotebookForApp = async (appId, notebookPath) => {
         const absPath = safeJoin(projectRoot, notebookPath);
         if (!absPath || !existsSync(absPath) || statSync(absPath).isDirectory() || !absPath.endsWith('.dqlnb')) {
@@ -313,21 +967,50 @@ export async function startLocalServer(opts) {
         }
         let governedAnswer;
         let providerError;
+        const memoOnly = input.mode === 'memo_only';
         const contextEnvelope = {
             mode: 'app_research',
+            generationMode: input.mode ?? 'sql_and_memo',
             intent: input.intent,
             appId: input.appId,
             dashboardId: input.dashboardId,
             sourceTileId: input.sourceTileId,
             sourceBlockId: input.sourceBlockId,
             title: input.title,
-            instruction: 'Generate review-required read-only SQL when certified blocks do not exactly answer the requested research grain. Execute only through the bounded generated SQL preview path.',
+            instruction: [
+                'Answer as an app-scoped analyst. Start from certified block/result context, active filters, dbt/semantic metadata, and schema evidence.',
+                memoOnly
+                    ? 'Write the stakeholder memo from the supplied selected result, preview rows, generated SQL, metrics, drivers, filters, and caveats. Do not generate replacement SQL unless the user explicitly asks to fix SQL.'
+                    : 'Generate review-required read-only SQL only when the certified result does not exactly answer the requested analysis grain. Execute only through the bounded generated SQL preview path.',
+                'In the natural-language answer, write a stakeholder analysis memo, not a generic chat answer. Use Markdown headings chosen for the question, usually Executive answer, Key numbers, Drivers or Business readout, Caveats, and Next action.',
+                'Use concrete numbers from the selected result or preview when available. If baseline, segment, grain, lineage, or source proof is missing, say that explicitly instead of inventing a driver story.',
+                'Keep raw SQL in proposedSql/sql. Do not put SQL code fences or implementation trace in the memo body.',
+            ].join(' '),
+            generatedSql: input.generatedSql,
+            metrics: input.metrics,
+            drivers: input.drivers,
+            resultPreviews: input.resultPreviews,
+            summaryHint: input.summaryHint,
+            recommendationHint: input.recommendationHint,
+            sqlError: input.sqlError,
+            sqlErrorKind: input.sqlErrorKind,
+            hasReportEvidence: input.hasReportEvidence,
             context: input.context,
         };
         const controller = new AbortController();
         await runner.run({
             provider: resolvedProvider,
-            messages: [{ role: 'user', content: input.question }],
+            messages: [{
+                    role: 'user',
+                    content: memoOnly
+                        ? [
+                            `Research question: ${input.question}`,
+                            'Write the business memo now using only the evidence envelope supplied as upstream context.',
+                            'Return Markdown sections. Keep SQL, query text, implementation trace, and raw routing details out of the memo body.',
+                            'If the evidence is insufficient, state the gap and the next reviewer action instead of filling the story with generic text.',
+                        ].join('\n')
+                        : input.question,
+                }],
             upstream: {
                 cellId: `app-research:${input.appId}:${input.dashboardId ?? 'app'}`,
                 sql: JSON.stringify(contextEnvelope, null, 2),
@@ -348,7 +1031,7 @@ export async function startLocalServer(opts) {
             throw new Error(providerError ?? 'The AI provider did not return a governed answer.');
         }
         return {
-            sql: governedAnswer.proposedSql ?? governedAnswer.sql,
+            sql: memoOnly ? undefined : governedAnswer.proposedSql ?? governedAnswer.sql,
             answer: governedAnswer.answer ?? governedAnswer.text,
             result: governedAnswer.result,
             analysisPlan: governedAnswer.analysisPlan,
@@ -360,6 +1043,87 @@ export async function startLocalServer(opts) {
         };
     };
     const openNotebookResearchStorage = () => new LocalNotebookResearchStorage(defaultNotebookResearchDbPath(projectRoot));
+    const notebookResearchStorageUnavailableMessage = 'Notebook research storage is unavailable because the local SQLite native bindings are not installed for this Node.js runtime.';
+    const notebookResearchNextActionFilters = [
+        'fix_blockers',
+        'review_sql',
+        'review_context',
+        'run_preview',
+        'reuse_existing',
+        'create_dql_draft',
+        'open_certification',
+        'complete_review',
+        'continue_review',
+    ];
+    const isNotebookResearchStorageUnavailable = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        return /better[-_]sqlite3/i.test(message) || /Could not locate the bindings file/i.test(message);
+    };
+    const emptyNotebookResearchNextActionCounts = () => Object.fromEntries(notebookResearchNextActionFilters.map((action) => [action, 0]));
+    const emptyNotebookResearchListPage = (input = {}) => ({
+        runs: [],
+        total: 0,
+        domains: [],
+        owners: [],
+        intents: [],
+        notebooks: [],
+        counts: {
+            total: 0,
+            ready: 0,
+            needsReview: 0,
+            dqlDrafts: 0,
+            errors: 0,
+            reuseExisting: 0,
+            extendExisting: 0,
+            replacements: 0,
+            createNew: 0,
+            draftReady: 0,
+            certificationReady: 0,
+            blocked: 0,
+            staleOpen: 0,
+            expiredOpen: 0,
+            sourceLinked: 0,
+            nextActions: emptyNotebookResearchNextActionCounts(),
+        },
+        groupCounts: {
+            domains: 0,
+            owners: 0,
+            intents: 0,
+            notebooks: 0,
+        },
+        limit: input.limit,
+        offset: input.offset ?? 0,
+    });
+    const emptyNotebookResearchDiagnostics = () => ({
+        counts: {
+            totalRuns: 0,
+            activeRuns: 0,
+            closedRuns: 0,
+            notebooks: 0,
+            domains: 0,
+            owners: 0,
+            sourceLinkedRuns: 0,
+        },
+        health: {
+            staleOpenRuns: 0,
+            expiredOpenRuns: 0,
+            staleThresholdDays: 7,
+            expiredThresholdDays: 30,
+        },
+        search: {
+            indexed: false,
+            indexRows: 0,
+            stale: false,
+        },
+        updatedAt: {},
+        limits: {
+            pageSize: 50,
+            maxPageSize: 500,
+            sourceCoverageLimit: 10_000,
+            seedCellLimit: 1000,
+        },
+        warnings: [notebookResearchStorageUnavailableMessage],
+    });
     const runNotebookResearch = async (storage, run, input = {}) => {
         const question = notebookResearchString(input.question) || run.question;
         const domain = notebookResearchString(input.domain) ?? run.domain;
@@ -936,7 +1700,19 @@ export async function startLocalServer(opts) {
         if (tests.length === 0) {
             return { passed: 0, failed: 0, skipped: 0, duration: Date.now() - start, assertions: [], runAt: new Date() };
         }
-        const prepared = prepareLocalExecution(plan.sql, activeConnection, projectRoot, projectConfig);
+        // Run tests against the SAME SQL the preview runs: for a semantic block with a
+        // pre-compiled query, that's the query (not a recompiled metric), so the test's
+        // output columns match the block's declared outputs.
+        const semanticCompose = semanticLayer
+            ? composeSemanticBlockSql(source, semanticLayer, {
+                driver: activeConnection.driver,
+                tableMapping,
+                projectRoot,
+                projectConfig,
+                detectedProvider: semanticDetectedProvider,
+            })
+            : null;
+        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
         const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams ?? [], runtimeVariables(plan.variables ?? {}), prepared.connection);
         const rows = Array.isArray(rawResult?.rows) ? rawResult.rows : [];
         const columns = Array.isArray(rawResult?.columns)
@@ -1070,12 +1846,25 @@ export async function startLocalServer(opts) {
             sourceSystems: parsed.sourceSystems,
             replacementFor: parsed.replacementFor,
             reviewCadence: parsed.reviewCadence,
+            metricRef: parsed.metricRef || undefined,
+            metricsRef: parsed.metricsRef.length > 0 ? parsed.metricsRef : undefined,
             dependencies: [],
             usedInCount: 0,
             createdAt: new Date(),
             updatedAt: new Date(),
         };
-        const certification = new Certifier(options.enterprise ? ENTERPRISE_RULES : undefined).evaluate(record, testResults ?? undefined);
+        // Evaluate declared invariants against the preview result so the
+        // `invariants-hold` certifier rule can enforce them. Best-effort: when the
+        // preview failed there is no result to check, and the rule then blocks
+        // certification (in enterprise mode) because the guarantees are unverified.
+        const invariantEval = preview
+            ? evaluateBlockInvariants(source, {
+                columns: preview.result.columns,
+                rows: preview.result.rows,
+            })
+            : null;
+        record.invariants = extractBlockInvariants(source);
+        const certification = new Certifier(options.enterprise ? ENTERPRISE_RULES : undefined).evaluate(record, testResults ?? undefined, invariantEval ? { invariantResults: invariantEval.invariantResults } : undefined);
         const checklist = buildBlockStudioCertificationChecklist({
             source,
             validation,
@@ -1084,7 +1873,19 @@ export async function startLocalServer(opts) {
             certificationErrors: certification.errors,
             extraBlockers: blockers,
         });
-        return { certification, checklist, validation, preview, testResults };
+        return {
+            certification,
+            checklist,
+            validation,
+            preview,
+            testResults,
+            invariantResults: invariantEval?.invariantResults ?? [],
+            invariantViolation: invariantEval?.invariantViolation ?? false,
+        };
+    };
+    const writeAgentRunSse = (response, event, data) => {
+        response.write(`event: ${event}\n`);
+        response.write(`data: ${serializeJSON(data)}\n\n`);
     };
     const server = createServer(async (req, res) => {
         const requestUrl = req.url || '/';
@@ -1099,9 +1900,540 @@ export async function startLocalServer(opts) {
             res.end();
             return;
         }
-        if (req.method === 'GET' && path === '/api/health') {
-            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON({ status: 'ok' }));
+        if (req.method === 'GET' && path === '/api/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ status: 'ok' }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/agent-runs') {
+            const rawLimit = Number(url.searchParams.get('limit'));
+            const limit = Number.isFinite(rawLimit) && rawLimit > 0
+                ? Math.min(200, Math.floor(rawLimit))
+                : 50;
+            const runs = agentRunStore
+                .list()
+                .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+                .slice(0, limit);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ runs, total: agentRunStore.list().length, limit }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/agent-runs') {
+            try {
+                const body = await readJSON(req).catch(() => null);
+                const parsed = parseAgentRunRequestBody(body);
+                if (!parsed.request) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: parsed.error ?? 'Invalid agent run request.' }));
+                    return;
+                }
+                const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
+                if (wantsStream) {
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream; charset=utf-8',
+                        'Cache-Control': 'no-cache',
+                        'Connection': 'keep-alive',
+                        'X-Accel-Buffering': 'no',
+                    });
+                    const run = await agentRunEngine.run(parsed.request, (event) => {
+                        writeAgentRunSse(res, 'agent-run-event', event);
+                    });
+                    writeAgentRunSse(res, 'agent-run-complete', run);
+                    res.end();
+                    return;
+                }
+                const run = await agentRunEngine.run(parsed.request);
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ run }));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (res.headersSent) {
+                    writeAgentRunSse(res, 'agent-run-error', { error: message });
+                    res.end();
+                }
+                else {
+                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: message }));
+                }
+            }
+            return;
+        }
+        // Stakeholder → analyst handoff: turn a review-required output into a draft
+        // research run in the analyst notebook queue (no authoring by the stakeholder).
+        if (req.method === 'POST' && path === '/api/agent-runs/request-certification') {
+            try {
+                const body = await readJSON(req).catch(() => null);
+                const record = agentRunRecord(body);
+                const question = record ? agentRunString(record.question) : undefined;
+                if (!question) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: 'question is required.' }));
+                    return;
+                }
+                const notebookPath = (record && agentRunString(record.notebookPath))
+                    ?? `notebooks/certification-requests/${Date.now()}.dqlnb`;
+                const generatedSql = record ? agentRunString(record.generatedSql) : undefined;
+                try {
+                    const storage = openNotebookResearchStorage();
+                    try {
+                        const created = storage.createRun({
+                            notebookPath,
+                            title: agentRunTitle(question, 'Certification request'),
+                            question,
+                            intent: 'ad_hoc_analysis',
+                            domain: record ? agentRunString(record.domain) : undefined,
+                            owner: record ? agentRunString(record.owner) : undefined,
+                            generatedSql,
+                            context: {
+                                surface: 'stakeholder_request_certification',
+                                requestedContext: agentRunRecord(record?.context) ?? null,
+                            },
+                        });
+                        res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: true, researchRunId: created.id, notebookPath }));
+                    }
+                    finally {
+                        storage.close();
+                    }
+                }
+                catch (error) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: formatNotebookResearchStorageError(error) }));
+                }
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        const agentRunMatch = /^\/api\/agent-runs\/([^/]+)$/.exec(path);
+        if (req.method === 'GET' && agentRunMatch) {
+            const id = decodeURIComponent(agentRunMatch[1]);
+            const run = await agentRunStore.get(id);
+            if (!run) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Agent run not found.' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ run }));
+            return;
+        }
+        // Readiness → propose backbone. Returns a readiness summary plus the ranked
+        // DRAFT proposals (each with its stored Certifier verdict) so the notebook
+        // "Get Started" surface can route them into human review. dryRun preview —
+        // nothing is written or certified by this call.
+        if ((req.method === 'GET' || req.method === 'POST') && path === '/api/propose') {
+            try {
+                let owner;
+                let limit;
+                if (req.method === 'POST') {
+                    const body = await readJSON(req).catch(() => ({}));
+                    if (typeof body?.owner === 'string')
+                        owner = body.owner;
+                    if (typeof body?.limit === 'number' && Number.isFinite(body.limit) && body.limit > 0) {
+                        limit = body.limit;
+                    }
+                }
+                else {
+                    const ownerParam = url.searchParams.get('owner');
+                    if (ownerParam)
+                        owner = ownerParam;
+                    const limitParam = Number(url.searchParams.get('limit'));
+                    if (Number.isFinite(limitParam) && limitParam > 0)
+                        limit = limitParam;
+                }
+                const readiness = buildProposeReadiness(projectRoot, loadProjectConfig(projectRoot), { owner, limit });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(readiness));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Deterministic PLAN only (classify → plan). Writes NOTHING. Same data the
+        // readiness endpoint embeds, exposed standalone for the approve gate.
+        if (req.method === 'POST' && path === '/api/propose/plan') {
+            try {
+                const readiness = buildProposeReadiness(projectRoot, loadProjectConfig(projectRoot));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(readiness.ready ? readiness.plan : { ready: false, reason: readiness.reason }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Materialize drafts for an APPROVED scope { slugs } (or { domains }).
+        // This is the only propose endpoint that writes — and only for the approved,
+        // business-only selection. Nothing is ever certified.
+        if (req.method === 'POST' && path === '/api/propose/generate') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const config = loadProjectConfig(projectRoot);
+                let slugs = Array.isArray(body?.slugs)
+                    ? body.slugs.filter((s) => typeof s === 'string')
+                    : [];
+                // { domains } → resolve to the plan's slugs for those domains.
+                if (slugs.length === 0 && Array.isArray(body?.domains)) {
+                    const wanted = new Set(body.domains.filter((d) => typeof d === 'string'));
+                    const readiness = buildProposeReadiness(projectRoot, config);
+                    slugs = readiness.ready
+                        ? readiness.plan.domains
+                            .filter((d) => wanted.has(d.name))
+                            .flatMap((d) => d.candidates.map((c) => c.slug))
+                        : [];
+                }
+                if (slugs.length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide a non-empty { slugs } or { domains } scope to generate.' }));
+                    return;
+                }
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const result = await generateProposeDrafts(projectRoot, slugs, config, { owner });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Materialize a single approved draft { slug } and return it. Convenience for
+        // the per-block "Review & Certify" affordance.
+        if (req.method === 'POST' && path === '/api/propose/draft') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const slug = typeof body?.slug === 'string' ? body.slug : '';
+                if (!slug) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { slug } to draft.' }));
+                    return;
+                }
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const result = await generateProposeDrafts(projectRoot, [slug], loadProjectConfig(projectRoot), { owner });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Transparent PLAN PREVIEW for ONE candidate (spec 14, part A). Lazy +
+        // expensive: builds the real SQL + Certifier verdict + best-effort AI
+        // enrichment for a single slug, so the UI shows the actual logic before a
+        // human commits. Writes NOTHING.
+        if (req.method === 'GET' && path === '/api/propose/preview') {
+            try {
+                const slug = url.searchParams.get('slug')?.trim();
+                if (!slug) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide a ?slug= query parameter.' }));
+                    return;
+                }
+                const candidate = await buildProposeCandidatePreview(projectRoot, slug, url.searchParams.get('owner') ?? undefined);
+                if (!candidate) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `No proposed candidate found for slug "${slug}".` }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ candidate }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Unified AI BUILD (spec 14, part B). ONE engine, two targets:
+        //   target:'cell'  → generate SQL from the prompt (+ context). Writes nothing.
+        //   target:'block' → assemble a COMPLETE draft, WRITE it, return preview fields.
+        // Never routes through the governed Q&A answer-loop.
+        if (req.method === 'POST' && path === '/api/ai/build') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
+                if (!prompt) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide a non-empty { prompt }.' }));
+                    return;
+                }
+                const target = body?.target === 'cell' || body?.target === 'block' ? body.target : undefined;
+                if (!target) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: "Provide { target: 'cell' | 'block' }." }));
+                    return;
+                }
+                const context = {
+                    cellSql: typeof body?.context?.cellSql === 'string' ? body.context.cellSql : undefined,
+                    selection: typeof body?.context?.selection === 'string' ? body.context.selection : undefined,
+                };
+                const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const userId = typeof body?.userId === 'string'
+                    ? body.userId
+                    : undefined;
+                // Edit mode (spec 17, part A): modify the block at `blockPath` in place.
+                const mode = body?.mode === 'edit' ? 'edit' : 'create';
+                const blockPath = typeof body?.blockPath === 'string' && body.blockPath.trim()
+                    ? body.blockPath.trim()
+                    : undefined;
+                if (mode === 'edit' && (target !== 'block' || !blockPath)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: "Edit mode requires target 'block' and a { blockPath }." }));
+                    return;
+                }
+                // Ensure the agent knowledge graph is built before generating, so the Build
+                // path's semantic-metric routing sees the governed metrics on the very first
+                // call (a cold Build-before-Ask otherwise reads an unbuilt KG and misses them).
+                // Mirrors what the Ask path does; reindex is idempotent and closes its write
+                // connection, so the read-only metric load observes committed data.
+                try {
+                    await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
+                }
+                catch {
+                    // Best-effort: a failed reindex falls back to whatever KG exists (or none).
+                }
+                // Inject user-authored Skills as business context; the engine selects the
+                // relevant subset and stamps `appliedSkills` on the result.
+                const skills = loadSkills(projectRoot).skills;
+                const result = await buildFromPrompt({
+                    projectRoot,
+                    prompt,
+                    context,
+                    target,
+                    mode,
+                    blockPath,
+                    owner,
+                    userId,
+                    skills,
+                    dbtManifestPath: resolveDbtManifestPath(projectRoot, loadProjectConfig(projectRoot)),
+                    // Reflect-before-certify probe (P2): run the candidate block's SQL to learn
+                    // its REAL output columns and evaluate the declared invariants, so the agent
+                    // can reconcile the output contract + produce a grounded verdict before a
+                    // human reviews. Best-effort — buildFromPrompt falls back to a static reflection.
+                    executionProbe: async ({ sql, invariants }) => {
+                        const activeConnection = requireActiveConnection();
+                        const prepared = prepareLocalExecution(sql, activeConnection, projectRoot, projectConfig);
+                        const probeSql = `SELECT * FROM (${stripSqlTerminator(prepared.sql)}) _dql_probe LIMIT 2000`;
+                        const probeResult = await executor.executeQuery(probeSql, [], runtimeVariables({}), prepared.connection);
+                        const rows = (Array.isArray(probeResult?.rows) ? probeResult.rows : []);
+                        const rawColumns = Array.isArray(probeResult?.columns)
+                            ? probeResult.columns
+                            : [];
+                        const actualColumns = rawColumns.length > 0
+                            ? rawColumns.map((c) => (typeof c === 'string' ? c : c?.name ?? String(c)))
+                            : (rows[0] ? Object.keys(rows[0]) : []);
+                        const invariantResults = evaluateInvariants(invariants, { columns: actualColumns, rows });
+                        const passed = invariantResults.filter((r) => r.passed && !r.uncheckable).length;
+                        const failed = invariantResults.filter((r) => !r.passed && !r.uncheckable).length;
+                        return {
+                            actualColumns,
+                            invariantResults,
+                            tests: invariants.length > 0
+                                ? { passed, failed, assertionCount: invariantResults.length }
+                                : undefined,
+                        };
+                    },
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Resolved local OSS owner (spec 14, part C). Stamps drafts so a new block is
+        // never born with a "Missing owner" Certifier strike.
+        if (req.method === 'GET' && path === '/api/identity') {
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ owner: resolveLocalOwner(projectRoot) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Skills (spec 16) — user-authored business context. AI drafts, humans
+        //    certify; skills never carry certification. PROJECT skills (user empty)
+        //    are shared; PERSONAL skills (user set) are user-bound. ────────────────
+        if (req.method === 'GET' && path === '/api/skills') {
+            try {
+                const skills = loadSkills(projectRoot).skills.map(serializeSkill);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ skills }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Form pickers: metrics from the semantic layer + certified block ids.
+        if (req.method === 'GET' && path === '/api/skills/options') {
+            try {
+                const metrics = semanticLayer
+                    ? semanticLayer.listMetrics().map((m) => m.name).sort()
+                    : [];
+                const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+                const blocks = Object.values(manifest.blocks)
+                    .filter((b) => b.status === 'certified')
+                    .map((b) => b.name)
+                    .sort();
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ metrics, blocks }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/skills') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseSkillInput(body?.skill);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { skill } with id, scope, and body.' }));
+                    return;
+                }
+                const skill = writeSkill(projectRoot, input);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ skill: serializeSkill(skill) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'PUT' && path.startsWith('/api/skills/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/skills/'.length));
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseSkillInput(body?.skill, id);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { skill } with scope and body.' }));
+                    return;
+                }
+                const skill = writeSkill(projectRoot, input);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ skill: serializeSkill(skill) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'DELETE' && path.startsWith('/api/skills/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/skills/'.length));
+                deleteSkill(projectRoot, id);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Domains (spec 17, part B) — first-class business domain declarations.
+        //    Authoring here satisfies `dql doctor`'s "missing domain declaration"
+        //    warning. AI drafts, humans certify; domains carry no certification. ────
+        if (req.method === 'GET' && path === '/api/domains') {
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ domains: listDomains(projectRoot) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/domains') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseDomainInput(body?.domain);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { domain } with a non-empty name.' }));
+                    return;
+                }
+                writeDomainDeclaration(projectRoot, input);
+                await refreshLocalMetadataCatalog(projectRoot);
+                const domain = findDomain(projectRoot, input.name);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ domain }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'PUT' && path.startsWith('/api/domains/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/domains/'.length));
+                const body = (await readJSON(req).catch(() => ({})));
+                const input = parseDomainInput(body?.domain, id);
+                if (!input) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide { domain } with a name.' }));
+                    return;
+                }
+                // If the name changed, remove the old declaration so we never orphan one.
+                if (domainFolderSlug(id) !== domainFolderSlug(input.name)) {
+                    deleteDomainDeclaration(projectRoot, id);
+                }
+                writeDomainDeclaration(projectRoot, input);
+                await refreshLocalMetadataCatalog(projectRoot);
+                const domain = findDomain(projectRoot, input.name);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ domain }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'DELETE' && path.startsWith('/api/domains/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/domains/'.length));
+                deleteDomainDeclaration(projectRoot, id);
+                await refreshLocalMetadataCatalog(projectRoot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/favicon.ico') {
+            res.writeHead(200, {
+                'Content-Type': 'image/svg+xml',
+                'Cache-Control': 'public, max-age=86400',
+            });
+            res.end(NOTEBOOK_FAVICON_SVG);
             return;
         }
         if (req.method === 'GET' && path === '/api/settings/env-status') {
@@ -1242,6 +2574,80 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON({ ok: true, files }));
             return;
         }
+        // Local learning loop (OSS): record an analyst's wrong→right correction as a
+        // scope-matched Hint-Graph hint plus an advisory memory, so future similar
+        // questions avoid the same mistake. Single-user self-serve — the correction IS
+        // the approval, so the derived candidate is approved immediately unless the
+        // caller opts out. Advisory only: never overrides certified routing. The
+        // multi-tenant review workflow + automated distillation stay a cloud feature.
+        if (req.method === 'POST' && path === '/api/agent/learnings/correction') {
+            const body = await readJSON(req).catch(() => null);
+            const question = body && typeof body.question === 'string' ? body.question.trim() : '';
+            const correctedSql = body && typeof body.correctedSql === 'string' ? body.correctedSql.trim() : '';
+            if (!body || !question || !correctedSql) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'question and correctedSql are required.' }));
+                return;
+            }
+            const rawScope = body.scope && typeof body.scope === 'object' ? body.scope : {};
+            const scopeStr = (key) => (typeof rawScope[key] === 'string' && rawScope[key].trim() ? rawScope[key].trim() : undefined);
+            const scope = {
+                metric: scopeStr('metric'),
+                dbtModel: scopeStr('dbtModel'),
+                domain: scopeStr('domain'),
+                dialect: scopeStr('dialect'),
+                term: scopeStr('term'),
+                block: scopeStr('block'),
+            };
+            const wrongSql = typeof body.wrongSql === 'string' ? body.wrongSql.trim() : '';
+            const rationale = typeof body.rationale === 'string' && body.rationale.trim() ? body.rationale.trim() : undefined;
+            const author = typeof body.author === 'string' ? body.author : (resolveLocalOwner(projectRoot) ?? undefined);
+            try {
+                const { trace, hint } = recordCorrectionTrace(projectRoot, {
+                    question,
+                    scope,
+                    wrongAnswer: wrongSql || '(no prior SQL captured)',
+                    correction: correctedSql,
+                    correctedSql,
+                    rationale,
+                    author,
+                    hintTitle: typeof body.title === 'string' && body.title.trim() ? body.title.trim() : undefined,
+                    hintGuidance: typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance.trim() : undefined,
+                    tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
+                });
+                let approvedHint = hint;
+                if (body.approve !== false) {
+                    reviewHint(projectRoot, { hintId: hint.id, decision: 'approved', reviewer: author ?? 'local', note: 'Self-approved (OSS single-user).' });
+                    approvedHint = { ...hint, status: 'approved' };
+                }
+                // Plain-language advisory memory mirroring the lesson, for transparency + recall.
+                try {
+                    const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                    memory.upsert({
+                        id: `mem_${hint.id}`,
+                        scope: 'project',
+                        title: approvedHint.title,
+                        content: `${approvedHint.guidance}${rationale ? ` (${rationale})` : ''}`,
+                        tags: [scope.metric, scope.domain, scope.dbtModel].filter((x) => Boolean(x)),
+                        source: 'correction',
+                        confidence: 0.9,
+                        importance: 0.85,
+                        enabled: true,
+                    });
+                    memory.close();
+                }
+                catch {
+                    /* best-effort */
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, trace, hint: approvedHint }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         const appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
         if (req.method === 'POST' && appDashRun) {
             try {
@@ -1436,6 +2842,14 @@ export async function startLocalServer(opts) {
                     executeSql: executeLocalSqlForStoredResult,
                     generateInvestigationSql: generateInvestigationSqlForApp,
                     runNotebook: (appId, notebookPath) => runNotebookForApp(appId, notebookPath),
+                    // P4: give the App ask lane a grounded research planner over the catalog.
+                    planResearch: async ({ question, isFollowUp }) => {
+                        const metrics = loadSemanticMetrics(projectRoot);
+                        let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+                        if (blocks.length === 0)
+                            blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+                        return planResearch({ question, metrics, blocks, isFollowUp });
+                    },
                 });
                 if (handled)
                     return;
@@ -1560,8 +2974,11 @@ export async function startLocalServer(opts) {
             return;
         }
         if (req.method === 'GET' && path === '/api/notebook/research') {
-            const storage = openNotebookResearchStorage();
+            let storage;
+            const limit = notebookResearchInteger(url.searchParams.get('limit'), 50, 1, 500);
+            const offset = notebookResearchInteger(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER);
             try {
+                storage = openNotebookResearchStorage();
                 const notebookPath = notebookResearchString(url.searchParams.get('path'));
                 const sourceCellId = notebookResearchString(url.searchParams.get('sourceCellId') ?? url.searchParams.get('cellId'));
                 const domain = notebookResearchString(url.searchParams.get('domain'));
@@ -1577,24 +2994,28 @@ export async function startLocalServer(opts) {
                 const activeOnlyParam = url.searchParams.get('activeOnly') ?? url.searchParams.get('active');
                 const activeOnly = activeOnlyParam === 'true' || activeOnlyParam === '1';
                 const sort = notebookResearchSort(url.searchParams.get('sort'));
-                const limit = notebookResearchInteger(url.searchParams.get('limit'), 50, 1, 500);
-                const offset = notebookResearchInteger(url.searchParams.get('offset'), 0, 0, Number.MAX_SAFE_INTEGER);
                 const page = storage.listRunsPage({ notebookPath, sourceCellId, domain, owner, intent, search, status, reviewStatus, promotionAction, readiness, age, nextAction, activeOnly, sort, limit, offset });
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON(withNotebookResearchChecklistPage(page)));
             }
             catch (error) {
+                if (isNotebookResearchStorageUnavailable(error)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(withNotebookResearchChecklistPage(emptyNotebookResearchListPage({ limit, offset }))));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/research') {
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 const body = await readJSON(req);
                 const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
                 const question = notebookResearchString(body.question);
@@ -1641,7 +3062,7 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
@@ -1686,8 +3107,9 @@ export async function startLocalServer(opts) {
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/research/seed-cells') {
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 const body = await readJSON(req);
                 const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
                 if (!notebookPath) {
@@ -1738,12 +3160,14 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/research/source-coverage') {
-            const storage = openNotebookResearchStorage();
+            let storage;
+            let requestedSourceCellCount = 0;
+            let limit = 10_000;
             try {
                 const body = await readJSON(req);
                 const notebookPath = notebookResearchString(body.notebookPath) ?? notebookResearchString(body.path);
@@ -1784,15 +3208,16 @@ export async function startLocalServer(opts) {
                 const sourceCellIds = Array.from(new Set(requestedIds
                     .map((id) => notebookResearchString(id))
                     .filter((id) => Boolean(id))));
-                const requestedSourceCellCount = new Set([
+                requestedSourceCellCount = new Set([
                     ...sourceCellIds,
                     ...sourceCells
                         .map((cell) => notebookResearchSourceCellId(cell))
                         .filter((id) => Boolean(id)),
                 ]).size;
-                const limit = typeof body.limit === 'number' && Number.isFinite(body.limit)
+                limit = typeof body.limit === 'number' && Number.isFinite(body.limit)
                     ? Math.max(1, Math.min(10_000, Math.floor(body.limit)))
                     : 10_000;
+                storage = openNotebookResearchStorage();
                 const linkedRuns = storage.listLatestRunsBySourceCell({
                     notebookPath,
                     sourceCellIds,
@@ -1815,26 +3240,42 @@ export async function startLocalServer(opts) {
                 }));
             }
             catch (error) {
+                if (isNotebookResearchStorageUnavailable(error)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        runs: [],
+                        requestedCount: requestedSourceCellCount,
+                        matchedCount: 0,
+                        limitApplied: requestedSourceCellCount > limit,
+                    }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
         if (req.method === 'GET' && path === '/api/notebook/research/diagnostics') {
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON(storage.getDiagnostics()));
             }
             catch (error) {
+                if (isNotebookResearchStorageUnavailable(error)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(emptyNotebookResearchDiagnostics()));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
@@ -1842,8 +3283,9 @@ export async function startLocalServer(opts) {
         if (notebookResearchMatch) {
             const id = decodeURIComponent(notebookResearchMatch[1]);
             const action = notebookResearchMatch[2];
-            const storage = openNotebookResearchStorage();
+            let storage;
             try {
+                storage = openNotebookResearchStorage();
                 const run = storage.getRun(id);
                 if (!run) {
                     res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -1943,7 +3385,7 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
             finally {
-                storage.close();
+                storage?.close();
             }
             return;
         }
@@ -2447,6 +3889,144 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        // ── Distinct values for a block column → app/dashboard filter dropdowns ──
+        if (req.method === 'GET' && path === '/api/dashboard/filter-options') {
+            try {
+                const blockIdParam = url.searchParams.get('block');
+                const blockPath = url.searchParams.get('path')
+                    ?? (blockIdParam ? resolveBlockPathById(projectRoot, blockIdParam) : null);
+                const column = (url.searchParams.get('column') ?? '').trim();
+                const limit = Math.min(Math.max(Number(url.searchParams.get('limit') ?? 50) || 50, 1), 200);
+                if (!blockPath || !column || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(column)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path and a valid column are required' }));
+                    return;
+                }
+                const absolutePath = resolve(projectRoot, blockPath);
+                if (!absolutePath.startsWith(projectRoot + '/') && absolutePath !== projectRoot) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path escapes project root' }));
+                    return;
+                }
+                if (!existsSync(absolutePath)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'block not found' }));
+                    return;
+                }
+                const source = readFileSync(absolutePath, 'utf-8');
+                // Only expose distinct values for a DECLARED output column — keeps the probe
+                // inside the governed block contract (no arbitrary column scanning).
+                const parsedMeta = parseBlockSourceMetadata(source);
+                if (parsedMeta.outputs.length > 0 && !parsedMeta.outputs.includes(column)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `"${column}" is not a declared output of this block` }));
+                    return;
+                }
+                const activeConnection = requireActiveConnection();
+                const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+                const semanticCompose = semanticLayer
+                    ? composeSemanticBlockSql(source, semanticLayer, {
+                        driver: activeConnection.driver,
+                        tableMapping,
+                        projectRoot,
+                        projectConfig,
+                        detectedProvider: semanticDetectedProvider,
+                    })
+                    : null;
+                const validation = validateBlockStudioSource(source, semanticLayer);
+                const baseSql = semanticCompose?.sql ?? validation.executableSql;
+                if (!baseSql) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'block has no executable SQL' }));
+                    return;
+                }
+                const prepared = prepareLocalExecution(baseSql, activeConnection, projectRoot, projectConfig);
+                const q = quoteAgentIdentifier(column, prepared.connection);
+                const wrapped = `SELECT DISTINCT ${q} AS value FROM (${stripSqlTerminator(prepared.sql)}) _dql_opt WHERE ${q} IS NOT NULL ORDER BY 1 LIMIT ${limit + 1}`;
+                const result = await executor.executeQuery(wrapped, [], runtimeVariables({}), prepared.connection);
+                const rows = Array.isArray(result?.rows) ? result.rows : [];
+                const truncated = rows.length > limit;
+                const options = rows
+                    .slice(0, limit)
+                    .map((row) => row?.value)
+                    .filter((value) => value !== null && value !== undefined)
+                    .map((value) => String(value));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ column, options, truncated }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Plan an app from a goal (P1: plan → critique → show gaps) ──────────
+        // The agent decomposes the goal into the questions an app should answer
+        // (KPI + trend + breakdowns), matches each to a CERTIFIED block, derives the
+        // shared filters that refresh every tile, and reports coverage + gaps BEFORE
+        // anything is built — so the human reviews the plan, not a blank canvas.
+        if (req.method === 'POST' && path === '/api/app-plan') {
+            try {
+                const body = await readJSON(req);
+                const goal = typeof body.goal === 'string' ? body.goal.trim() : '';
+                if (!goal) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'goal is required' }));
+                    return;
+                }
+                const certifiedOnly = body.certifiedOnly !== false;
+                const metrics = loadSemanticMetrics(projectRoot);
+                let blocks = collectPlanBlocks(projectRoot, { certifiedOnly });
+                // If nothing is certified yet, fall back to all drafts so the plan still
+                // shows what COULD be assembled (every section then reads as a gap to certify).
+                if (blocks.length === 0 && certifiedOnly)
+                    blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+                const plan = await planApp({ goal, metrics, blocks });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ plan, blockCount: blocks.length, metricCount: metrics.length, certifiedOnly }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Research / follow-up planning (P4: ReAct over the catalog) ─────────
+        // Decide whether to answer, research across grounded steps, or ask a smart
+        // follow-up — so the agent behaves like a real assistant instead of always
+        // generating one query. Every step + option is bound to a real metric/block.
+        if (req.method === 'POST' && path === '/api/research-plan') {
+            try {
+                const body = await readJSON(req);
+                const question = typeof body.question === 'string' ? body.question.trim() : '';
+                if (!question) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'question is required' }));
+                    return;
+                }
+                const metrics = loadSemanticMetrics(projectRoot);
+                let blocks = collectPlanBlocks(projectRoot, { certifiedOnly: true });
+                if (blocks.length === 0)
+                    blocks = collectPlanBlocks(projectRoot, { certifiedOnly: false });
+                const plan = await planResearch({
+                    question,
+                    metrics,
+                    blocks,
+                    intent: typeof body.intent === 'string'
+                        ? body.intent
+                        : undefined,
+                    isFollowUp: body.isFollowUp === true,
+                    history: Array.isArray(body.history) ? body.history : undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ plan, blockCount: blocks.length, metricCount: metrics.length }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         // ── Run block tests ────────────────────────────────────────────────
         if (req.method === 'POST' && path === '/api/blocks/run-tests') {
             try {
@@ -2485,7 +4065,11 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'source is required' }));
                     return;
                 }
-                const result = await certifyBlockStudioSource(source, blockPath, { enterprise: body.enterprise !== false });
+                // OSS local-first certifies in non-enterprise mode: owner + passing tests +
+                // a successful run are the gate; grain/outputs/pattern/lineage/cadence are
+                // AI-filled advisory warnings, not hard blockers. Enterprise-grade certification
+                // (all of those required) is an opt-in for the cloud tier — request it explicitly.
+                const result = await certifyBlockStudioSource(source, blockPath, { enterprise: body.enterprise === true });
                 const blockers = Array.from(new Set(result.checklist.blockers));
                 if (!result.certification.certified || blockers.length > 0) {
                     res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -2514,6 +4098,32 @@ export async function startLocalServer(opts) {
                         certifiedPayload = openBlockStudioDocument(projectRoot, normalizedBlockPath, semanticLayer);
                     }
                 }
+                // Auto-capture (OSS local learning loop): certifying a block teaches the
+                // agent to prefer it. Write a scoped, advisory project memory — deterministic,
+                // best-effort, and it never blocks certification.
+                try {
+                    const learned = parseBlockSourceMetadata(certifiedSource);
+                    if (learned.name) {
+                        const learnedOutputs = Array.isArray(learned.outputs)
+                            ? learned.outputs.filter((o) => typeof o === 'string')
+                            : [];
+                        const memory = new MemoryStore(defaultMemoryPath(projectRoot));
+                        memory.upsert({
+                            id: `mem_certify_${learned.name}`,
+                            scope: 'project',
+                            title: `Certified block: ${learned.name}`,
+                            content: `Prefer the certified block "${learned.name}" for ${learned.description?.trim() || `questions in the ${learned.domain ?? 'analytics'} domain`}.${learned.grain ? ` Grain: ${learned.grain}.` : ''}${learnedOutputs.length ? ` Outputs: ${learnedOutputs.slice(0, 8).join(', ')}.` : ''} It is the trusted source — reuse it instead of generating new SQL.`,
+                            tags: [learned.domain, learned.name, ...learnedOutputs.slice(0, 4)].filter((x) => Boolean(x)),
+                            source: 'certify',
+                            confidence: 0.95,
+                            importance: 0.85,
+                            enabled: true,
+                        });
+                    }
+                }
+                catch {
+                    /* best-effort: learning capture must never block certification */
+                }
                 await refreshLocalMetadataCatalog(projectRoot);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
@@ -2642,7 +4252,8 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const certifiedSource = setBlockStudioSourceStatus(readiness.candidate.dqlSource, 'certified');
-                    const certification = await certifyBlockStudioSource(certifiedSource, readiness.candidate.savedPath, { enterprise: true });
+                    // OSS certify = non-enterprise (owner-gated); enterprise depth is the cloud tier.
+                    const certification = await certifyBlockStudioSource(certifiedSource, readiness.candidate.savedPath, { enterprise: false });
                     const blockers = Array.from(new Set(certification.checklist.blockers));
                     if (!certification.certification.certified || blockers.length > 0) {
                         const savedDraft = saveDqlGenerationDraft(importId, readiness.candidate);
@@ -4576,6 +6187,14 @@ export async function startLocalServer(opts) {
                 assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
                 const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables(plan.variables), prepared.connection);
                 const normalized = normalizeQueryResult(rawResult);
+                // Enforce the block's declared invariants against the result set. This
+                // is additive: blocks without invariants produce `null` and the
+                // response is unchanged. The agent surface (`query_via_block`) reads
+                // these fields to downgrade the trust label on violation.
+                const invariants = evaluateBlockInvariants(executableCell.source || cell.source || '', {
+                    columns: normalized.columns,
+                    rows: normalized.rows,
+                });
                 if (execContext) {
                     recordNotebookQueryRun(projectRoot, {
                         notebookPath: execContext.notebookPath,
@@ -4604,6 +6223,12 @@ export async function startLocalServer(opts) {
                     chartConfig: plan.chartConfig,
                     tests: plan.tests,
                     result: normalized,
+                    ...(invariants
+                        ? {
+                            invariantResults: invariants.invariantResults,
+                            invariantViolation: invariants.invariantViolation,
+                        }
+                        : {}),
                 }));
             }
             catch (error) {
@@ -4679,6 +6304,7 @@ table: ${table}${tagList}
         res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
         res.end(content);
     });
+    opts.captureServer?.(server);
     return new Promise((resolvePromise, reject) => {
         let retriedWithRandomPort = false;
         server.on('error', (error) => {
@@ -4913,6 +6539,145 @@ export function serializeJSON(value) {
         return current;
     });
 }
+/** Serialize a Skill to the shared API contract shape (spec 16). */
+function serializeSkill(skill) {
+    return {
+        id: skill.id,
+        scope: skill.scope,
+        user: skill.user,
+        domain: skill.domain,
+        description: skill.description,
+        body: skill.body,
+        preferredMetrics: skill.preferredMetrics,
+        preferredBlocks: skill.preferredBlocks,
+        vocabulary: skill.vocabulary,
+        sourcePath: skill.sourcePath,
+        isStarter: skill.isStarter,
+    };
+}
+/**
+ * Validate + normalize an inbound `{ skill }` body into a WriteSkillInput.
+ * `id` + `scope` + `body` are required; `fallbackId` supplies the id on PUT
+ * (from the URL). Returns null when the payload is invalid.
+ */
+function parseSkillInput(raw, fallbackId) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const skill = raw;
+    const id = typeof skill.id === 'string' && skill.id.trim() ? skill.id.trim() : fallbackId;
+    if (!id)
+        return null;
+    const scope = skill.scope === 'personal' ? 'personal' : skill.scope === 'project' ? 'project' : undefined;
+    if (!scope)
+        return null;
+    if (typeof skill.body !== 'string')
+        return null;
+    const asStrings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+    const asMap = (value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (typeof v === 'string')
+                out[k] = v;
+        }
+        return out;
+    };
+    return {
+        id,
+        scope,
+        user: scope === 'personal' && typeof skill.user === 'string' ? skill.user : undefined,
+        domain: typeof skill.domain === 'string' && skill.domain.trim() ? skill.domain.trim() : undefined,
+        description: typeof skill.description === 'string' ? skill.description : undefined,
+        body: skill.body,
+        preferredMetrics: asStrings(skill.preferredMetrics),
+        preferredBlocks: asStrings(skill.preferredBlocks),
+        vocabulary: asMap(skill.vocabulary),
+        isStarter: skill.isStarter === true ? true : undefined,
+    };
+}
+/** Loose, case/slug-insensitive domain key for counting membership. */
+function domainKey(value) {
+    if (!value)
+        return '';
+    return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function manifestDomainToDto(domain, counts) {
+    return {
+        id: domain.name,
+        name: domain.name,
+        owner: domain.owner,
+        boundedContext: domain.boundedContext,
+        sourceSystems: domain.sourceSystems,
+        description: domain.description,
+        sourcePath: domain.filePath,
+        blockCount: counts.blockCount,
+        skillCount: counts.skillCount,
+        termCount: counts.termCount,
+    };
+}
+/** List authored domains with per-domain block/skill/term counts. */
+export function listDomains(projectRoot) {
+    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+    const domains = manifest.domains ?? {};
+    const skills = loadSkills(projectRoot).skills;
+    const blockCounts = new Map();
+    for (const block of Object.values(manifest.blocks)) {
+        const key = domainKey(block.domain);
+        if (key)
+            blockCounts.set(key, (blockCounts.get(key) ?? 0) + 1);
+    }
+    const termCounts = new Map();
+    for (const term of Object.values(manifest.terms ?? {})) {
+        const key = domainKey(term.domain);
+        if (key)
+            termCounts.set(key, (termCounts.get(key) ?? 0) + 1);
+    }
+    const skillCounts = new Map();
+    for (const skill of skills) {
+        const key = domainKey(skill.domain);
+        if (key)
+            skillCounts.set(key, (skillCounts.get(key) ?? 0) + 1);
+    }
+    return Object.values(domains)
+        .map((domain) => {
+        const key = domainKey(domain.name);
+        return manifestDomainToDto(domain, {
+            blockCount: blockCounts.get(key) ?? 0,
+            skillCount: skillCounts.get(key) ?? 0,
+            termCount: termCounts.get(key) ?? 0,
+        });
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Find a single authored domain by name/id (case/slug-insensitive). */
+function findDomain(projectRoot, nameOrId) {
+    const key = domainKey(nameOrId);
+    return listDomains(projectRoot).find((domain) => domainKey(domain.name) === key);
+}
+/** Validate + normalize an inbound `{ domain }` body into a DomainInput. */
+export function parseDomainInput(raw, fallbackId) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const domain = raw;
+    const name = typeof domain.name === 'string' && domain.name.trim()
+        ? domain.name.trim()
+        : typeof domain.id === 'string' && domain.id.trim()
+            ? domain.id.trim()
+            : fallbackId;
+    if (!name)
+        return null;
+    const asStrings = (value) => Array.isArray(value)
+        ? value.filter((v) => typeof v === 'string' && v.trim().length > 0)
+        : undefined;
+    return {
+        name,
+        owner: typeof domain.owner === 'string' ? domain.owner : undefined,
+        boundedContext: typeof domain.boundedContext === 'string' ? domain.boundedContext : undefined,
+        sourceSystems: asStrings(domain.sourceSystems),
+        description: typeof domain.description === 'string' ? domain.description : undefined,
+    };
+}
 async function refreshLocalMetadataCatalog(projectRoot) {
     try {
         await ensureMetadataCatalogFresh(projectRoot, { force: true });
@@ -4985,6 +6750,153 @@ export function loadProjectConfig(projectRoot) {
     }
     return config;
 }
+/**
+ * Core of the `/api/propose` endpoint, factored out as a pure function so it can
+ * be unit-tested without standing up an HTTP server.
+ *
+ * It reuses the existing `propose` engine from `@duckcodeailabs/dql-agent`
+ * verbatim (no inference/ranking logic is duplicated here) in `dryRun` mode so a
+ * readiness preview never mutates the project. Every returned proposal is a
+ * `status: draft` block with the engine's stored Certifier verdict attached.
+ */
+export function buildProposeReadiness(projectRoot, projectConfig = loadProjectConfig(projectRoot), options = {}) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath) {
+        return {
+            ready: false,
+            reason: 'No dbt manifest found. Run `dbt parse` (or `dbt compile`) in your dbt project, then reopen Get Started.',
+            summary: {
+                modelsScanned: 0,
+                businessModels: 0,
+                plumbingExcluded: 0,
+                metricsFound: 0,
+                proposalsRanked: 0,
+                draftsExisting: 0,
+                readyForReview: 0,
+                blockingTotal: 0,
+                warningTotal: 0,
+            },
+            plan: {
+                totals: { modelsScanned: 0, businessModels: 0, plumbingExcluded: 0, metricsFound: 0 },
+                willGenerate: 0,
+                willSkip: 0,
+                domains: [],
+                config: {
+                    businessLayers: [],
+                    excludeLayers: [],
+                    maxPerDomain: 0,
+                    minScore: 0,
+                    aiEnrichment: 'auto',
+                },
+            },
+            proposals: [],
+        };
+    }
+    const proposeConfig = projectConfig.propose;
+    // PLAN: deterministic, business-only, bounded. Writes nothing.
+    const plan = proposePlan(projectRoot, manifestPath, { config: proposeConfig });
+    // dryRun: rank + certify the selected scope only. Never writes from a preview.
+    // Stamp the resolved local OSS owner when none was passed so the stored verdict
+    // does not carry a phantom "Missing owner" strike. Read-only resolution — the
+    // preview must not mutate the project.
+    const summary = propose({
+        projectRoot,
+        dbtManifestPath: manifestPath,
+        owner: options.owner || resolveLocalOwner(projectRoot, { persist: false }),
+        limit: options.limit,
+        dryRun: true,
+        config: proposeConfig,
+    });
+    let readyForReview = 0;
+    let blockingTotal = 0;
+    let warningTotal = 0;
+    for (const proposal of summary.proposals) {
+        blockingTotal += proposal.certification.errors.length;
+        warningTotal += proposal.certification.warnings.length;
+        if (proposal.certification.errors.length === 0)
+            readyForReview += 1;
+    }
+    return {
+        ready: true,
+        summary: {
+            projectName: summary.projectName,
+            modelsScanned: summary.modelsScanned,
+            businessModels: summary.businessModels,
+            plumbingExcluded: summary.plumbingExcluded,
+            metricsFound: summary.metricsFound,
+            proposalsRanked: summary.proposalsRanked,
+            // In dryRun the engine marks already-present blocks as skipped.
+            draftsExisting: summary.draftsSkipped,
+            readyForReview,
+            blockingTotal,
+            warningTotal,
+        },
+        plan,
+        proposals: summary.proposals,
+    };
+}
+export async function generateProposeDrafts(projectRoot, slugs, projectConfig = loadProjectConfig(projectRoot), options = {}) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath) {
+        return {
+            ready: false,
+            reason: 'No dbt manifest found. Run `dbt parse` (or `dbt compile`) first.',
+            draftsWritten: 0,
+            draftsSkipped: 0,
+            proposals: [],
+        };
+    }
+    // Structure deterministic, content AI-optional: optionally pre-compute AI
+    // enrichment (description / llmContext / examples) for the approved slugs, then
+    // hand it to the deterministic engine as data. Best-effort — any failure or a
+    // missing provider falls back to dbt-derived content.
+    let enrichedBySlug;
+    const proposeConfig = resolveProposeConfig(projectConfig.propose);
+    if (proposeConfig.aiEnrichment !== 'off' && slugs.length > 0) {
+        enrichedBySlug = await gatherProposeEnrichment(projectRoot, manifestPath, projectConfig.propose, slugs).catch(() => undefined);
+    }
+    const summary = propose({
+        projectRoot,
+        dbtManifestPath: manifestPath,
+        // Stamp the resolved local OSS owner when none was passed so drafts are not
+        // born with a "Missing owner" Certifier strike.
+        owner: options.owner || resolveLocalOwner(projectRoot),
+        config: projectConfig.propose,
+        onlySlugs: slugs,
+        enrichedBySlug,
+    });
+    return {
+        ready: true,
+        draftsWritten: summary.draftsWritten,
+        draftsSkipped: summary.draftsSkipped,
+        proposals: summary.proposals,
+    };
+}
+/**
+ * Build the FILLED transparent preview for ONE proposed candidate slug (spec 14,
+ * part A). Reuses the deterministic `buildProposePreview` engine (real SQL +
+ * Certifier verdict) and best-effort AI enrichment (description/llmContext/
+ * examples) when a provider is available. Writes NOTHING. Returns `undefined`
+ * when the slug is not part of the bounded, business-only selection.
+ */
+export async function buildProposeCandidatePreview(projectRoot, slug, owner, projectConfig = loadProjectConfig(projectRoot)) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, projectConfig);
+    if (!manifestPath)
+        return undefined;
+    // Best-effort AI enrichment for this one slug (content only). Any miss falls
+    // back to the deterministic dbt-derived content inside buildProposePreview.
+    let enriched;
+    const proposeConfig = resolveProposeConfig(projectConfig.propose);
+    if (proposeConfig.aiEnrichment !== 'off') {
+        const map = await gatherProposeEnrichment(projectRoot, manifestPath, projectConfig.propose, [slug]).catch(() => undefined);
+        enriched = map?.get(slug);
+    }
+    return buildProposePreview(projectRoot, manifestPath, slug, {
+        config: projectConfig.propose,
+        owner: owner || resolveLocalOwner(projectRoot),
+        enriched,
+    });
+}
 function getProjectConnectionsForApi(config) {
     const connections = getStoredConnections(config);
     if (Object.keys(connections).length === 0 && isConnectionLike(config.defaultConnection)) {
@@ -4997,6 +6909,11 @@ const CONNECTOR_INSTALLS = {
         driver: 'duckdb',
         label: 'DuckDB',
         packageName: 'duckdb',
+        // Latest 1.x. An earlier pin to 1.1.3 worked around a BIGINT serialization crash,
+        // but that only bites a naive `JSON.stringify` — the DQL driver
+        // (`normalizeDuckDBValue`) coerces BIGINT→number before marshaling and
+        // `serializeJSON` has a BigInt replacer, so 1.4.x is verified-good on the local
+        // DuckDB path (COUNT/AVG/SELECT * over UUID/BIGINT/decimal/datetime on real data).
         packageSpec: 'duckdb@^1.1.0',
         builtIn: false,
     },
@@ -5345,6 +7262,10 @@ function buildDashboardFilterPredicate(input) {
         const end = addDashboardFilterParam(input, 'end', range.end);
         return `${input.expression} BETWEEN $${start.position} AND $${end.position}`;
     }
+    // A daterange with only one bound set is incomplete — skip it rather than binding
+    // the partial object as a scalar equality (which would produce invalid SQL).
+    if (input.filterType === 'daterange')
+        return null;
     const values = Array.isArray(input.value) ? input.value.filter((item) => !isEmptyDashboardFilterValue(item)) : [input.value];
     if (values.length === 0)
         return null;
@@ -6191,6 +8112,16 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
     if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
         return { sql: null, diagnostics, semanticRefs };
     }
+    // Import-adapter shape: a semantic block may carry a pre-compiled `query` (the
+    // governed metric already expanded to runnable SQL). When present, RUN THAT —
+    // the `metric` field is provenance/governance, not something to recompile. This
+    // keeps metric-bound blocks runnable offline (the full MetricFlow engine may be
+    // unavailable). We still validated the metric exists above. Returning the query
+    // as the composed SQL lets the normal {{ ref() }} resolution + execution apply.
+    const precompiledQuery = extractBlockStudioSql(source);
+    if (precompiledQuery) {
+        return { sql: precompiledQuery, diagnostics, semanticRefs };
+    }
     let composed;
     try {
         composed = options?.projectRoot && options.projectConfig
@@ -6536,7 +8467,7 @@ function saveDqlGenerationDraftForProject(projectRoot, importId, candidate) {
     }
 }
 export function saveBlockStudioArtifacts(projectRoot, options) {
-    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -6576,7 +8507,7 @@ export function saveBlockStudioArtifacts(projectRoot, options) {
     return targetRelativePath;
 }
 export function saveBlockStudioDraftArtifacts(projectRoot, options) {
-    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -6719,8 +8650,132 @@ function readBlockCompanionFile(projectRoot, relativePath) {
         return null;
     }
 }
+/**
+ * Extract the declared `invariants` from a block's DQL source using the core
+ * parser (the same path that populates the manifest). Returns an empty array
+ * when the source has no invariants or cannot be parsed — invariant evaluation
+ * is best-effort and must never break a run.
+ */
+export function extractBlockInvariants(source) {
+    // Only DQL block sources declare invariants. Never hand a non-DQL cell source
+    // (e.g. a raw SQL notebook cell like "SELECT 1") to the DQL parser: it can loop
+    // on input it doesn't recognize and OOM-crash the runtime on every execute.
+    // Require a `block "..."` declaration before parsing.
+    if (!/(?:^|\n)\s*block\s+["']/.test(source))
+        return [];
+    try {
+        const ast = new Parser(source).parse();
+        const block = ast.statements.find((statement) => statement.kind === 'BlockDecl');
+        return Array.isArray(block?.invariants) ? block.invariants : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Evaluate a block's declared invariants against a normalized query result.
+ * Returns `null` when the block declares no invariants so callers can omit the
+ * field entirely (blocks without invariants behave exactly as before).
+ */
+export function evaluateBlockInvariants(source, result) {
+    const invariants = extractBlockInvariants(source);
+    if (invariants.length === 0)
+        return null;
+    const invariantResults = evaluateInvariants(invariants, {
+        columns: result.columns,
+        rows: result.rows,
+    });
+    return { invariantResults, invariantViolation: hasInvariantViolation(invariantResults) };
+}
+/** Resolve a block id/slug to its `.dql` path (filename slug first, then `block "<id>"`). */
+function resolveBlockPathById(projectRoot, blockId) {
+    const wanted = blockId.trim().toLowerCase();
+    if (!wanted)
+        return null;
+    const leaf = wanted.split('.').pop() ?? wanted;
+    const escaped = leaf.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const nameRe = new RegExp(`^\\s*block\\s+"${escaped}"`, 'im');
+    const stack = ['blocks', 'domains'].map((dir) => join(projectRoot, dir));
+    let nameMatch = null;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const filePath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(filePath);
+                continue;
+            }
+            if (!entry.name.endsWith('.dql'))
+                continue;
+            const rel = relative(projectRoot, filePath).replaceAll('\\', '/');
+            if (entry.name.replace(/\.dql$/, '').toLowerCase() === leaf)
+                return rel; // fast path: filename slug
+            if (!nameMatch) {
+                try {
+                    if (nameRe.test(readFileSync(filePath, 'utf-8')))
+                        nameMatch = rel;
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    return nameMatch;
+}
+/**
+ * Collect the workspace's blocks as the App planner needs to see them (name +
+ * governed metric + filterable dimensions). Walks blocks/ and domains/, parsing
+ * each `.dql`. Certified-only by default — the planner builds an app from trusted
+ * material and reports the rest as gaps.
+ */
+function collectPlanBlocks(projectRoot, opts = {}) {
+    const out = [];
+    const seen = new Set();
+    const stack = ['blocks', 'domains'].map((dir) => join(projectRoot, dir));
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const filePath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(filePath);
+                continue;
+            }
+            if (!entry.name.endsWith('.dql'))
+                continue;
+            let source;
+            try {
+                source = readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const meta = parseBlockSourceMetadata(source);
+            if (!meta.name || seen.has(meta.name))
+                continue;
+            if (opts.certifiedOnly && meta.status !== 'certified')
+                continue;
+            seen.add(meta.name);
+            out.push({
+                name: meta.name,
+                domain: meta.domain || undefined,
+                description: meta.description || undefined,
+                metricRef: meta.metricRef || meta.metricsRef[0] || undefined,
+                allowedFilters: meta.allowedFilters,
+                dimensions: meta.dimensions,
+            });
+        }
+    }
+    return out;
+}
 export function parseBlockSourceMetadata(source) {
-    const name = source.match(/^\s*block\s+"([^"]+)"/i)?.[1] ?? '';
+    // Multiline: a `.dql` typically opens with a comment header (e.g. a proposed-draft
+    // banner), so the `block "<name>"` declaration is NOT at the start of the string.
+    // Without `m` the name parsed empty and every certified block was saved as the
+    // generic `block.dql` (slug fallback) — colliding on the 2nd certify (BLOCK_EXISTS).
+    const name = source.match(/^\s*block\s+"([^"]+)"/im)?.[1] ?? '';
     const extractString = (key) => source.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? '';
     const extractStringArray = (key) => {
         const match = source.match(new RegExp(`\\b${key}\\s*=\\s*\\[([^\\]]*)\\]`, 'i'));
@@ -6761,6 +8816,8 @@ export function parseBlockSourceMetadata(source) {
         sourceSystems: extractStringArray('sourceSystems'),
         replacementFor: extractStringArray('replacementFor'),
         reviewCadence: extractString('reviewCadence'),
+        metricRef: extractString('metric'),
+        metricsRef: extractStringArray('metrics'),
     };
 }
 function compareBlockStudioValues(actual, operator, expected) {
@@ -6810,14 +8867,15 @@ function buildBlockStudioCertificationChecklist(input) {
         blockers.add(blocker);
     if (!input.previewSucceeded)
         blockers.add('Block has not run successfully');
-    if (!input.testResults || input.testResults.failed > 0)
+    // Only a REAL test failure blocks. "No tests" and "no chart" are advisory review
+    // items the AI fills at draft time — never hard gates (owner is the gate). This is
+    // what keeps "build a DQL" from demanding ~13 fields per block at 300-query scale.
+    if (input.testResults && input.testResults.failed > 0)
         blockers.add('Tests must pass before certification');
-    if (!input.testResults || input.testResults.assertions.length === 0)
-        blockers.add('At least one test assertion is required before certification');
-    if (!input.validation.chartConfig?.chart)
-        blockers.add('Visualization config is missing');
     return {
-        metadata: Boolean(parsed.domain.trim() && parsed.owner.trim() && parsed.description.trim()),
+        // The metadata tab is green once the one required field (owner) is present.
+        // Description/domain are AI-filled + editable and surface as review items, not gates.
+        metadata: Boolean(parsed.owner.trim()),
         validation: input.validation.diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
         run: input.previewSucceeded,
         tests: Boolean(input.testResults && input.testResults.failed === 0 && input.testResults.assertions.length > 0),
@@ -7828,13 +9886,13 @@ async function createBlockStudioAssistProvider(projectRoot, requestedProvider) {
     let provider;
     switch (selected.id) {
         case 'anthropic':
-            provider = new ClaudeProvider({ apiKey: config.apiKey, model: config.model });
+            provider = new ClaudeProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'openai':
             provider = new OpenAIProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'gemini':
-            provider = new GeminiProvider({ apiKey: config.apiKey, model: config.model });
+            provider = new GeminiProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'ollama':
             provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
@@ -7975,7 +10033,7 @@ function resolveBlockWriteTarget(projectRoot, safeDomain, slug) {
     return { relativePath, absPath: join(projectRoot, relativePath) };
 }
 export function createBlockArtifacts(projectRoot, options) {
-    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -8030,7 +10088,7 @@ export function createBlockArtifacts(projectRoot, options) {
     };
 }
 export function createSemanticBuilderBlock(projectRoot, options) {
-    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9_]+/g, '-').replace(/^[-_]+|[-_]+$/g, '') || 'block';
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
@@ -8493,6 +10551,19 @@ export function discoverDbtProfileConnections(projectRoot, projectConfig) {
                 const mapped = mapDbtProfileOutput(output);
                 if (!mapped)
                     continue;
+                // dbt resolves a relative duckdb `path` against the dbt project dir (where it runs),
+                // NOT the DQL workspace. Resolve to an absolute path here so the imported connection
+                // opens the real warehouse instead of silently creating an empty db next to dql.config.json.
+                if (mapped.adapter === 'duckdb' &&
+                    mapped.connection.filepath &&
+                    mapped.connection.filepath !== ':memory:') {
+                    if (!isAbsoluteLikePath(mapped.connection.filepath)) {
+                        mapped.connection.filepath = resolve(dbtProjectPath, mapped.connection.filepath);
+                    }
+                    if (!existsSync(mapped.connection.filepath)) {
+                        mapped.warnings.push(`DuckDB file not found at ${mapped.connection.filepath} — run \`dbt build\` (or \`dbt seed\`) to create it before querying.`);
+                    }
+                }
                 const warnings = [...mapped.warnings];
                 if (targetName !== defaultTarget) {
                     warnings.push(`Not the default dbt target "${defaultTarget}".`);
@@ -9605,7 +11676,7 @@ async function testProviderConfig(projectRoot, id) {
     let provider;
     switch (id) {
         case 'gemini':
-            provider = new GeminiProvider({ apiKey: config.apiKey, model: config.model });
+            provider = new GeminiProvider({ apiKey: config.apiKey, baseUrl: config.baseUrl, model: config.model });
             break;
         case 'ollama':
             provider = new OllamaProvider({ baseUrl: config.baseUrl, model: config.model });
@@ -9666,7 +11737,10 @@ async function testAnthropicProviderConfig(config, label, details) {
         return { ok: false, message: `${label} is not configured${details}. Add an API key in Settings or ANTHROPIC_API_KEY.` };
     }
     try {
-        const client = new Anthropic({ apiKey: config.apiKey });
+        const client = new Anthropic({
+            apiKey: config.apiKey,
+            ...(config.baseUrl ? { baseURL: normalizeAnthropicBaseUrl(config.baseUrl) } : {}),
+        });
         const response = await client.messages.create({
             model: config.model ?? 'claude-opus-4-8',
             max_tokens: 16,