@duckcodeailabs/dql-cli 1.6.34 → 1.7.1

package/dist/local-runtime.js

@@ -1,20 +1,22 @@
-import { execFileSync, execSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { createServer } from 'node:http';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { homedir } from 'node:os';
-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, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, 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 { execFileSync, execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, extname, join, normalize, relative, resolve, } from "node:path";
+import { Readable } from "node:stream";
+import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, planMixedSourceNotebookSql, planMixedSourceSql, } from "./mixed-source-sql.js";
+import Anthropic from "@anthropic-ai/sdk";
+import OpenAI from "openai";
+import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, hasStandaloneSemanticRef, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
+import { loadSemanticLayerFromDir, normalizeDqlArtifactReference, serializeMetricDefinitionToYaml, resolveSemanticLayerAsync, resolveRepoSource, getDialect, Parser, NodeKind, blockParameterDefinitions, buildLineageGraph, buildManifest, collectInputFiles, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryBusiness360, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, domainFolderSlug, previewModelingChange, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, relationshipValidationProofFingerprint, discoverDbtDomains, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, } 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 { createDqlAgentProviderRunner } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, probeLocalOllamaEmbeddings, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, invalidateAgentProjectState, resolveDomainContextEnvelope, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, probeLocalOllamaEmbeddings, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
@@ -25,8 +27,10 @@ import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeA
 import { LocalAppStorage, LocalNotebookResearchStorage, defaultLocalAppsDbPath, defaultNotebookResearchDbPath } from '@duckcodeailabs/dql-project';
 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';
+import { clearBlockStudioImportSessions, candidateToDqlSource, createBlockStudioImportSession, deleteBlockStudioImportSession, listBlockStudioImportSessions, loadBlockStudioImportSession, readBlockStudioImportCandidate, parameterizeSqlForDqlImport, updateBlockStudioImportCandidate, writeBlockStudioImportSession, writeBlockStudioImportCandidate, } from './block-studio-import.js';
+import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, hasMetricFlowCli, } from "./metricflow.js";
+import { NotebookDatasetWorkspace, } from "./notebook-datasets.js";
+import { prepareBlockInvocation } from './block-invocation.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) {
@@ -152,13 +156,33 @@ export function parseAgentRunRequestBody(body) {
 export function shouldSynthesizeAgentRunAnswer(governedAnswer) {
     if (governedAnswer.kind === 'no_answer')
         return false;
+    // The executed rows are the presentation boundary: certified, semantic,
+    // DQL-first, and exploratory routes all deserve a separate stakeholder-facing
+    // explanation grounded in those values. Trust and query mechanics stay in the
+    // artifact/inspector instead of leaking into the primary answer.
+    if (governedAnswer.result)
+        return true;
     if (governedAnswer.kind === 'certified' || governedAnswer.certification === 'certified')
         return false;
+    // EXP-001: exploratory prose is part of the trust boundary. A free-form
+    // synthesis pass can accidentally relabel an entity-level lifetime measure
+    // as a child-level allocation or total repeated values. Keep the host's
+    // deterministic grain statement instead.
+    if (governedAnswer.exploratoryCandidate)
+        return false;
     const finalText = (governedAnswer.answer ?? governedAnswer.text ?? '').trim();
     if (governedAnswer.dqlArtifact && finalText)
         return false;
     return true;
 }
+function businessNarrativeGaps(warnings) {
+    const businessRelevant = (warnings ?? []).filter((warning) => !(/missing requested output column/i.test(warning)
+        || /\bquery plan\b/i.test(warning)
+        || /\bgrain\b/i.test(warning)
+        || /\bcolumn(?:s)?\b.*\bmissing\b/i.test(warning)
+        || /\bSQL\b|\bDBT\b|\bjoin probe\b/i.test(warning)));
+    return businessRelevant.length > 0 ? businessRelevant : undefined;
+}
 // ── Server-side conversation threads ────────────────────────────────────────
 // When a run carries a threadId, the persisted thread is the authoritative
 // source of prior turns (survives refresh); the client-built context remains
@@ -258,7 +282,7 @@ function conversationTurnInputFromRun(run) {
         certification: agentRunString(payload?.certification),
         sourceCertifiedBlock: agentRunString(payload?.sourceCertifiedBlock)
             ?? (artifact?.kind === 'answer' ? agentRunString(artifact.ref) : undefined),
-        contextPackId: agentRunString(payload?.contextPackId),
+        contextPackId: agentRunString(payload?.contextPackId) ?? agentRunString(contextPack?.id),
         sql: agentRunString(payload?.proposedSql) ?? agentRunString(payload?.sql),
         dqlArtifact: agentRunRecord(payload?.dqlArtifact),
         cascade: agentRunRecord(payload?.cascade),
@@ -311,15 +335,187 @@ function conversationStringArray(value) {
     const values = value.filter((item) => typeof item === 'string' && item.trim().length > 0);
     return values.length > 0 ? values : undefined;
 }
+function isLoopbackOrigin(value) {
+    try {
+        const hostname = new URL(value).hostname;
+        return hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '::1' || hostname === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
 function compactConversationRecord(record) {
     const entries = Object.entries(record).filter(([, value]) => value !== undefined && value !== null);
     return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }
+function apiRequestId(scope) {
+    return `${scope}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function apiErrorEnvelope(input) {
+    return {
+        requestId: input.requestId,
+        ...(input.snapshotId ? { snapshotId: input.snapshotId } : {}),
+        code: input.code,
+        message: input.message,
+        // Retain the legacy field during the compatibility window.
+        error: input.message,
+        recoverable: input.recoverable ?? input.code !== 'DOMAIN_COLLISION',
+        ...(input.details !== undefined ? { details: input.details } : {}),
+        ...(input.nextActions?.length ? { nextActions: input.nextActions } : {}),
+    };
+}
+function apiErrorCode(error, fallback) {
+    return typeof error === 'object' && error && 'code' in error
+        ? String(error.code)
+        : fallback;
+}
+function apiErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 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';
-    let connection = rawConnection ? normalizeProjectConnection(rawConnection, projectRoot) : null;
+    const loopback = bindHost === '127.0.0.1' || bindHost === 'localhost' || bindHost === '::1';
+    const authToken = opts.authToken ?? process.env.DQL_SERVER_TOKEN;
+    const allowedOrigins = new Set((opts.allowedOrigins ?? (process.env.DQL_ALLOWED_ORIGINS ?? '').split(','))
+        .map((value) => value.trim().replace(/\/$/, ''))
+        .filter(Boolean));
+    if (!loopback && !authToken) {
+        throw new Error('Non-loopback DQL server binding requires DQL_SERVER_TOKEN (or LocalServerOptions.authToken).');
+    }
+    if (!loopback && allowedOrigins.size === 0) {
+        throw new Error('Non-loopback DQL server binding requires DQL_ALLOWED_ORIGINS (or LocalServerOptions.allowedOrigins).');
+    }
+    const gitRoot = await resolveGitRoot(projectRoot);
+    if (gitRoot)
+        ensureLocalRuntimeGitignore(projectRoot);
     let projectConfig = loadProjectConfig(projectRoot);
+    const configuredConnection = rawConnection
+        ? normalizeProjectConnection(rawConnection, projectRoot)
+        : projectConfig.defaultConnection
+            ? normalizeProjectConnection(projectConfig.defaultConnection, projectRoot)
+            : null;
+    let connection = configuredConnection ?? resolveDbtProfileRuntimeConnection(projectRoot, projectConfig);
+    const projectSnapshots = new ProjectSnapshotService();
+    const dashboardRunEvidence = new Map();
+    const dbtNodeDetailCache = new Map();
+    const onboardingJobs = new Map();
+    const projectSnapshot = () => {
+        const dbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig) ?? undefined;
+        const inputs = collectInputFiles({ projectRoot, dbtManifestPath });
+        const signatureHash = createHash('sha256');
+        for (const input of inputs.sort()) {
+            try {
+                const stats = statSync(input);
+                signatureHash.update(`${input}\0${stats.size}\0${stats.mtimeMs}\n`);
+            }
+            catch {
+                signatureHash.update(`${input}\0missing\n`);
+            }
+        }
+        const signature = signatureHash.digest('hex');
+        const previousId = projectSnapshots.current()?.snapshotId;
+        const snapshot = projectSnapshots.refresh(signature, () => buildManifest({ projectRoot, dbtManifestPath }));
+        if (snapshot.snapshotId !== previousId)
+            dbtNodeDetailCache.clear();
+        return {
+            signature: snapshot.sourceVersion,
+            snapshotId: snapshot.snapshotId,
+            manifest: snapshot.value,
+            stale: snapshot.stale,
+            error: snapshot.error,
+        };
+    };
+    const onboardingDbtPaths = (body = {}) => {
+        const repoUrl = typeof body.repoUrl === 'string' && body.repoUrl.trim() ? body.repoUrl.trim() : undefined;
+        const branch = typeof body.branch === 'string' && body.branch.trim() ? body.branch.trim() : undefined;
+        const subPath = typeof body.subPath === 'string' && body.subPath.trim() ? body.subPath.trim() : undefined;
+        const repo = repoUrl ? resolveRepoSource({
+            provider: 'dbt', source: repoUrl.includes('gitlab') ? 'gitlab' : 'github', repoUrl, branch, subPath,
+        }, projectRoot) : undefined;
+        const projectDirInput = repo?.localPath ?? (typeof body.projectDir === 'string' ? body.projectDir : projectConfig.dbt?.projectDir ?? '.');
+        const dbtProjectDir = resolve(projectRoot, projectDirInput);
+        const manifestInput = typeof body.manifestPath === 'string' ? body.manifestPath : projectConfig.dbt?.manifestPath ?? 'target/manifest.json';
+        const manifestPath = resolve(dbtProjectDir, manifestInput);
+        if (!(manifestPath === dbtProjectDir || manifestPath.startsWith(`${dbtProjectDir}/`))) {
+            throw Object.assign(new Error('dbt manifestPath must stay inside dbt projectDir.'), { code: 'DBT_ARTIFACT_INVALID' });
+        }
+        const profilesDirInput = typeof body.profilesDir === 'string'
+            ? body.profilesDir
+            : projectConfig.dbt?.profilesDir;
+        const configuredProfilesDir = profilesDirInput ? resolve(projectRoot, profilesDirInput) : undefined;
+        const profilePath = findDbtProfilePaths(projectRoot, dbtProjectDir, configuredProfilesDir)[0];
+        const profilesDir = configuredProfilesDir ?? (profilePath ? dirname(profilePath) : undefined);
+        return { dbtProjectDir, manifestPath, projectDirInput, manifestInput, profilesDir, repoUrl, branch, subPath, repoWarnings: repo?.warnings ?? [] };
+    };
+    const previewDbtOnboarding = (body = {}) => {
+        const paths = onboardingDbtPaths(body);
+        if (!existsSync(join(paths.dbtProjectDir, 'dbt_project.yml')))
+            throw Object.assign(new Error('dbt_project.yml was not found.'), { code: 'DBT_PROJECT_NOT_FOUND' });
+        if (!existsSync(paths.manifestPath))
+            throw Object.assign(new Error(`dbt manifest is missing at ${paths.manifestPath}. Run dbt parse, then retry.`), { code: 'DBT_MANIFEST_MISSING' });
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(paths.manifestPath, 'utf8'));
+        }
+        catch (error) {
+            throw Object.assign(new Error(`dbt manifest is invalid: ${error instanceof Error ? error.message : String(error)}`), { code: 'DBT_ARTIFACT_INVALID' });
+        }
+        const fingerprint = createHash('sha256').update(readFileSync(paths.manifestPath)).digest('hex');
+        return {
+            projectDir: portableProjectPath(projectRoot, paths.dbtProjectDir),
+            manifestPath: relative(paths.dbtProjectDir, paths.manifestPath).replace(/\\/g, '/'),
+            ...(paths.profilesDir ? { profilesDir: portableProjectPath(projectRoot, paths.profilesDir) } : {}),
+            ...(paths.repoUrl ? { repoUrl: paths.repoUrl, branch: paths.branch, subPath: paths.subPath } : {}),
+            ...(paths.repoWarnings.length ? { warnings: paths.repoWarnings } : {}),
+            fingerprint,
+            projectName: typeof raw.metadata?.project_name === 'string' ? raw.metadata.project_name : undefined,
+            counts: {
+                models: Object.keys(raw.nodes ?? {}).filter((id) => id.startsWith('model.')).length,
+                sources: Object.keys(raw.sources ?? {}).length,
+                metrics: Object.keys(raw.metrics ?? {}).length,
+            },
+            artifacts: {
+                manifest: paths.manifestPath,
+                catalog: existsSync(join(dirname(paths.manifestPath), 'catalog.json')) ? join(dirname(paths.manifestPath), 'catalog.json') : null,
+                semanticManifest: existsSync(join(dirname(paths.manifestPath), 'semantic_manifest.json')) ? join(dirname(paths.manifestPath), 'semantic_manifest.json') : null,
+            },
+        };
+    };
+    const datasetWorkspace = new NotebookDatasetWorkspace(projectRoot, executor, connectorModuleSearchPaths(projectRoot));
+    let localWorkspaceReady = false;
+    const ensureLocalWorkspaceReady = async () => {
+        ensureConnectorInstalledForStartup(projectRoot, "duckdb");
+        if (!localWorkspaceReady) {
+            await datasetWorkspace.initialize();
+            localWorkspaceReady = true;
+        }
+        return datasetWorkspace.localConnection;
+    };
+    const resolveNamedConnection = (name) => {
+        if (!name)
+            return null;
+        const stored = getStoredConnections(projectConfig);
+        const normalized = normalizeStoredConnection(stored[name]);
+        return normalized
+            ? normalizeProjectConnection(normalized, projectRoot)
+            : null;
+    };
+    const resolveExecutionConnection = async (body) => {
+        const target = body.executionTarget && typeof body.executionTarget === "object"
+            ? body.executionTarget
+            : null;
+        if (target?.target === "local")
+            return ensureLocalWorkspaceReady();
+        if (target?.target === "connection" &&
+            typeof target.connectionName === "string") {
+            const named = resolveNamedConnection(target.connectionName);
+            if (!named)
+                throw new Error(`Connection not found: ${target.connectionName}`);
+            return named;
+        }
+        return requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
+    };
     const requireActiveConnection = (candidate = connection) => {
         if (!candidate) {
             throw new Error('No database connection is configured yet. Open Connections, add a warehouse or local DuckDB/file connection, then retry.');
@@ -382,6 +578,45 @@ export async function startLocalServer(opts) {
         }
     }
     await refreshLocalMetadataCatalog(projectRoot);
+    const recordDatasetMetadataSnapshot = (datasets = datasetWorkspace.list()) => {
+        if (datasets.length === 0)
+            return;
+        try {
+            recordRuntimeSchemaSnapshot(projectRoot, {
+                source: "notebook_local_datasets",
+                tables: datasets.map((dataset) => ({
+                    relation: dataset.alias,
+                    schema: "notebook_local",
+                    name: dataset.name,
+                    description: [
+                        dataset.description,
+                        `${dataset.storageMode} ${dataset.format} dataset`,
+                        `refreshed ${dataset.refreshedAt}`,
+                        `trust ${dataset.trustState}`,
+                    ]
+                        .filter(Boolean)
+                        .join(" · "),
+                    source: dataset.storageMode === "project"
+                        ? "project_dataset"
+                        : "local_dataset",
+                    columns: dataset.profile.columns.map((column) => ({
+                        name: column.name,
+                        type: column.type,
+                        description: column.flags?.length
+                            ? column.flags.join(", ")
+                            : undefined,
+                    })),
+                })),
+            });
+        }
+        catch {
+            // Dataset metadata improves retrieval but must never block notebook startup.
+        }
+    };
+    if (datasetWorkspace.list().length > 0) {
+        await ensureLocalWorkspaceReady().catch(() => undefined);
+        recordDatasetMetadataSnapshot();
+    }
     // Auto-register data/ CSV and Parquet files as DuckDB views so semantic layer
     // queries like `FROM orders` resolve without requiring read_csv_auto() in SQL.
     if (connection && (connection.driver === 'file' || connection.driver === 'duckdb')) {
@@ -509,6 +744,38 @@ export async function startLocalServer(opts) {
         return message;
     };
     const formatNotebookResearchStorageError = (error) => (formatAgentRunInfrastructureError(error, 'Notebook research storage'));
+    /**
+     * CTX-001 / SKILL-001 — Build surfaces receive the same server-resolved,
+     * snapshot-bound domain envelope and compact evidence pack as Ask. The pack
+     * is a retrieval boundary, never an authorization bypass.
+     */
+    const buildDirectBuildContext = async (input) => {
+        const snapshot = projectSnapshot();
+        const domainContext = resolveDomainContextEnvelope({
+            manifest: snapshot.manifest,
+            activeDomain: input.domain,
+            purpose: input.purpose,
+            modelAreaId: input.modelAreaId,
+            source: input.domain ? 'explicit_ui' : 'inferred',
+            snapshotId: snapshot.snapshotId,
+        });
+        const contextPack = await buildLocalContextPack(projectRoot, {
+            question: input.question,
+            mode: 'build',
+            surface: input.surface,
+            selectedContext: {
+                activeSurface: input.surface,
+                domain: input.domain,
+                purpose: input.purpose,
+                modelAreaId: input.modelAreaId,
+                ...input.selectedContext,
+            },
+            domainContext,
+            strictness: 'balanced',
+            limit: 120,
+        });
+        return { domainContext, contextPack };
+    };
     const buildAgentPromptArtifact = async (request, target, repair) => {
         try {
             await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
@@ -525,6 +792,17 @@ export async function startLocalServer(opts) {
         const prompt = isRepair
             ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}`
             : request.question;
+        const domain = target === 'block' ? agentRunWorkspaceValue(request, 'domain') : undefined;
+        const modelAreaId = agentRunWorkspaceValue(request, 'modelAreaId');
+        const purpose = agentRunWorkspaceValue(request, 'purpose');
+        const { domainContext, contextPack } = await buildDirectBuildContext({
+            question: prompt,
+            domain,
+            purpose,
+            modelAreaId,
+            surface: target === 'cell' ? 'notebook' : 'block',
+            selectedContext: { target, mode },
+        });
         return buildFromPrompt({
             projectRoot,
             prompt,
@@ -535,10 +813,16 @@ export async function startLocalServer(opts) {
             target,
             mode,
             blockPath: target === 'block'
-                ? agentRunWorkspaceValue(request, 'blockPath') ?? request.selectedObject?.path
+                ? agentRunWorkspaceValue(request, 'blockPath')
+                    ?? (request.selectedObject?.kind === 'block' && request.selectedObject.path?.endsWith('.dql')
+                        ? request.selectedObject.path
+                        : undefined)
                 : undefined,
             owner: agentRunWorkspaceValue(request, 'owner'),
-            domain: target === 'block' ? agentRunWorkspaceValue(request, 'domain') : undefined,
+            domain,
+            modelAreaId,
+            contextPack,
+            domainContext,
             userId: agentRunWorkspaceValue(request, 'userId'),
             skills,
             dbtManifestPath: resolveDbtManifestPath(projectRoot, projectConfig),
@@ -605,6 +889,9 @@ export async function startLocalServer(opts) {
                 'Prefer certified DQL blocks when they exactly cover the question.',
                 'Generated DQL artifacts remain review-required; SQL is only the bounded preview/compiled evidence.',
                 'If the question needs investigation, return the clearest answer and next review action without certifying generated work.',
+                ...(route === 'sql_cell'
+                    ? ['This is a notebook authoring fallback. Reuse certified blocks and semantic definitions as context, but return the requested row-level SQL cell rather than substituting a related aggregate answer.']
+                    : []),
                 ...(isRepair ? [`This is a repair attempt — fix the previous failure: ${repair?.repairHint}`] : []),
             ].join(' '),
         };
@@ -621,11 +908,28 @@ export async function startLocalServer(opts) {
         catch {
             semanticDriver = undefined;
         }
+        const requestedDomain = agentRunWorkspaceValue(request, 'domain');
+        const requestedPurpose = agentRunWorkspaceValue(request, 'purpose');
+        const requestedModelAreaId = agentRunWorkspaceValue(request, 'modelAreaId');
+        const runProjectSnapshot = projectSnapshot();
+        const domainContext = requestedDomain
+            ? resolveDomainContextEnvelope({
+                manifest: runProjectSnapshot.manifest,
+                activeDomain: requestedDomain,
+                purpose: requestedPurpose,
+                modelAreaId: requestedModelAreaId,
+                source: 'explicit_ui',
+                snapshotId: runProjectSnapshot.snapshotId,
+            })
+            : undefined;
         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 },
+                ...(isRepair
+                    ? [{ role: 'assistant', content: `The prior attempt needs repair without changing the original question or requested output grain: ${repair?.repairHint}` }]
+                    : []),
+                { role: 'user', content: request.question },
             ],
             conversationContext: request.conversationContext,
             upstream: {
@@ -635,6 +939,13 @@ export async function startLocalServer(opts) {
             reasoningEffort,
             ...(analysisDepth ? { analysisDepth } : {}),
             projectRoot,
+            domainContext,
+            projectSnapshot: { snapshotId: runProjectSnapshot.snapshotId, manifest: runProjectSnapshot.manifest },
+            assertProjectSnapshot: (snapshotId) => {
+                // Refresh the service from current source state before the final guard.
+                projectSnapshot();
+                projectSnapshots.assertCurrent(snapshotId);
+            },
             ...(semanticDriver ? { semanticDriver } : {}),
             executeCertifiedBlock: executeCertifiedBlockForAgent,
             executeGeneratedSql: executeGeneratedSqlForAgent,
@@ -736,7 +1047,71 @@ export async function startLocalServer(opts) {
             },
         ];
     }
-    const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit, emitAnswerDelta }) => {
+    /**
+     * PRD-001 / AGT-002 / AGT-006 / EXP-002 — every answer surface receives the
+     * same executable DQL artifact. Generated SQL is parameterized before the
+     * artifact leaves the runtime; it remains compiled evidence, not the primary
+     * user-facing object. Saving later persists this exact source without another
+     * model call.
+     */
+    function attachExecutableDqlArtifactContract(governedAnswer, question) {
+        const originalSql = governedAnswer.proposedSql?.trim() || governedAnswer.sql?.trim();
+        let artifact = governedAnswer.dqlArtifact;
+        if ((!artifact || artifact.kind === 'sql_block') && originalSql) {
+            const parameterized = parameterizeSqlForDqlImport(originalSql);
+            const artifactName = artifact?.name
+                ?? artifact?.source.match(/\bblock\s+"([^"]+)"/i)?.[1]
+                ?? deriveGeneratedDraftSlug(question);
+            const domain = artifact?.source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1] ?? 'uncategorized';
+            const source = candidateToDqlSource({
+                name: artifactName,
+                domain,
+                description: question,
+                owner: '',
+                tags: ['ai-generated', 'review-required'],
+                terms: [],
+                pattern: '',
+                grain: '',
+                entities: [],
+                outputs: [],
+                dimensions: [],
+                allowedFilters: parameterized.allowedFilters,
+                parameterPolicy: parameterized.parameterPolicy,
+                filterBindings: parameterized.filterBindings,
+                parameterDecisions: parameterized.parameterDecisions,
+                sourceSystems: [],
+                replacementFor: [],
+                reviewCadence: 'monthly',
+                sql: parameterized.sql,
+                llmContext: `Review-required DQL generated for: ${question}`,
+            });
+            artifact = {
+                ...(artifact ?? { kind: 'sql_block' }),
+                kind: 'sql_block',
+                name: artifactName,
+                source,
+            };
+        }
+        if (!artifact?.source)
+            return;
+        const invocation = prepareBlockInvocation({
+            source: artifact.source,
+            parameters: artifact.parameterValues,
+            question,
+            surface: 'ask_ai',
+        });
+        const certified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
+        const semantic = governedAnswer.route?.tier === 'semantic_metric';
+        governedAnswer.dqlArtifact = {
+            ...artifact,
+            ...(invocation.parameters.length > 0 ? { parameters: invocation.parameters } : {}),
+            ...(Object.keys(invocation.values).length > 0 ? { parameterValues: invocation.values } : {}),
+            persistence: artifact.sourcePath ? 'saved' : 'transient',
+            trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
+            ...(originalSql ? { compiledSql: originalSql } : {}),
+        };
+    }
+    const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit }) => {
         let governedAnswer;
         try {
             governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route, (message) => emit({ type: 'executor.started', message, route }));
@@ -745,6 +1120,126 @@ export async function startLocalServer(opts) {
             if (!governedAnswer.appliedHints) {
                 governedAnswer.appliedHints = governedAnswer.contextPack?.appliedHints;
             }
+            // EXP-001 — a missing modeled relationship is not the same as an unsafe
+            // relationship. The answer loop exposes a non-executed candidate only for
+            // that narrow case; the host owns bounded probe/execution and never
+            // weakens the final governed-SQL guard.
+            if (governedAnswer.exploratoryCandidate) {
+                const explorationSchema = governedAnswer.contextPack?.allowedSqlContext.relations.map((table) => ({
+                    relation: table.relation,
+                    name: table.name,
+                    columns: table.columns.map((column) => ({ ...column })),
+                    source: table.source,
+                }))
+                    ?? governedAnswer.analysisPlan?.candidateTables.map((table) => ({
+                        relation: table.relation,
+                        name: table.relation.split('.').at(-1) ?? table.relation,
+                        columns: table.columns.map((name) => ({ name })),
+                        source: 'answer analysis plan',
+                    }));
+                const exploration = await executeExploratoryCandidate(governedAnswer.exploratoryCandidate, explorationSchema, request.question, governedAnswer.contextPack?.questionPlan.requestedShape.topN?.scope === 'overall'
+                    ? governedAnswer.contextPack.questionPlan.requestedShape.topN.n
+                    : undefined);
+                const probeSummary = exploration.proofs.length > 0
+                    ? `${exploration.proofs.length} bounded join probe${exploration.proofs.length === 1 ? '' : 's'} completed.`
+                    : 'No join probe was required for this query.';
+                const baseWarnings = governedAnswer.validationWarnings ?? [];
+                const evidence = governedAnswer.evidence ?? {
+                    route: [], lineage: [], businessContext: [], selectedAssets: [], sourceTables: [], semanticObjects: [], citations: [],
+                };
+                governedAnswer.evidence = evidence;
+                evidence.route.push({
+                    tool: 'explore_dbt_grounded_sql',
+                    status: exploration.result ? 'checked' : 'failed',
+                    label: exploration.result ? 'Executed bounded DBT-grounded exploration' : 'DBT-grounded exploration could not execute',
+                    detail: exploration.error ?? probeSummary,
+                });
+                if (exploration.proofs.length > 0) {
+                    evidence.businessContext.push({
+                        label: 'Exploratory join probes',
+                        value: exploration.proofs.map((proof) => proof.summary).join('; '),
+                        source: 'bounded DBT-grounded validation',
+                    });
+                }
+                if (exploration.result) {
+                    evidence.route = [
+                        ...cascadeTraceToEvidenceRouteSteps(createCascadeTrace({ terminalLane: 'generated' })),
+                        ...evidence.route.filter((step) => !step.tool.startsWith('cascade_')),
+                    ];
+                    evidence.validation = {
+                        status: 'warning',
+                        message: 'The bounded DBT-grounded query executed successfully, but its inferred relationship path still requires analyst review before reuse.',
+                    };
+                    evidence.execution = {
+                        status: 'executed',
+                        message: 'Executed the bounded DBT-grounded exploratory SQL preview.',
+                        rowCount: exploration.result.rowCount,
+                        executionTime: exploration.result.executionTime,
+                    };
+                }
+                const repairedExploratoryCandidate = exploration.sql !== governedAnswer.exploratoryCandidate.sql
+                    ? { ...governedAnswer.exploratoryCandidate, sql: exploration.sql }
+                    : governedAnswer.exploratoryCandidate;
+                const lifetimeGrainRepair = exploration.repairs.find((repair) => repair.startsWith('Used lifetime_'));
+                const explorationAnswer = exploration.result
+                    ? lifetimeGrainRepair
+                        ? `Exploratory DBT-grounded query executed and returned ${exploration.result.rowCount} row${exploration.result.rowCount === 1 ? '' : 's'}. Each row is an owning-entity and joined-dimension pair. The lifetime measure remains an entity-level attribute repeated across that dimension; it is not allocated to the joined dimension. ${lifetimeGrainRepair}`
+                        : `Exploratory DBT-grounded query executed and returned ${exploration.result.rowCount} row${exploration.result.rowCount === 1 ? '' : 's'}. Review the inferred join evidence before reusing this analysis.`
+                    : `DQL found a DBT-grounded exploratory path, but the bounded validation could not run: ${exploration.error ?? 'unknown execution error'}.`;
+                governedAnswer = {
+                    ...governedAnswer,
+                    kind: 'uncertified',
+                    sourceTier: 'dbt_manifest',
+                    certification: 'analyst_review_required',
+                    reviewStatus: 'analyst_review_required',
+                    confidence: exploration.result ? 0.58 : 0.2,
+                    ...(exploration.result ? {
+                        refusalCode: undefined,
+                        refusalDetails: undefined,
+                        intentDecision: {
+                            ...governedAnswer.intentDecision,
+                            action: 'answer',
+                            confidence: Math.max(governedAnswer.intentDecision?.confidence ?? 0, 0.9),
+                            reason: 'Executed a bounded DBT-grounded exploratory answer after certified and semantic routes did not fully cover the request.',
+                            clarifyingQuestion: undefined,
+                            clarifySoft: undefined,
+                            followsUp: governedAnswer.intentDecision?.followsUp ?? false,
+                        },
+                    } : {}),
+                    result: exploration.result,
+                    proposedSql: exploration.sql,
+                    sql: exploration.sql,
+                    exploratoryCandidate: repairedExploratoryCandidate,
+                    executionError: exploration.error,
+                    text: explorationAnswer,
+                    answer: explorationAnswer,
+                    trustLabel: 'Exploratory · DBT-grounded',
+                    contextPackId: governedAnswer.contextPackId ?? governedAnswer.contextPack?.id,
+                    route: {
+                        tier: 'generated_sql',
+                        label: exploration.result
+                            ? 'Exploratory · DBT-grounded answer (review required).'
+                            : 'Exploratory · DBT-grounded query needs review before execution.',
+                    },
+                    cascade: exploration.result
+                        ? createCascadeAnswerResult({
+                            routeTier: 'generated_sql',
+                            label: 'Exploratory DBT-grounded answer executed with review required.',
+                            artifactKind: 'dbt_grounded_exploration',
+                            hasSqlPreview: true,
+                            executionStatus: 'executed',
+                            rowCount: exploration.result.rowCount,
+                        })
+                        : governedAnswer.cascade,
+                    validationWarnings: [
+                        ...baseWarnings,
+                        probeSummary,
+                        ...exploration.repairs,
+                        ...(exploration.error ? [`Exploratory execution: ${exploration.error}`] : []),
+                    ],
+                };
+            }
+            attachExecutableDqlArtifactContract(governedAnswer, request.question);
             applySmartVisualization(governedAnswer, request.question);
         }
         catch (error) {
@@ -767,8 +1262,21 @@ export async function startLocalServer(opts) {
         const resolvedRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
         const isSemantic = governedAnswer.route?.tier === 'semantic_metric';
-        const isGroundingGap = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'grounding_gap';
+        const requestedNotebookDataset = findMentionedNotebookDataset(request.question, datasetWorkspace.list());
+        const governedAssetMissesLocalSource = Boolean(requestedNotebookDataset && (isCertified
+            || isSemantic
+            || governedAnswer.sourceCertifiedBlock
+            || governedAnswer.dqlArtifact?.kind === 'certified_block'));
+        const isExploratory = Boolean(governedAnswer.exploratoryCandidate);
+        const isGroundingGap = governedAnswer.kind === 'no_answer'
+            && governedAnswer.refusalCode === 'grounding_gap'
+            && !isExploratory;
         const isProviderError = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'provider_error';
+        // AGT-004: a rejected attribution/export/proof policy is a deliberate
+        // governance boundary, not an ambiguous user question and not a repairable
+        // retrieval miss. Keep the precise policy detail visible, but never burn two
+        // more provider calls retrying the same incompatible candidate.
+        const isPolicyBlocked = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'policy_blocked';
         // The model tried to compose a governed query and declined despite having usable
         // context (e.g. it wasn't confident about a multi-table join). That is NOT a
         // question for the USER to clarify — it's a case to retry harder: escalate to a
@@ -783,9 +1291,11 @@ export async function startLocalServer(opts) {
         // grounding gap or a model decline is retried/escalated by the engine, and a
         // provider outage is surfaced as blocked so the UI offers a retry.
         const needsClarification = governedAnswer.kind === 'no_answer'
-            && !isGroundingGap && !isProviderError && !isModelDeclined;
+            && !isGroundingGap && !isProviderError && !isModelDeclined && !isPolicyBlocked;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
-        const runnableSql = governedAnswer.kind === 'no_answer' ? undefined : sql;
+        const runnableSql = governedAnswer.kind === 'no_answer' || (isExploratory && !governedAnswer.result)
+            ? undefined
+            : sql;
         // Synthesis is a legacy polish pass. Certified/no-answer paths and lanes
         // that already produced DQL-first final prose keep the fast path.
         let synthesizedAnswer;
@@ -798,13 +1308,14 @@ export async function startLocalServer(opts) {
                     const result = await synthesizeAnswer({
                         question: request.question,
                         category: routeDecision?.category,
-                        audience: request.audience ?? 'analyst',
+                        // The primary Ask reply is always business-facing. Analysts keep
+                        // the full DQL, SQL, lineage, gates, and grain in the inspector.
+                        audience: 'stakeholder',
                         resultPreview: preview,
                         sql: sql,
                         draftText: draft,
-                        gaps: governedAnswer.validationWarnings,
+                        gaps: businessNarrativeGaps(governedAnswer.validationWarnings),
                     }, {
-                        onDelta: emitAnswerDelta,
                         complete: ({ system, user, signal, onDelta }) => streamOrGenerate(provider, [{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 350, temperature: 0.3, signal }, onDelta ?? (() => { })),
                     });
                     if (result.text)
@@ -846,13 +1357,18 @@ export async function startLocalServer(opts) {
             : [
                 { id: 'create-block', label: governedAnswer.dqlArtifact ? 'Review DQL draft' : 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
                 { id: 'research-gap', label: 'Research deeper', route: 'research' },
-                ...(runnableSql ? [{ id: 'insert-sql', label: 'Insert SQL preview', route: 'sql_cell', artifactKind: 'sql_cell' }] : []),
+                ...(runnableSql ? [{
+                        id: 'insert-sql',
+                        label: governedAnswer.dqlArtifact ? 'Insert as DQL cell' : 'Insert SQL preview',
+                        route: 'sql_cell',
+                        artifactKind: 'sql_cell',
+                    }] : []),
             ];
         return {
             resolvedRoute,
             answerRefusalCode: governedAnswer.kind === 'no_answer' ? governedAnswer.refusalCode : undefined,
             answerTier: governedAnswer.route?.tier,
-            summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : 'Answered with review-required generated analysis.'),
+            summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : isExploratory ? 'Exploratory DBT-grounded analysis requires review.' : 'Answered with review-required generated analysis.'),
             answer: synthesizedAnswer ?? governedAnswer.answer ?? governedAnswer.text,
             status,
             trustState,
@@ -864,20 +1380,35 @@ export async function startLocalServer(opts) {
                 ? (governedAnswer.dqlArtifact && !isProviderError
                     ? [agentRunArtifact('dql_block_draft', 'DQL draft (review required)', governedAnswer.dqlArtifact, undefined, 'review_required')]
                     : [])
-                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : isSemantic ? 'Governed semantic answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : isSemantic ? 'governed' : 'review_required')],
+                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : isSemantic ? 'Governed semantic answer' : isExploratory ? 'Exploratory DBT-grounded answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : isSemantic ? 'governed' : 'review_required')],
             evaluations: [
                 agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.', {
                     plannedRoute: route,
                     resolvedRoute,
                     aiRoute: governedAnswer.route,
                 }),
+                ...(governedAssetMissesLocalSource ? [
+                    {
+                        ...agentRunEvaluation('requested-local-source', 'Requested local dataset', false, 'warning', `${requestedNotebookDataset.alias} was explicitly requested, but the governed answer did not use local data. Reuse its governed logic only as context and build the mixed-source SQL fallback.`, { datasetId: requestedNotebookDataset.id, alias: requestedNotebookDataset.alias }),
+                        suggestedRepair: `Build a notebook SQL fallback that combines the requested ${requestedNotebookDataset.alias} dataset with the required warehouse extraction.`,
+                        repairAction: {
+                            kind: 'escalate',
+                            route: 'sql_cell',
+                            hint: `The certified or semantic result is not exact because it omits the explicitly requested local dataset ${requestedNotebookDataset.alias}. Author the warehouse extraction and mixed-source notebook handoff.`,
+                        },
+                    },
+                ] : []),
                 agentRunEvaluation('trust-boundary', 'Trust boundary', isCertified || isSemantic, isCertified || isSemantic ? 'info' : 'warning', isCertified
                     ? 'The answer came from certified DQL context.'
                     : isSemantic
                         ? 'The answer was compiled and executed from governed semantic definitions; it is not a human-certified reusable block.'
                         : 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),
+                            : isPolicyBlocked
+                                ? `DQL blocked the generated path under its relationship policy: ${governedAnswer.refusalDetails?.message ?? 'the relationship is not authorized for this analysis.'}`
+                                : isExploratory
+                                    ? 'The answer used bounded DBT/schema evidence because no certified modeled relationship path covered the request. It is review-required and was not certified.'
+                                    : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
                 ...(isGroundingGap ? [
                     {
                         ...agentRunEvaluation('grounding-gap', 'Metadata grounding', false, 'warning', 'The answer loop found a metadata grounding gap that can be retried with wider context.', {
@@ -902,6 +1433,15 @@ export async function startLocalServer(opts) {
                         repairAction: { kind: 'escalate', route: 'research', hint: declinedRepairHint },
                     },
                 ] : []),
+                ...(isPolicyBlocked ? [
+                    agentRunEvaluation('relationship-policy', 'Relationship policy', false, 'warning', governedAnswer.refusalDetails?.message
+                        ?? 'The selected relationship is not authorized for this analysis.', {
+                        refusalCode: governedAnswer.refusalCode,
+                        refusalDetails: governedAnswer.refusalDetails,
+                        validationWarnings: governedAnswer.validationWarnings,
+                        route: governedAnswer.route,
+                    }),
+                ] : []),
                 ...(governedAnswer.executionError ? [
                     agentRunEvaluation('execution-error', 'Execution error', false, 'warning', governedAnswer.executionError),
                 ] : []),
@@ -1138,33 +1678,112 @@ export async function startLocalServer(opts) {
             };
         },
         sql_cell: async ({ request, routeDecision, attempt, repairHint }) => {
+            const selectedCellSql = agentRunWorkspaceValue(request, 'cellSql');
+            const mixedSourcePlan = selectedCellSql
+                ? planMixedSourceSql(selectedCellSql, datasetWorkspace.list().map((dataset) => dataset.alias))
+                : null;
+            if (mixedSourcePlan) {
+                const explanation = [
+                    `The original query directly joined warehouse data with the local dataset ${mixedSourcePlan.localDataset}. Those sources execute in different engines, so the CSV is not a missing dbt table.`,
+                    `I prepared the warehouse-only extraction and retained ${mixedSourcePlan.warehouseKey}, the key needed to join with ${mixedSourcePlan.localDataset}.${mixedSourcePlan.localKey}.`,
+                    'Insert and run this SQL on the warehouse connection. On its result, choose Combine with local data, select the local dataset, and confirm the suggested keys. The final mixed result runs locally and remains review-required.',
+                ].join(' ');
+                const result = {
+                    target: 'cell',
+                    sql: mixedSourcePlan.warehouseSql,
+                    explanation,
+                    mixedSourcePlan,
+                };
+                return {
+                    summary: `Prepared a warehouse extraction for local combination with ${mixedSourcePlan.localDataset}.`,
+                    answer: explanation,
+                    artifacts: [agentRunArtifact('sql_cell', 'Warehouse extraction for local analysis', result)],
+                    evaluations: [
+                        agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Detected a mixed local and warehouse SQL repair.'),
+                        agentRunEvaluation('mixed-source-boundary', 'Mixed-source boundary', true, 'warning', 'No direct cross-engine join was executed. The user must explicitly stage the bounded warehouse result.'),
+                    ],
+                    nextActions: [{ id: 'insert-sql', label: 'Insert warehouse extraction', artifactKind: 'sql_cell' }],
+                };
+            }
+            const requestedNotebookDataset = findMentionedNotebookDataset(request.question, datasetWorkspace.list());
+            const authoringRequest = requestedNotebookDataset
+                ? {
+                    ...request,
+                    question: [
+                        request.question,
+                        '',
+                        `Notebook SQL fallback contract: ${requestedNotebookDataset.alias} is a local dataset, not a warehouse table. Produce the warehouse-only row-level extraction needed for the requested analysis. Include the warehouse join key that corresponds to the local dataset identifier, plus the requested order/detail columns. Do not return an aggregate certified answer and do not reference ${requestedNotebookDataset.alias} in the warehouse SQL. The UI will stage this bounded result and create the local join cell after confirmation.`,
+                    ].join('\n'),
+                }
+                : request;
             // P4: route Notebook SQL-cell generation through the SAME tool-rich governed
             // pipeline Ask AI uses (schema-discovery tools P3 + declined-retry P1 + budget
             // recovery P2), instead of the tool-less buildFromPrompt path. A SQL cell only
             // needs the SQL, which the governed answer produces directly as proposedSql.
-            const governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt: attempt ?? 0, repairHint });
-            const sql = governedAnswer.proposedSql ?? governedAnswer.sql ?? '';
+            const governedAnswer = await runGovernedAgentAnswerForRun(authoringRequest, { attempt: attempt ?? 0, repairHint }, 'sql_cell');
+            attachExecutableDqlArtifactContract(governedAnswer, request.question);
+            const schemaContext = requestedNotebookDataset
+                ? await getSchemaContextForAgent(request.question)
+                : [];
+            const generatedSql = governedAnswer.proposedSql ?? governedAnswer.sql ?? '';
+            const generatedPlan = requestedNotebookDataset && generatedSql.trim()
+                ? planMixedSourceNotebookSql(generatedSql, {
+                    id: requestedNotebookDataset.id,
+                    name: requestedNotebookDataset.name,
+                    alias: requestedNotebookDataset.alias,
+                    columns: requestedNotebookDataset.profile.columns.map((column) => ({
+                        name: column.name,
+                        flags: column.flags,
+                    })),
+                }, schemaContext)
+                : null;
+            const generatedReusedNonExactAsset = Boolean(governedAnswer.sourceCertifiedBlock || governedAnswer.dqlArtifact?.kind === 'certified_block');
+            const fallbackSql = requestedNotebookDataset && (generatedReusedNonExactAsset || !generatedSql.trim())
+                ? buildMixedSourceWarehouseFallbackSql(request.question, {
+                    id: requestedNotebookDataset.id,
+                    name: requestedNotebookDataset.name,
+                    alias: requestedNotebookDataset.alias,
+                    columns: requestedNotebookDataset.profile.columns.map((column) => ({ name: column.name, flags: column.flags })),
+                }, schemaContext)
+                : undefined;
+            const naturalMixedSourcePlan = requestedNotebookDataset && fallbackSql
+                ? planMixedSourceNotebookSql(fallbackSql, {
+                    id: requestedNotebookDataset.id,
+                    name: requestedNotebookDataset.name,
+                    alias: requestedNotebookDataset.alias,
+                    columns: requestedNotebookDataset.profile.columns.map((column) => ({ name: column.name, flags: column.flags })),
+                }, schemaContext)
+                : generatedPlan;
+            const sql = naturalMixedSourcePlan?.warehouseSql ?? generatedSql;
             const explanation = governedAnswer.answer ?? governedAnswer.text;
             const hasSql = Boolean(sql.trim());
             // Preserve the BuildCellResult shape the notebook UI already consumes.
             const result = {
                 target: 'cell',
                 sql,
-                explanation,
+                explanation: naturalMixedSourcePlan
+                    ? `No certified block or semantic result exactly covered all requested sources. The workflow combines ${naturalMixedSourcePlan.warehouseRelations?.join(', ') || 'the requested warehouse tables'} in one bounded warehouse extraction, then joins it locally with ${naturalMixedSourcePlan.localDataset} on ${naturalMixedSourcePlan.warehouseKey} = ${naturalMixedSourcePlan.localKey}. Click Add workflow to notebook below to create the cells. The mixed result remains review-required.`
+                    : explanation,
+                ...(naturalMixedSourcePlan ? { mixedSourcePlan: naturalMixedSourcePlan } : {}),
+                ...(!naturalMixedSourcePlan && governedAnswer.dqlArtifact ? { dqlArtifact: governedAnswer.dqlArtifact } : {}),
                 ...(governedAnswer.appliedSkills ? { appliedSkills: governedAnswer.appliedSkills } : {}),
             };
             return {
                 summary: hasSql
-                    ? 'Created a review-required SQL cell draft.'
+                    ? naturalMixedSourcePlan
+                        ? `Prepared a mixed-source notebook workflow using ${naturalMixedSourcePlan.localDataset}.`
+                        : 'Created a review-required DQL query cell.'
                     : (explanation || 'No SQL could be generated for this request.'),
-                answer: explanation,
-                artifacts: [agentRunArtifact('sql_cell', 'Generated SQL cell', result)],
+                answer: result.explanation,
+                artifacts: [agentRunArtifact('sql_cell', naturalMixedSourcePlan ? 'Warehouse extraction for local analysis' : 'Generated DQL query 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.'),
+                    agentRunEvaluation('review-boundary', 'Review boundary', true, 'warning', naturalMixedSourcePlan
+                        ? 'The warehouse extraction is staged with limits and the CSV join runs locally. Mixed-source output is never auto-certified.'
+                        : 'Generated DQL and its compiled SQL evidence must be reviewed before certification.'),
                 ],
-                nextActions: [
-                    { id: 'insert-sql', label: 'Insert SQL preview', artifactKind: 'sql_cell' },
+                nextActions: naturalMixedSourcePlan ? [] : [
+                    { id: 'insert-sql', label: governedAnswer.dqlArtifact ? 'Insert as DQL cell' : 'Insert SQL preview', artifactKind: 'sql_cell' },
                     { id: 'create-block', label: 'Review as DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
                 ],
             };
@@ -1302,17 +1921,19 @@ export async function startLocalServer(opts) {
             // A real app needs a certified anchor: only offer confirmation when at least
             // one certified tile is present. Otherwise fall through to the escalate path
             // (research / draft the missing blocks) so the user isn't sent to a dead end.
-            const proposed = Boolean(proposal && proposal.tiles.some((tile) => tile.certification === 'certified' && !tile.error));
+            const proposed = Boolean(proposal && proposal.tiles.some((tile) => (tile.certification === 'certified' || tile.certification === 'reviewed_semantic') && !tile.error));
             const sessionPlan = agentRunRecord(session.plan);
             const appTitle = agentRunString(sessionPlan?.name) ?? 'App proposal';
             const certifiedCount = proposal?.coverage.certifiedTiles ?? 0;
             const generatedCount = proposal?.coverage.generatedTiles ?? 0;
+            const semanticCount = proposal?.coverage.semanticTiles ?? 0;
             const gapCount = proposal?.coverage.gaps ?? 0;
             // 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: proposed
                     ? `Proposed ${certifiedCount} certified tile${certifiedCount === 1 ? '' : 's'}`
+                        + (semanticCount > 0 ? ` + ${semanticCount} reviewed semantic tile${semanticCount === 1 ? '' : 's'}` : '')
                         + (generatedCount > 0 ? ` + ${generatedCount} AI-generated (review required)` : '')
                         + (gapCount > 0 ? `; ${gapCount} question${gapCount === 1 ? '' : 's'} still uncovered` : '')
                         + '. Review the list and confirm to create the app.'
@@ -1326,6 +1947,7 @@ export async function startLocalServer(opts) {
                         dashboardId: session.dashboardId,
                         plan: session.plan,
                         proposal,
+                        proposalHash: session.proposalHash,
                         warnings: session.warnings,
                     }, session.appId)] : [],
                 evaluations: [
@@ -1519,19 +2141,21 @@ export async function startLocalServer(opts) {
             cells: snapshotCells,
         });
     };
-    const executeCertifiedBlockForAgent = async (node) => {
-        if (node.kind !== 'block') {
-            throw new Error(`Certified ${node.kind} "${node.name}" is a navigation artifact and cannot be executed as a block.`);
-        }
-        const manifest = buildManifest({ projectRoot });
-        const block = manifest.blocks[node.name] ?? manifest.blocks[node.nodeId.replace(/^block:/, '')];
-        if (!block) {
-            throw new Error(`Matched block "${node.name}" is not present in the project manifest.`);
+    const executeDqlArtifactSourceForAgent = async (source, metadata = {}, invocationInput) => {
+        const invocation = prepareBlockInvocation({
+            source,
+            parameters: invocationInput?.parameters,
+            question: invocationInput?.question,
+            surface: 'ask_ai',
+        });
+        if (invocation.errors.length > 0)
+            throw new Error(invocation.errors.join(' '));
+        if (invocation.unresolvedParameters.length > 0) {
+            throw new Error(`I need values for: ${invocation.unresolvedParameters.join(', ')}.`);
         }
-        const absBlockPath = join(projectRoot, block.filePath);
-        const source = readFileSync(absBlockPath, 'utf-8');
         const activeConnection = requireActiveConnection();
         const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+        const plan = buildExecutionPlan({ id: `agent-${metadata.name ?? 'dql-artifact'}`, type: 'dql', source, title: metadata.name ?? 'DQL artifact' }, { semanticLayer, driver: activeConnection.driver, tableMapping, parameters: invocation.values });
         const semanticCompose = semanticLayer
             ? composeSemanticBlockSql(source, semanticLayer, {
                 driver: activeConnection.driver,
@@ -1539,29 +2163,55 @@ export async function startLocalServer(opts) {
                 projectRoot,
                 projectConfig,
                 detectedProvider: semanticDetectedProvider,
+                parameters: invocation.values,
             })
             : null;
-        const plan = buildExecutionPlan({ id: `agent-${block.name}`, type: 'dql', source, title: block.name }, { semanticLayer, driver: activeConnection.driver, tableMapping });
         if (!plan && !semanticCompose?.sql) {
             const semanticError = semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message;
-            throw new Error(semanticError ?? `Block "${block.name}" produced no executable SQL.`);
+            throw new Error(semanticError ?? `DQL artifact "${metadata.name ?? 'draft'}" produced no executable SQL.`);
         }
         const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, activeConnection, projectRoot, projectConfig);
         const app = loadRuntimeApp(projectRoot, activePersonaAppId());
-        assertAppAccess({ app, domain: block.domain ?? app?.domain, level: 'execute' });
-        const rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), prepared.connection);
+        const sourceDomain = metadata.domain ?? source.match(/\bdomain\s*=\s*"([^"]+)"/i)?.[1];
+        assertAppAccess({ app, domain: sourceDomain ?? app?.domain, level: 'execute' });
+        const rawResult = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
         const normalized = normalizeQueryResult(rawResult);
         return {
             columns: normalized.columns,
             rows: normalized.rows,
             rowCount: normalized.rowCount,
             executionTime: normalized.executionTime,
-            chartConfig: plan?.chartConfig ?? (block.chartType ? { chart: block.chartType } : undefined),
+            chartConfig: plan?.chartConfig ?? (metadata.chartType ? { chart: metadata.chartType } : undefined),
             sql: prepared.sql,
-            blockName: block.name,
-            blockPath: block.filePath,
+            ...(metadata.name ? { blockName: metadata.name } : {}),
+            ...(metadata.path ? { blockPath: metadata.path } : {}),
+            parameters: invocation.resolvedParameters,
+            auditId: invocation.auditId,
         };
     };
+    const executeCertifiedBlockByNameForAgent = async (blockName, invocationInput, requireCertified = false) => {
+        const manifest = buildManifest({ projectRoot });
+        const block = manifest.blocks[blockName];
+        if (!block) {
+            throw new Error(`Matched block "${blockName}" is not present in the project manifest.`);
+        }
+        if (requireCertified && block.status !== 'certified') {
+            throw new Error(`Block "${block.name}" is not certified and cannot be rerun as a certified answer.`);
+        }
+        const source = readFileSync(join(projectRoot, block.filePath), 'utf-8');
+        return executeDqlArtifactSourceForAgent(source, {
+            name: block.name,
+            path: block.filePath,
+            domain: block.domain,
+            chartType: block.chartType,
+        }, invocationInput);
+    };
+    const executeCertifiedBlockForAgent = async (node, invocationInput) => {
+        if (node.kind !== 'block') {
+            throw new Error(`Certified ${node.kind} "${node.name}" is a navigation artifact and cannot be executed as a block.`);
+        }
+        return executeCertifiedBlockByNameForAgent(node.name || node.nodeId.replace(/^block:/, ''), invocationInput);
+    };
     const executeGeneratedSqlForAgent = async (sql) => {
         const activeConnection = requireActiveConnection();
         const boundedSql = buildAgentPreviewSql(sql);
@@ -1582,6 +2232,62 @@ export async function startLocalServer(opts) {
             sql: prepared.sql,
         };
     };
+    /**
+     * EXP-001: execution host for the deliberately narrow non-governed lane.
+     * It does not reinterpret dbt lineage or shared names as relationship proof.
+     * Instead it validates the generated equality predicates against bounded
+     * samples, records the result as exploratory evidence, then executes the
+     * existing read-only 200-row preview. Any malformed, broad, or unsupported
+     * candidate remains review-required and is not executed automatically.
+     */
+    const executeExploratoryCandidate = async (candidate, schemaContext = [], question = '', requestedTopN) => {
+        const preflight = repairExploratorySqlBeforeExecution(candidate.sql, schemaContext, question);
+        const boundedSql = applyRequestedTopNToExploratorySql(preflight.sql, requestedTopN);
+        const repairs = boundedSql === preflight.sql
+            ? preflight.repairs
+            : [...preflight.repairs, `Applied the requested overall top-${requestedTopN} bound before exploratory execution.`];
+        if (preflight.blockedReason) {
+            return {
+                proofs: [],
+                sql: boundedSql,
+                repairs,
+                error: preflight.blockedReason,
+            };
+        }
+        const analysis = analyzeSqlReferences(boundedSql);
+        if (!analysis.parsed) {
+            return { proofs: [], sql: boundedSql, repairs, error: 'DQL could not parse the exploratory SQL to validate its join predicates.' };
+        }
+        // A normal customer → order → order-item → product question needs three
+        // joins. Keep the lane bounded, but do not reject this common dbt-star path
+        // solely because the old two-join demo limit was too small.
+        if (analysis.joins.length > 4) {
+            return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has more than four joins and requires an analyst to review the relationship path.' };
+        }
+        if (analysis.joins.some((join) => !join.leftRelation || !join.rightRelation)) {
+            return { proofs: [], sql: boundedSql, repairs, error: 'This exploratory query has a join endpoint DQL could not resolve for bounded validation.' };
+        }
+        const activeConnection = requireActiveConnection();
+        const proofs = [];
+        try {
+            for (const join of analysis.joins) {
+                const proofSql = buildExploratoryJoinProbeSql({
+                    leftRelation: join.leftRelation,
+                    leftColumn: join.leftColumn,
+                    rightRelation: join.rightRelation,
+                    rightColumn: join.rightColumn,
+                });
+                const prepared = prepareLocalExecution(proofSql, activeConnection, projectRoot, projectConfig);
+                const raw = await executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
+                proofs.push({ summary: summarizeExploratoryJoinProbe(raw.rows, join.leftRelation, join.leftColumn, join.rightRelation, join.rightColumn) });
+            }
+            const result = await executeGeneratedSqlForAgent(boundedSql);
+            return { result, proofs, sql: boundedSql, repairs };
+        }
+        catch (error) {
+            return { proofs, sql: boundedSql, repairs, error: error instanceof Error ? error.message : String(error) };
+        }
+    };
     const getSchemaContextForAgent = async (question, preparedContextPack) => {
         const scanRuntimeSchema = async () => {
             if (!connection)
@@ -1603,7 +2309,7 @@ export async function startLocalServer(opts) {
             // Rescan live when the question shape calls for it OR the stored snapshot is
             // stale/absent (P6) — otherwise a warehouse schema change between sessions is
             // silently reasoned over from a cached snapshot that never expires.
-            const runtimeScan = (shouldAugmentAgentRuntimeSchema(question) || runtimeSnapshotStale(projectRoot))
+            const runtimeScan = (shouldAugmentAgentRuntimeSchema(question, preparedContextPack?.questionPlan) || runtimeSnapshotStale(projectRoot))
                 ? await scanRuntimeSchema().catch(() => undefined)
                 : undefined;
             const runtimeContext = runtimeScan?.ranked ?? [];
@@ -2286,14 +2992,16 @@ export async function startLocalServer(opts) {
     });
     // SSE clients for /api/watch hot-reload
     const sseClients = new Set();
-    // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
+    // Watch all Git-owned authoring roots. Domain Packages are recursive and are
+    // the canonical home for modeling, skills, blocks, notebooks, Apps, and evals.
     if (projectRoot) {
-        for (const dir of ['notebooks', 'workbooks', 'blocks', 'dashboards', 'semantic-layer', 'data']) {
+        let sourceRefreshTimer;
+        for (const dir of ['domains', 'skills', 'tests', 'notebooks', 'workbooks', 'blocks', 'apps', 'dashboards', 'semantic-layer', 'data']) {
             const watchDir = join(projectRoot, dir);
             if (!existsSync(watchDir))
                 continue;
             try {
-                watch(watchDir, { persistent: false }, (eventType, filename) => {
+                watch(watchDir, { persistent: false, recursive: true }, (eventType, filename) => {
                     if (!filename)
                         return;
                     const path = `${dir}/${filename}`;
@@ -2306,6 +3014,14 @@ export async function startLocalServer(opts) {
                             sseClients.delete(client);
                         }
                     }
+                    if (['domains', 'skills', 'tests', 'blocks', 'apps', 'notebooks'].includes(dir)) {
+                        invalidateAgentProjectState(projectRoot);
+                        if (sourceRefreshTimer)
+                            clearTimeout(sourceRefreshTimer);
+                        sourceRefreshTimer = setTimeout(() => {
+                            void refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
+                        }, 250);
+                    }
                     // Hot-reload semantic layer on change and notify frontend
                     if (dir === 'semantic-layer') {
                         const semanticConnection = connection;
@@ -2338,6 +3054,31 @@ export async function startLocalServer(opts) {
             }
             catch { /* dir not watchable */ }
         }
+        const configuredDbtManifest = resolveDbtManifestPath(projectRoot);
+        if (configuredDbtManifest && existsSync(dirname(configuredDbtManifest))) {
+            try {
+                watch(dirname(configuredDbtManifest), { persistent: false }, (_eventType, filename) => {
+                    if (!filename || !['manifest.json', 'catalog.json', 'semantic_manifest.json', 'run_results.json'].includes(String(filename)))
+                        return;
+                    invalidateAgentProjectState(projectRoot);
+                    if (sourceRefreshTimer)
+                        clearTimeout(sourceRefreshTimer);
+                    sourceRefreshTimer = setTimeout(() => {
+                        void refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
+                    }, 250);
+                    const payload = JSON.stringify({ type: 'dbt-artifacts-changed', path: String(filename) });
+                    for (const client of sseClients) {
+                        try {
+                            client.write(`event: change\ndata: ${payload}\n\n`);
+                        }
+                        catch {
+                            sseClients.delete(client);
+                        }
+                    }
+                });
+            }
+            catch { /* dbt artifact directory not watchable */ }
+        }
     }
     const validateImportCandidate = (candidate) => ({
         ...candidate,
@@ -2374,7 +3115,7 @@ export async function startLocalServer(opts) {
             return null;
         return `Likely duplicate of ${match.name} (${match.kind}, ${Math.round(match.score * 100)}% match). Reuse the existing block, extend it, or document this draft as a replacement before certification.`;
     };
-    const runBlockStudioPreviewSource = async (source, targetConnection) => {
+    const runBlockStudioPreviewSource = async (source, targetConnection, parameters = {}) => {
         const activeConnection = requireActiveConnection(targetConnection);
         let tableMapping;
         if (semanticLayer) {
@@ -2388,6 +3129,12 @@ export async function startLocalServer(opts) {
                 tableMapping = undefined;
             }
         }
+        const invocation = prepareBlockInvocation({ source, parameters, surface: 'block_studio' });
+        if (invocation.errors.length > 0)
+            throw new Error(invocation.errors.join(' '));
+        if (invocation.unresolvedParameters.length > 0) {
+            throw new Error(`Provide required parameter${invocation.unresolvedParameters.length === 1 ? '' : 's'}: ${invocation.unresolvedParameters.join(', ')}.`);
+        }
         const semanticCompose = semanticLayer
             ? composeSemanticBlockSql(source, semanticLayer, {
                 driver: activeConnection.driver,
@@ -2395,6 +3142,7 @@ export async function startLocalServer(opts) {
                 projectRoot,
                 projectConfig,
                 detectedProvider: semanticDetectedProvider,
+                parameters: invocation.values,
             })
             : null;
         const validation = validateBlockStudioSource(source, semanticLayer);
@@ -2407,11 +3155,12 @@ export async function startLocalServer(opts) {
         }
         const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: activeConnection.driver, tableMapping });
         const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan?.sql ?? executableSql, activeConnection, projectRoot, projectConfig);
-        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), prepared.connection);
+        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...invocation.values }), prepared.connection);
         return {
             sql: prepared.sql,
             result: normalizeQueryResult(result),
             chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
+            invocation,
         };
     };
     const runBlockStudioTestSummary = async (source, targetConnection) => {
@@ -2630,20 +3379,616 @@ export async function startLocalServer(opts) {
         const requestUrl = req.url || '/';
         const url = new URL(requestUrl, 'http://127.0.0.1');
         const path = url.pathname || '/';
-        // CORS — needed for dql-notebook SPA dev mode
-        res.setHeader('Access-Control-Allow-Origin', '*');
+        // Exact-origin CORS. Loopback dev origins are accepted; remote serving
+        // requires an explicit allowlist and bearer token.
+        const requestOrigin = typeof req.headers.origin === 'string' ? req.headers.origin.replace(/\/$/, '') : undefined;
+        const loopbackOrigin = requestOrigin ? isLoopbackOrigin(requestOrigin) : false;
+        const originAllowed = !requestOrigin || (loopback ? loopbackOrigin : allowedOrigins.has(requestOrigin));
+        if (requestOrigin && originAllowed)
+            res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+        res.setHeader('Vary', 'Origin');
         res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        if (!originAllowed && path.startsWith('/api/')) {
+            res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ error: 'Origin is not allowed.' }));
+            return;
+        }
         if (req.method === 'OPTIONS') {
             res.writeHead(204);
             res.end();
             return;
         }
+        if (!loopback && path.startsWith('/api/') && path !== '/api/health') {
+            const authorization = req.headers.authorization ?? '';
+            if (authorization !== `Bearer ${authToken}`) {
+                res.writeHead(401, { 'Content-Type': 'application/json; charset=utf-8', 'WWW-Authenticate': 'Bearer' });
+                res.end(serializeJSON({ error: 'A valid DQL server bearer token is required.' }));
+                return;
+            }
+        }
         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/onboarding/status') {
+            const requestId = apiRequestId('onboarding-status');
+            const dbtProjectDir = findDbtProjectPath(projectRoot, projectConfig);
+            const manifestPath = resolve(dbtProjectDir, projectConfig.dbt?.manifestPath ?? 'target/manifest.json');
+            const configuredProfilesDir = projectConfig.dbt?.profilesDir ? resolve(projectRoot, projectConfig.dbt.profilesDir) : undefined;
+            const profilePath = findDbtProfilePaths(projectRoot, dbtProjectDir, configuredProfilesDir)[0];
+            const registry = loadDomainPackageRegistry(projectRoot);
+            const manifestFound = existsSync(manifestPath);
+            let snapshotId;
+            let snapshotError;
+            if (manifestFound) {
+                try {
+                    snapshotId = projectSnapshot().snapshotId;
+                }
+                catch (error) {
+                    snapshotError = error instanceof Error ? error.message : String(error);
+                }
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                requestId,
+                snapshotId,
+                dbt: {
+                    configured: Boolean(projectConfig.dbt),
+                    projectDir: projectConfig.dbt?.projectDir,
+                    manifestPath: projectConfig.dbt?.manifestPath,
+                    profilesDir: configuredProfilesDir
+                        ? portableProjectPath(projectRoot, configuredProfilesDir)
+                        : profilePath ? portableProjectPath(projectRoot, dirname(profilePath)) : undefined,
+                    repoUrl: projectConfig.dbt?.repoUrl,
+                    branch: projectConfig.dbt?.branch,
+                    subPath: projectConfig.dbt?.subPath,
+                    projectFound: existsSync(join(dbtProjectDir, 'dbt_project.yml')),
+                    manifestFound,
+                },
+                modeling: {
+                    enabled: projectConfig.manifestVersion === 3 && projectConfig.modeling?.mode === 'dbt-first',
+                    manifestVersion: projectConfig.manifestVersion ?? 2,
+                    mode: projectConfig.modeling?.mode,
+                },
+                domains: { count: registry.values().length, diagnostics: registry.diagnostics },
+                snapshot: { id: snapshotId, error: snapshotError },
+                capabilities: {
+                    warehouse: Boolean(connection),
+                    ai: Boolean(process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY || process.env.OLLAMA_BASE_URL),
+                },
+            }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/onboarding/dbt/preview') {
+            const requestId = apiRequestId('onboarding-dbt-preview');
+            try {
+                const preview = previewDbtOnboarding(await readJSON(req));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, ...preview }));
+            }
+            catch (error) {
+                const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : 'DBT_ARTIFACT_INVALID';
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Verify the dbt project and artifact paths, then preview again.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/onboarding/dbt/apply') {
+            const requestId = apiRequestId('onboarding-dbt-apply');
+            try {
+                const body = await readJSON(req);
+                let preview;
+                try {
+                    preview = previewDbtOnboarding(body);
+                }
+                catch (error) {
+                    const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : '';
+                    if (code !== 'DBT_MANIFEST_MISSING' || body.buildArtifacts !== true)
+                        throw error;
+                    const { dbtProjectDir } = onboardingDbtPaths(body);
+                    try {
+                        const { profilesDir } = onboardingDbtPaths(body);
+                        const parseArgs = buildDbtParseArgs(dbtProjectDir, profilesDir);
+                        execFileSync('dbt', parseArgs, {
+                            cwd: dbtProjectDir,
+                            timeout: 120_000,
+                            maxBuffer: 1024 * 1024,
+                            encoding: 'utf8',
+                            stdio: ['ignore', 'pipe', 'pipe'],
+                            env: { ...process.env, DBT_LOG_FORMAT: 'text' },
+                        });
+                    }
+                    catch (parseError) {
+                        throw Object.assign(new Error(`dbt parse failed. Run it in ${dbtProjectDir} to inspect the project error, then retry.`), { code: 'DBT_PARSE_FAILED', cause: parseError });
+                    }
+                    preview = previewDbtOnboarding(body);
+                }
+                const expectedFingerprint = typeof body.fingerprint === 'string'
+                    ? body.fingerprint
+                    : typeof body.expectedFingerprint === 'string' ? body.expectedFingerprint : undefined;
+                if ((!expectedFingerprint && body.buildArtifacts !== true) || (expectedFingerprint && expectedFingerprint !== preview.fingerprint)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code: 'SOURCE_CHANGED', message: 'dbt artifacts changed after preview. Review the refreshed preview before applying.', nextActions: ['Refresh the preview and review the new diff.'] })));
+                    return;
+                }
+                const nextConfig = {
+                    ...projectConfig,
+                    manifestVersion: 3,
+                    modeling: { mode: 'dbt-first' },
+                    dbt: {
+                        projectDir: preview.projectDir,
+                        manifestPath: preview.manifestPath,
+                        ...(preview.profilesDir ? { profilesDir: preview.profilesDir } : {}),
+                        ...(preview.repoUrl ? { repoUrl: preview.repoUrl, branch: preview.branch, subPath: preview.subPath } : {}),
+                    },
+                    semanticLayer: { provider: 'dbt', projectPath: preview.projectDir },
+                };
+                const configPath = join(projectRoot, 'dql.config.json');
+                const previousConfigSource = readFileSync(configPath, 'utf8');
+                const previousProjectConfig = projectConfig;
+                const previousConnection = connection;
+                const tempPath = `${configPath}.tmp-${process.pid}`;
+                writeFileSync(tempPath, `${JSON.stringify(nextConfig, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+                renameSync(tempPath, configPath);
+                projectConfig = nextConfig;
+                if (!configuredConnection)
+                    connection = resolveDbtProfileRuntimeConnection(projectRoot, nextConfig);
+                projectSnapshots.invalidate();
+                invalidateAgentProjectState(projectRoot);
+                let snapshotId;
+                try {
+                    snapshotId = projectSnapshot().snapshotId;
+                }
+                catch (error) {
+                    const rollbackPath = `${configPath}.rollback-${process.pid}`;
+                    writeFileSync(rollbackPath, previousConfigSource, { encoding: 'utf8', mode: 0o600 });
+                    renameSync(rollbackPath, configPath);
+                    projectConfig = previousProjectConfig;
+                    connection = previousConnection;
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    throw Object.assign(new Error(`dbt-first configuration did not compile and was rolled back: ${error instanceof Error ? error.message : String(error)}`), { code: 'SNAPSHOT_BUILD_FAILED' });
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId, applied: true, config: { manifestVersion: 3, modeling: nextConfig.modeling, dbt: nextConfig.dbt }, fingerprint: preview.fingerprint }));
+            }
+            catch (error) {
+                const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : 'DBT_ARTIFACT_INVALID';
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Fix the reported dbt issue and run preview again.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/onboarding/refresh') {
+            const requestId = apiRequestId('onboarding-refresh');
+            const id = `dbt-refresh-${Date.now().toString(36)}`;
+            try {
+                const body = await readJSON(req);
+                const currentArtifact = previewDbtOnboarding({});
+                if (!body.expectedFingerprint || body.expectedFingerprint !== currentArtifact.fingerprint) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code: 'SOURCE_CHANGED', message: 'dbt artifacts changed before refresh. Review the current artifact preview.', nextActions: ['Return to the dbt preview step and review the refreshed fingerprint.'] })));
+                    return;
+                }
+                projectSnapshots.invalidate();
+                const snapshot = projectSnapshot();
+                invalidateAgentProjectState(projectRoot);
+                await reindexProject(projectRoot, { manifest: snapshot.manifest, kgPath: defaultKgPath(projectRoot) });
+                const job = { id, kind: 'dbt_refresh', status: 'completed', createdAt: new Date().toISOString(), result: { snapshotId: snapshot.snapshotId, diagnostics: snapshot.manifest.diagnostics ?? [] } };
+                onboardingJobs.set(id, job);
+                res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, jobId: id, ...job }));
+            }
+            catch (error) {
+                const job = { id, kind: 'dbt_refresh', status: 'failed', createdAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) };
+                onboardingJobs.set(id, job);
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ...apiErrorEnvelope({ requestId, code: 'SNAPSHOT_BUILD_FAILED', message: job.error, nextActions: ['Keep using the previous snapshot while fixing compile diagnostics.'] }), jobId: id, ...job }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/onboarding/jobs/')) {
+            const requestId = apiRequestId('onboarding-job');
+            const id = decodeURIComponent(path.slice('/api/onboarding/jobs/'.length));
+            const job = onboardingJobs.get(id);
+            res.writeHead(job ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
+            const jobSnapshotId = typeof job?.result?.snapshotId === 'string'
+                ? String((job?.result).snapshotId)
+                : undefined;
+            res.end(serializeJSON(job ? { requestId, ...(jobSnapshotId ? { snapshotId: jobSnapshotId } : {}), ...job } : apiErrorEnvelope({ requestId, code: 'ONBOARDING_JOB_NOT_FOUND', message: `onboarding job not found: ${id}`, recoverable: false })));
+            return;
+        }
+        if (req.method === 'DELETE' && path.startsWith('/api/onboarding/jobs/')) {
+            const requestId = apiRequestId('onboarding-job-cancel');
+            const id = decodeURIComponent(path.slice('/api/onboarding/jobs/'.length));
+            const job = onboardingJobs.get(id);
+            if (job)
+                onboardingJobs.set(id, { ...job, status: 'cancelled' });
+            res.writeHead(job ? 200 : 404, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(job ? { requestId, ...job, status: 'cancelled' } : apiErrorEnvelope({ requestId, code: 'ONBOARDING_JOB_NOT_FOUND', message: `onboarding job not found: ${id}`, recoverable: false })));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/onboarding/domains/discover') {
+            const requestId = apiRequestId('domain-discovery');
+            try {
+                const dbtManifestPath = resolveDbtManifestPath(projectRoot);
+                if (!dbtManifestPath || !existsSync(dbtManifestPath))
+                    throw Object.assign(new Error('No dbt manifest found. Run dbt parse or connect the project first.'), { code: 'DBT_MANIFEST_MISSING' });
+                const report = discoverDbtDomains({ projectRoot, dbtManifestPath });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    requestId,
+                    snapshotId: projectSnapshot().snapshotId,
+                    ...report,
+                    capabilities: { aiEnrichment: false, deterministic: true },
+                }));
+            }
+            catch (error) {
+                const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : 'DBT_ARTIFACT_INVALID';
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Build a valid dbt manifest and retry discovery.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/onboarding/domains/apply') {
+            const requestId = apiRequestId('domain-apply');
+            try {
+                const body = await readJSON(req);
+                const dbtManifestPath = resolveDbtManifestPath(projectRoot);
+                if (!dbtManifestPath || !existsSync(dbtManifestPath))
+                    throw Object.assign(new Error('No dbt manifest found.'), { code: 'DBT_MANIFEST_MISSING' });
+                const report = discoverDbtDomains({ projectRoot, dbtManifestPath });
+                const expectedFingerprint = body.sourceFingerprint ?? body.expectedSourceFingerprint;
+                if (!expectedFingerprint || expectedFingerprint !== report.sourceFingerprint) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: projectSnapshot().snapshotId, code: 'SOURCE_CHANGED', message: 'dbt/domain evidence changed after discovery. Review the refreshed proposals before applying.', nextActions: ['Run domain discovery again and review the updated evidence.'] })));
+                    return;
+                }
+                const proposalIds = Array.isArray(body.proposals) ? body.proposals.flatMap((value) => typeof value === 'object' && value && 'id' in value && typeof value.id === 'string' ? [value.id] : []) : [];
+                const requested = proposalIds.length > 0 ? proposalIds : Array.isArray(body.selectedDomains) ? body.selectedDomains : Array.isArray(body.domains) ? body.domains : report.proposals.map((proposal) => proposal.id);
+                const selected = new Set(requested.filter((value) => typeof value === 'string'));
+                if (body.mode === 'preview') {
+                    const preview = report.proposals.filter((proposal) => selected.has(proposal.id)).map((proposal) => ({ path: join('domains', ...proposal.id.split('.'), 'domain.dql').replace(/\\/g, '/'), operation: 'create_or_retain', summary: `${proposal.matchedDbtUniqueIds.length} dbt model(s); review required` }));
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, snapshotId: projectSnapshot().snapshotId, applied: false, preview }));
+                    return;
+                }
+                const existing = loadDomainPackageRegistry(projectRoot);
+                const applied = [];
+                for (const proposal of report.proposals.filter((value) => selected.has(value.id))) {
+                    if (existing.get(proposal.id)) {
+                        applied.push({ id: proposal.id, status: 'existing', message: 'Existing Domain Package retained unchanged.' });
+                        continue;
+                    }
+                    const segments = proposal.id.split('.');
+                    if (segments.length === 0 || segments.some((segment) => !/^[a-z0-9_]+$/.test(segment))) {
+                        applied.push({ id: proposal.id, status: 'blocked', message: 'Domain id is not a safe normalized path.' });
+                        continue;
+                    }
+                    const sourcePath = join('domains', ...segments, 'domain.dql').replace(/\\/g, '/');
+                    const absolute = join(projectRoot, sourcePath);
+                    mkdirSync(dirname(absolute), { recursive: true });
+                    const dbtPaths = [...new Set(report.memberships.filter((membership) => membership.proposedDomain === proposal.id).flatMap((membership) => membership.sourcePath ? [membership.sourcePath] : []))].sort();
+                    const source = renderDomainDeclaration({
+                        id: proposal.id,
+                        name: proposal.name,
+                        parent: proposal.proposedParent,
+                        owner: proposal.owner,
+                        dbtPaths,
+                        description: 'Draft domain boundary proposed from cited dbt evidence; review before governance use.',
+                    });
+                    const temp = `${absolute}.tmp-${process.pid}`;
+                    writeFileSync(temp, source, { encoding: 'utf8', mode: 0o600 });
+                    renameSync(temp, absolute);
+                    applied.push({ id: proposal.id, status: 'created', path: sourcePath, message: 'Review-required domain boundary created; no relationships or skills were certified.' });
+                }
+                projectSnapshots.invalidate();
+                invalidateAgentProjectState(projectRoot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: projectSnapshot().snapshotId, applied: true, results: applied, domains: loadDomainPackageRegistry(projectRoot).values().map((pkg) => ({ id: pkg.id, filePath: pkg.declarationPath, lifecycle: 'draft' })) }));
+            }
+            catch (error) {
+                const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : 'DOMAIN_COLLISION';
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Resolve the collision or invalid proposal and preview again.'] })));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/domain-packages') {
+            const snapshot = projectSnapshot();
+            const manifest = snapshot.manifest;
+            const registry = loadDomainPackageRegistry(projectRoot);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                domains: listDomains(projectRoot),
+                packages: registry.values().map((pkg) => ({
+                    id: pkg.id,
+                    name: pkg.name,
+                    parent: pkg.parent,
+                    depth: pkg.depth,
+                    ancestry: pkg.ancestry,
+                    declarationPath: pkg.declarationPath,
+                    root: relative(projectRoot, pkg.root).replace(/\\/g, '/'),
+                    owner: pkg.owner,
+                    exports: pkg.exports,
+                })),
+                modeling: manifest.modeling,
+                dbtProvenance: manifest.dbtProvenance,
+                domainAssets: collectDomainPackageAssets(projectRoot, registry),
+                diagnostics: manifest.diagnostics ?? [],
+                snapshot: { id: snapshot.snapshotId, stale: snapshot.stale, error: snapshot.error },
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/domain-workspaces') {
+            const requestId = apiRequestId('domain-workspaces');
+            const snapshot = projectSnapshot();
+            const manifest = snapshot.manifest;
+            const packages = Object.values(manifest.modeling?.packages ?? {});
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                requestId,
+                snapshotId: snapshot.snapshotId,
+                snapshot: { id: snapshot.snapshotId, stale: snapshot.stale, error: snapshot.error },
+                domains: packages.map((pkg) => domainWorkspaceSummary(manifest, pkg.id)),
+                unassignedModels: Object.values(manifest.dbtProvenance?.nodes ?? {}).filter((node) => !Object.values(manifest.modeling?.entities ?? {}).some((entity) => entity.dbtUniqueId === node.uniqueId)).length,
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/domain-workspaces/')) {
+            const requestId = apiRequestId('domain-workspace');
+            const suffix = decodeURIComponent(path.slice('/api/domain-workspaces/'.length));
+            const relatedSuffix = '/related-products';
+            const domainId = suffix.endsWith(relatedSuffix) ? suffix.slice(0, -relatedSuffix.length) : suffix;
+            const snapshot = projectSnapshot();
+            const manifest = snapshot.manifest;
+            if (!manifest.modeling?.packages[domainId]) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'DOMAIN_NOT_FOUND', message: `domain workspace not found: ${domainId}`, recoverable: false })));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(suffix.endsWith(relatedSuffix)
+                ? { requestId, domain: domainId, ...relatedProductsForDomain(manifest, domainId), snapshotId: snapshot.snapshotId }
+                : {
+                    requestId,
+                    snapshotId: snapshot.snapshotId,
+                    ...domainWorkspaceSummary(manifest, domainId),
+                    relatedProducts: relatedProductsForDomain(manifest, domainId),
+                    snapshot: { id: snapshot.snapshotId, stale: snapshot.stale, error: snapshot.error },
+                }));
+            return;
+        }
+        // Manifest v3 modeling surface. This response intentionally contains dbt
+        // provenance references and the sparse DQL overlay, never copied dbt YAML.
+        if (req.method === 'GET' && path === '/api/modeling/dbt-first') {
+            const requestId = apiRequestId('modeling-dbt-first');
+            const snapshot = projectSnapshot();
+            const manifest = snapshot.manifest;
+            if (manifest.manifestVersion !== 3 || !manifest.modeling || !manifest.dbtProvenance) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'DBT_FIRST_NOT_ENABLED', message: 'dbt-first modeling is not enabled. Set manifestVersion: 3 and modeling.mode: "dbt-first" in dql.config.json.', nextActions: ['Use Setup to connect dbt and enable dbt-first modeling.'] })));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                requestId,
+                snapshotId: snapshot.snapshotId,
+                manifestVersion: manifest.manifestVersion,
+                dbtProvenance: manifest.dbtProvenance,
+                modeling: manifest.modeling,
+                domainAssets: collectDomainPackageAssets(projectRoot, loadDomainPackageRegistry(projectRoot)),
+                lineage: manifest.lineage,
+                diagnostics: manifest.diagnostics ?? [],
+                snapshot: { id: snapshot.snapshotId, stale: snapshot.stale, error: snapshot.error },
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/modeling/dbt-first/nodes/')) {
+            const requestId = apiRequestId('modeling-node');
+            const dbtManifestPath = resolveDbtManifestPath(projectRoot);
+            const uniqueId = decodeURIComponent(path.slice('/api/modeling/dbt-first/nodes/'.length));
+            const snapshot = projectSnapshot();
+            const cacheKey = `${snapshot.snapshotId}:${uniqueId}`;
+            if (!dbtNodeDetailCache.has(cacheKey)) {
+                dbtNodeDetailCache.set(cacheKey, dbtManifestPath ? loadDbtNodeAuthoringDetail(dbtManifestPath, uniqueId) : undefined);
+            }
+            const detail = dbtNodeDetailCache.get(cacheKey);
+            if (!detail) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'DBT_NODE_NOT_FOUND', message: `dbt node not found: ${uniqueId}`, recoverable: false })));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, ...detail }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/modeling/dbt-first/inventory') {
+            const requestId = apiRequestId('modeling-inventory');
+            const snapshot = projectSnapshot();
+            const manifest = snapshot.manifest;
+            const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit')) || 50));
+            const cursor = Math.max(0, Number(url.searchParams.get('cursor')) || 0);
+            const query = (url.searchParams.get('q') ?? '').trim().toLowerCase();
+            const domain = (url.searchParams.get('domain') ?? '').trim();
+            const boundByDbtId = new Map(Object.values(manifest.modeling?.entities ?? {}).map((entity) => [entity.dbtUniqueId, entity]));
+            const nodes = Object.values(manifest.dbtProvenance?.nodes ?? {})
+                .filter((node) => !query || `${node.name} ${node.relation ?? ''} ${node.sourcePath ?? ''}`.toLowerCase().includes(query))
+                .filter((node) => !domain || boundByDbtId.get(node.uniqueId)?.domain === domain)
+                .sort((a, b) => a.uniqueId.localeCompare(b.uniqueId));
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                requestId,
+                items: nodes.slice(cursor, cursor + limit).map((node) => ({ ...node, binding: boundByDbtId.get(node.uniqueId) })),
+                nextCursor: cursor + limit < nodes.length ? cursor + limit : null,
+                total: nodes.length,
+                snapshotId: snapshot.snapshotId,
+            }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/modeling/dbt-first/nodes/batch') {
+            const requestId = apiRequestId('modeling-node-batch');
+            const body = await readJSON(req);
+            const uniqueIds = Array.isArray(body.uniqueIds) ? body.uniqueIds.filter((value) => typeof value === 'string').slice(0, 100) : [];
+            const snapshot = projectSnapshot();
+            const dbtManifestPath = resolveDbtManifestPath(projectRoot);
+            const details = uniqueIds.map((uniqueId) => {
+                const cacheKey = `${snapshot.snapshotId}:${uniqueId}`;
+                if (!dbtNodeDetailCache.has(cacheKey))
+                    dbtNodeDetailCache.set(cacheKey, dbtManifestPath ? loadDbtNodeAuthoringDetail(dbtManifestPath, uniqueId) : undefined);
+                return dbtNodeDetailCache.get(cacheKey);
+            }).filter(Boolean);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ requestId, details, snapshotId: snapshot.snapshotId }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/modeling/dbt-first/neighborhood') {
+            const requestId = apiRequestId('modeling-neighborhood');
+            const snapshot = projectSnapshot();
+            const manifest = snapshot.manifest;
+            const entityRef = url.searchParams.get('entity') ?? '';
+            const limit = Math.min(200, Math.max(1, Number(url.searchParams.get('limit')) || 200));
+            const entities = manifest.modeling?.entities ?? {};
+            const relationships = manifest.modeling?.relationships ?? {};
+            const entityKey = entities[entityRef] ? entityRef : Object.entries(entities).find(([, entity]) => entity.qualifiedId === entityRef)?.[0];
+            if (!entityKey) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code: 'MODELING_ENTITY_NOT_FOUND', message: `modeling entity not found: ${entityRef}`, recoverable: false })));
+                return;
+            }
+            const edges = Object.values(relationships).filter((relationship) => relationship.from === entityKey || relationship.to === entityKey).slice(0, limit);
+            const keys = new Set([entityKey, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                requestId,
+                entities: Object.fromEntries([...keys].flatMap((key) => entities[key] ? [[key, entities[key]]] : [])),
+                relationships: Object.fromEntries(edges.map((edge) => [edge.qualifiedId, edge])),
+                snapshotId: snapshot.snapshotId,
+            }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/modeling/dbt-first/dbt-source/preview') {
+            const requestId = apiRequestId('modeling-dbt-source-preview');
+            const snapshot = projectSnapshot();
+            try {
+                const body = await readJSON(req);
+                if (!body.change)
+                    throw Object.assign(new Error('A dbt source change is required.'), { code: 'INVALID_REQUEST' });
+                if (body.expectedSnapshotId && body.expectedSnapshotId !== snapshot.snapshotId) {
+                    throw Object.assign(new Error('Project sources changed after the model was loaded.'), { code: 'SOURCE_CHANGED' });
+                }
+                const { dbtProjectDir, manifestPath } = onboardingDbtPaths({});
+                const preview = previewDbtSourcePatch(dbtProjectDir, manifestPath, body.change);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, ...preview }));
+            }
+            catch (error) {
+                const code = apiErrorCode(error, 'DBT_SOURCE_PATCH_INVALID');
+                res.writeHead(code === 'SOURCE_CHANGED' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code, message: apiErrorMessage(error), nextActions: ['Refresh the model and review the dbt YAML source patch again.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/modeling/dbt-first/dbt-source/apply') {
+            const requestId = apiRequestId('modeling-dbt-source-apply');
+            const snapshot = projectSnapshot();
+            try {
+                const body = await readJSON(req);
+                if (!body.change)
+                    throw Object.assign(new Error('A dbt source change is required.'), { code: 'INVALID_REQUEST' });
+                if (!body.expectedSnapshotId || body.expectedSnapshotId !== snapshot.snapshotId) {
+                    throw Object.assign(new Error('Project sources changed after the source patch preview.'), { code: 'SOURCE_CHANGED' });
+                }
+                const expectedFingerprint = body.expectedFingerprint ?? body.fingerprint;
+                if (!expectedFingerprint)
+                    throw Object.assign(new Error('The reviewed source patch fingerprint is required.'), { code: 'SOURCE_CHANGED' });
+                const { dbtProjectDir, manifestPath } = onboardingDbtPaths({});
+                const applied = applyDbtSourcePatch(dbtProjectDir, manifestPath, body.change, expectedFingerprint);
+                projectSnapshots.invalidate();
+                invalidateAgentProjectState(projectRoot);
+                const nextSnapshot = projectSnapshot();
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: nextSnapshot.snapshotId, applied }));
+            }
+            catch (error) {
+                const inferred = /changed after the preview/i.test(apiErrorMessage(error)) ? 'SOURCE_CHANGED' : 'DBT_SOURCE_PATCH_INVALID';
+                const code = apiErrorCode(error, inferred);
+                res.writeHead(code === 'SOURCE_CHANGED' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code, message: apiErrorMessage(error), nextActions: ['Refresh the source patch preview before applying.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/modeling/dbt-first/preview') {
+            const requestId = apiRequestId('modeling-preview');
+            const snapshot = projectSnapshot();
+            try {
+                const body = await readJSON(req);
+                if (!body.change)
+                    throw new Error('A modeling change is required.');
+                if (body.expectedSnapshotId && body.expectedSnapshotId !== snapshot.snapshotId)
+                    throw Object.assign(new Error('Project sources changed after the model was loaded.'), { code: 'SOURCE_CHANGED' });
+                const preview = previewModelingChange(projectRoot, body.change);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, ...preview }));
+            }
+            catch (error) {
+                const code = apiErrorCode(error, 'MODELING_CHANGE_INVALID');
+                res.writeHead(code === 'SOURCE_CHANGED' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code, message: apiErrorMessage(error), nextActions: ['Refresh Domain Studio and preview the change again.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/modeling/dbt-first/apply') {
+            const requestId = apiRequestId('modeling-apply');
+            const snapshot = projectSnapshot();
+            try {
+                const body = await readJSON(req);
+                if (!body.change)
+                    throw new Error('A modeling change is required.');
+                if (!body.expectedSnapshotId || body.expectedSnapshotId !== snapshot.snapshotId)
+                    throw Object.assign(new Error('Project sources changed after the modeling preview.'), { code: 'SOURCE_CHANGED' });
+                if (!body.fingerprint)
+                    throw Object.assign(new Error('The reviewed modeling source fingerprint is required.'), { code: 'SOURCE_CHANGED' });
+                const applied = applyModelingChange(projectRoot, body.change, body.fingerprint);
+                projectSnapshots.invalidate();
+                const nextSnapshot = projectSnapshot();
+                const manifest = nextSnapshot.manifest;
+                await refreshUnifiedProjectIndexes(projectRoot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: nextSnapshot.snapshotId, applied, modeling: manifest.modeling, diagnostics: manifest.diagnostics ?? [] }));
+            }
+            catch (error) {
+                const inferred = /changed after the preview/i.test(apiErrorMessage(error)) ? 'SOURCE_CHANGED' : 'MODELING_APPLY_FAILED';
+                const code = apiErrorCode(error, inferred);
+                res.writeHead(code === 'SOURCE_CHANGED' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code, message: apiErrorMessage(error), nextActions: ['Refresh Domain Studio and review the latest source diff.'] })));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/modeling/dbt-first/relationships/validate') {
+            const requestId = apiRequestId('modeling-relationship-validate');
+            const snapshot = projectSnapshot();
+            try {
+                const body = await readJSON(req);
+                if (!body.relationship)
+                    throw new Error('A relationship is required.');
+                if (!body.expectedSnapshotId || body.expectedSnapshotId !== snapshot.snapshotId)
+                    throw Object.assign(new Error('Project sources changed before relationship validation.'), { code: 'SOURCE_CHANGED' });
+                const manifest = snapshot.manifest;
+                const activeConnection = requireActiveConnection();
+                const evidence = await validateModelingRelationship(body.relationship, manifest, (sql) => executor.executeQuery(sql, [], {}, activeConnection), (identifier) => getDialect(activeConnection.driver).quoteIdentifier(identifier));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ requestId, snapshotId: snapshot.snapshotId, evidence }));
+            }
+            catch (error) {
+                const code = apiErrorCode(error, 'RELATIONSHIP_VALIDATION_FAILED');
+                res.writeHead(code === 'SOURCE_CHANGED' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(apiErrorEnvelope({ requestId, snapshotId: snapshot.snapshotId, code, message: apiErrorMessage(error), nextActions: ['Refresh the model or configure a warehouse connection, then retry validation.'] })));
+            }
+            return;
+        }
         if (req.method === 'GET' && path === '/api/agent-runs') {
             const rawLimit = Number(url.searchParams.get('limit'));
             const limit = Number.isFinite(rawLimit) && rawLimit > 0
@@ -3036,6 +4381,11 @@ export async function startLocalServer(opts) {
                     selection: typeof body?.context?.selection === 'string' ? body.context.selection : undefined,
                 };
                 const owner = typeof body?.owner === 'string' ? body.owner : undefined;
+                const domain = typeof body?.domain === 'string' && body.domain.trim() ? body.domain.trim() : undefined;
+                const modelAreaId = typeof body?.modelAreaId === 'string' && body.modelAreaId.trim() ? body.modelAreaId.trim() : undefined;
+                const purpose = typeof body?.purpose === 'string'
+                    ? body.purpose?.trim() || undefined
+                    : undefined;
                 const userId = typeof body?.userId === 'string'
                     ? body.userId
                     : undefined;
@@ -3060,6 +4410,14 @@ export async function startLocalServer(opts) {
                 catch {
                     // Best-effort: a failed reindex falls back to whatever KG exists (or none).
                 }
+                const { domainContext, contextPack } = await buildDirectBuildContext({
+                    question: prompt,
+                    domain,
+                    purpose,
+                    modelAreaId,
+                    surface: target === 'cell' ? 'notebook' : 'block',
+                    selectedContext: { target, mode, blockPath, owner },
+                });
                 // Inject user-authored Skills as business context; the engine selects the
                 // relevant subset and stamps `appliedSkills` on the result.
                 const skills = loadSkills(projectRoot).skills;
@@ -3071,6 +4429,10 @@ export async function startLocalServer(opts) {
                     mode,
                     blockPath,
                     owner,
+                    domain,
+                    modelAreaId,
+                    contextPack,
+                    domainContext,
                     userId,
                     skills,
                     dbtManifestPath: resolveDbtManifestPath(projectRoot, loadProjectConfig(projectRoot)),
@@ -3127,6 +4489,52 @@ export async function startLocalServer(opts) {
         // ── 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/settings') {
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(buildSkillPathSettings(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 === 'PUT' && path === '/api/skills/settings') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const requestedPath = typeof body.path === 'string' ? body.path.trim() : '';
+                if (!requestedPath || requestedPath.includes('\0')) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Provide an existing Skills folder path.' }));
+                    return;
+                }
+                const resolvedPath = resolve(projectRoot, requestedPath);
+                if (!existsSync(resolvedPath) || !statSync(resolvedPath).isDirectory()) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Skills folder not found: ${resolvedPath}` }));
+                    return;
+                }
+                const configPath = join(projectRoot, 'dql.config.json');
+                const raw = existsSync(configPath)
+                    ? JSON.parse(readFileSync(configPath, 'utf-8'))
+                    : {};
+                const layout = raw.layout && typeof raw.layout === 'object' && !Array.isArray(raw.layout)
+                    ? raw.layout
+                    : {};
+                raw.layout = { ...layout, skillsPath: requestedPath };
+                writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`, 'utf-8');
+                projectConfig = loadProjectConfig(projectRoot);
+                invalidateAgentProjectState(projectRoot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(buildSkillPathSettings(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 === 'GET' && path === '/api/skills') {
             try {
                 const skills = loadSkills(projectRoot).skills
@@ -3240,9 +4648,12 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'Provide { domain } with a non-empty name.' }));
                     return;
                 }
-                writeDomainDeclaration(projectRoot, input);
-                await refreshLocalMetadataCatalog(projectRoot);
-                const domain = findDomain(projectRoot, input.name);
+                applyModelingChange(projectRoot, {
+                    operation: 'upsert_domain',
+                    value: { ...input, id: input.id ?? domainFolderSlug(input.name).replace(/-/g, '_') },
+                });
+                await refreshUnifiedProjectIndexes(projectRoot);
+                const domain = findDomain(projectRoot, input.id ?? input.name);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ domain }));
             }
@@ -3263,12 +4674,15 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 // If the name changed, remove the old declaration so we never orphan one.
-                if (domainFolderSlug(id) !== domainFolderSlug(input.name)) {
-                    deleteDomainDeclaration(projectRoot, id);
+                if (domainKey(id) !== domainKey(input.id ?? input.name)) {
+                    deleteCanonicalDomainDeclaration(projectRoot, id);
                 }
-                writeDomainDeclaration(projectRoot, input);
-                await refreshLocalMetadataCatalog(projectRoot);
-                const domain = findDomain(projectRoot, input.name);
+                applyModelingChange(projectRoot, {
+                    operation: 'upsert_domain',
+                    value: { ...input, id: input.id ?? id },
+                });
+                await refreshUnifiedProjectIndexes(projectRoot);
+                const domain = findDomain(projectRoot, input.id ?? input.name);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ domain }));
             }
@@ -3281,8 +4695,8 @@ export async function startLocalServer(opts) {
         if (req.method === 'DELETE' && path.startsWith('/api/domains/')) {
             try {
                 const id = decodeURIComponent(path.slice('/api/domains/'.length));
-                deleteDomainDeclaration(projectRoot, id);
-                await refreshLocalMetadataCatalog(projectRoot);
+                deleteCanonicalDomainDeclaration(projectRoot, id);
+                await refreshUnifiedProjectIndexes(projectRoot);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ ok: true }));
             }
@@ -3377,8 +4791,12 @@ export async function startLocalServer(opts) {
                     }
                     try {
                         if (candidate.kind === 'domain' && candidate.domain) {
-                            const written = writeDomainDeclaration(projectRoot, candidate.domain);
-                            saved.push({ id: candidate.id, path: written.path, status: 'saved' });
+                            const domainId = candidate.domain.id ?? domainFolderSlug(candidate.domain.name).replace(/-/g, '_');
+                            const written = applyModelingChange(projectRoot, {
+                                operation: 'upsert_domain',
+                                value: { ...candidate.domain, id: domainId },
+                            });
+                            saved.push({ id: candidate.id, path: written.patches[0]?.path, status: 'saved' });
                         }
                         else if (candidate.kind === 'skill' && candidate.skill) {
                             const skill = writeSkill(projectRoot, { ...candidate.skill, scope: 'project', status: 'draft' });
@@ -3392,7 +4810,7 @@ export async function startLocalServer(opts) {
                         saved.push({ id: candidate.id, status: 'blocked', blockers: [error instanceof Error ? error.message : String(error)] });
                     }
                 }
-                await refreshLocalMetadataCatalog(projectRoot);
+                await refreshUnifiedProjectIndexes(projectRoot);
                 updateContextBootstrapSession(projectRoot, id, (current) => ({ ...current, closedAt: new Date().toISOString() }));
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ id, saved }));
@@ -3819,6 +5237,33 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        const appStoryRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/story$/);
+        if (req.method === 'POST' && appStoryRun) {
+            const body = await readJSON(req).catch(() => ({}));
+            const runId = typeof body.runId === 'string' ? body.runId : '';
+            const evidence = dashboardRunEvidence.get(runId);
+            const appId = decodeURIComponent(appStoryRun[1]);
+            const dashboardId = decodeURIComponent(appStoryRun[2]);
+            if (!evidence || evidence.expiresAt < Date.now() || evidence.appId !== appId || evidence.dashboardId !== dashboardId) {
+                dashboardRunEvidence.delete(runId);
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Dashboard run evidence expired or does not match this App. Run the dashboard again.' }));
+                return;
+            }
+            // The endpoint accepts runId only. Optional provider wording can be added
+            // here later; the claim-checked deterministic brief is always available.
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                runId,
+                snapshotId: evidence.snapshotId,
+                filterFingerprint: evidence.filterFingerprint,
+                resultFingerprint: evidence.resultFingerprint,
+                personaFingerprint: evidence.personaFingerprint,
+                facts: evidence.facts,
+                story: evidence.story,
+            }));
+            return;
+        }
         const appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
         if (req.method === 'POST' && appDashRun) {
             try {
@@ -3831,6 +5276,12 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: `Dashboard "${dashboardId}" not found in app "${appId}"` }));
                     return;
                 }
+                const activeApp = activePersonaAppId();
+                if (activeApp && activeApp !== appId) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `The active persona belongs to App "${activeApp}", not "${appId}".` }));
+                    return;
+                }
                 const manifest = buildManifest({ projectRoot });
                 const variables = body.variables && typeof body.variables === 'object'
                     ? body.variables
@@ -3873,7 +5324,38 @@ export async function startLocalServer(opts) {
                             });
                             continue;
                         }
-                        if (pin.refreshCadence === 'daily' && pin.sql && isAiPinRefreshDue(pin.lastRefreshedAt)) {
+                        const pinPlan = pin.analysisPlan && typeof pin.analysisPlan === 'object' && !Array.isArray(pin.analysisPlan)
+                            ? pin.analysisPlan
+                            : undefined;
+                        const pinArtifact = normalizeDqlArtifactReference(pinPlan?.dqlArtifact);
+                        let renderedPinResult = pin.result;
+                        let renderedPinChartConfig = pin.chartConfig;
+                        if (pinArtifact) {
+                            try {
+                                const boundParameters = dashboardTileParameterValues({
+                                    item,
+                                    dashboardValues: dashboardVariables,
+                                    requestValues: variables,
+                                });
+                                const executed = await executeDqlArtifactSourceForAgent(pinArtifact.source, { name: pinArtifact.name ?? pin.title, path: pinArtifact.sourcePath }, { question: pin.question, parameters: { ...(pinArtifact.parameterValues ?? {}), ...boundParameters } });
+                                renderedPinResult = executed;
+                                renderedPinChartConfig = executed.chartConfig && typeof executed.chartConfig === 'object'
+                                    ? executed.chartConfig
+                                    : renderedPinChartConfig;
+                            }
+                            catch (err) {
+                                tiles.push({
+                                    tileId: item.i,
+                                    status: 'error',
+                                    tileType: 'aiPin',
+                                    title: item.title ?? pin.title,
+                                    error: err instanceof Error ? err.message : String(err),
+                                    trustState: pinArtifact.trustState ?? 'review_required',
+                                });
+                                continue;
+                            }
+                        }
+                        else if (pin.refreshCadence === 'daily' && pin.sql && isAiPinRefreshDue(pin.lastRefreshedAt)) {
                             try {
                                 const refreshed = await executeLocalSqlForStoredResult(pin.sql);
                                 pin = localApps.updateAiPinResult(pin.id, refreshed) ?? pin;
@@ -3888,8 +5370,8 @@ export async function startLocalServer(opts) {
                             tileType: 'aiPin',
                             title: item.title ?? pin.title,
                             viz: item.viz,
-                            chartConfig: mergeDashboardChartConfig(pin.chartConfig, item),
-                            result: pin.result,
+                            chartConfig: mergeDashboardChartConfig(renderedPinChartConfig, item),
+                            result: renderedPinResult,
                             aiPin: pin,
                             citation: {
                                 kind: 'ai_pin',
@@ -3898,6 +5380,70 @@ export async function startLocalServer(opts) {
                         });
                         continue;
                     }
+                    if (item.semantic) {
+                        try {
+                            if (!semanticLayer)
+                                throw new Error('Semantic layer is not available for this governed query.');
+                            const knownMetrics = new Set(semanticLayer.listMetrics().map((metric) => metric.name));
+                            const missingMetrics = item.semantic.metrics.filter((metric) => !knownMetrics.has(metric));
+                            if (missingMetrics.length)
+                                throw new Error(`Semantic definition changed; missing metric(s): ${missingMetrics.join(', ')}`);
+                            const knownModels = new Set(semanticLayer.listSemanticModels().map((model) => model.name));
+                            const missingModels = item.semantic.semanticModelRefs.filter((model) => !knownModels.has(model));
+                            if (missingModels.length)
+                                throw new Error(`Semantic definition changed; missing model(s): ${missingModels.join(', ')}`);
+                            const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
+                            const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                            const activeFilters = Object.entries(dashboardVariables)
+                                .filter(([field, value]) => item.semantic.dimensions?.includes(field) && value !== undefined && value !== null && value !== '')
+                                .map(([dimension, value]) => ({ dimension, operator: 'equals', values: Array.isArray(value) ? value.map(String) : [String(value)] }));
+                            const staticFilters = (item.semantic.filters ?? []).map((filter) => ({
+                                dimension: filter.field,
+                                operator: filter.operator,
+                                values: Array.isArray(filter.value) ? filter.value.map(String) : [String(filter.value)],
+                            }));
+                            const composed = composeRuntimeSemanticQuery({
+                                metrics: item.semantic.metrics,
+                                dimensions: item.semantic.dimensions ?? [],
+                                filters: [...staticFilters, ...activeFilters],
+                                ...(item.semantic.timeDimension ? { timeDimension: { name: item.semantic.timeDimension, granularity: 'month' } } : {}),
+                                orderBy: item.semantic.orderBy?.map((order) => ({ name: order.field, direction: order.direction })),
+                                limit: item.semantic.limit,
+                                engine: item.semantic.provider,
+                            }, semanticLayer, {
+                                projectRoot,
+                                projectConfig,
+                                detectedProvider: semanticDetectedProvider,
+                                driver: targetConnection.driver,
+                                tableMapping,
+                            });
+                            if (!composed)
+                                throw new Error('The governed semantic query could not be composed.');
+                            const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
+                            const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'ok',
+                                tileType: 'semantic',
+                                title: item.title ?? item.semantic.id,
+                                viz: item.viz,
+                                result: normalizeQueryResult(result),
+                                trustState: 'review_required',
+                                citation: { kind: 'semantic_query', name: item.semantic.id },
+                            });
+                        }
+                        catch (err) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'error',
+                                tileType: 'semantic',
+                                title: item.title ?? item.semantic.id,
+                                error: err instanceof Error ? err.message : String(err),
+                                trustState: 'review_required',
+                            });
+                        }
+                        continue;
+                    }
                     const block = resolveDashboardItemBlock(item, manifest);
                     if (!block) {
                         tiles.push({
@@ -3918,6 +5464,34 @@ export async function startLocalServer(opts) {
                         const source = readFileSync(absBlockPath, 'utf-8');
                         const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
                         const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                        const boundParameters = dashboardTileParameterValues({
+                            item,
+                            dashboardValues: dashboardVariables,
+                            requestValues: variables,
+                        });
+                        const invocation = prepareBlockInvocation({
+                            block: block.name,
+                            source,
+                            parameters: { ...dashboardVariables, ...boundParameters },
+                            parameterSources: Object.fromEntries(Object.keys(boundParameters).map((name) => [name, 'surface'])),
+                            surface: 'app',
+                        });
+                        if (invocation.errors.length || invocation.unresolvedParameters.length) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'unresolved',
+                                tileType: 'block',
+                                blockId: block.name,
+                                title: item.title ?? block.name,
+                                error: invocation.errors[0] ?? `Needs values for: ${invocation.unresolvedParameters.join(', ')}`,
+                                invocation: {
+                                    resolvedParameters: invocation.resolvedParameters,
+                                    unresolvedParameters: invocation.unresolvedParameters,
+                                    auditId: invocation.auditId,
+                                },
+                            });
+                            continue;
+                        }
                         const semanticCompose = semanticLayer
                             ? composeSemanticBlockSql(source, semanticLayer, {
                                 driver: targetConnection.driver,
@@ -3925,6 +5499,7 @@ export async function startLocalServer(opts) {
                                 projectRoot,
                                 projectConfig,
                                 detectedProvider: semanticDetectedProvider,
+                                parameters: invocation.values,
                             })
                             : null;
                         const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, { semanticLayer, driver: targetConnection.driver, tableMapping });
@@ -3945,7 +5520,7 @@ export async function startLocalServer(opts) {
                             dashboard: loaded.dashboard,
                         });
                         const prepared = prepareLocalExecution(filterApplication.sql, targetConnection, projectRoot, projectConfig);
-                        const result = await executor.executeQuery(prepared.sql, filterApplication.sqlParams, runtimeVariables(filterApplication.variables), prepared.connection);
+                        const result = await executor.executeQuery(prepared.sql, filterApplication.sqlParams, runtimeVariables({ ...filterApplication.variables, ...invocation.values }), prepared.connection);
                         tiles.push({
                             tileId: item.i,
                             status: 'ok',
@@ -3960,6 +5535,11 @@ export async function startLocalServer(opts) {
                                 applied: filterApplication.appliedFilters,
                                 skipped: filterApplication.skippedFilters,
                             },
+                            invocation: {
+                                resolvedParameters: invocation.resolvedParameters,
+                                unresolvedParameters: invocation.unresolvedParameters,
+                                auditId: invocation.auditId,
+                            },
                             citation: {
                                 kind: 'block',
                                 name: block.name,
@@ -3987,12 +5567,55 @@ export async function startLocalServer(opts) {
                     }
                 }
                 localApps?.close();
+                const snapshot = projectSnapshot();
+                const filterFingerprint = createHash('sha256').update(JSON.stringify(dashboardVariables)).digest('hex');
+                const resultFingerprint = createHash('sha256').update(JSON.stringify(tiles.map((tile) => ({ tileId: tile.tileId, status: tile.status, result: tile.result })))).digest('hex');
+                const personaFingerprint = createHash('sha256').update(activePersonaAppId() ?? 'global').digest('hex');
+                const runId = `app_run_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                const storyResult = buildDeterministicDashboardStory({
+                    goal: loaded.dashboard.story?.goal ?? loaded.dashboard.metadata.businessOutcome ?? loaded.dashboard.metadata.title,
+                    audience: loaded.dashboard.story?.audience ?? loaded.dashboard.metadata.audience,
+                    filters: dashboardVariables,
+                    tiles: tiles.map((tile) => ({
+                        tileId: tile.tileId,
+                        title: typeof tile.title === 'string' ? tile.title : tile.tileId,
+                        status: tile.status,
+                        trustState: (tile.trustState === 'certified' || tile.trustState === 'review_required' || tile.trustState === 'draft_ready'
+                            ? tile.trustState
+                            : tile.certificationStatus === 'certified' ? 'certified' : 'review_required'),
+                        result: tile.result,
+                        citation: tile.citation,
+                    })),
+                    eligibleTileIds: loaded.dashboard.story?.eligibleTileIds,
+                    driverTileIds: loaded.dashboard.story?.driverTileIds,
+                });
+                dashboardRunEvidence.set(runId, {
+                    appId,
+                    dashboardId,
+                    snapshotId: snapshot.snapshotId,
+                    filterFingerprint,
+                    resultFingerprint,
+                    personaFingerprint,
+                    facts: storyResult.facts,
+                    story: storyResult.story,
+                    expiresAt: Date.now() + 15 * 60_000,
+                });
+                for (const [id, evidence] of dashboardRunEvidence)
+                    if (evidence.expiresAt < Date.now())
+                        dashboardRunEvidence.delete(id);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     appId,
                     dashboardId,
                     persona: activePersonaAppId() ? { appId: activePersonaAppId() } : null,
+                    runId,
+                    snapshotId: snapshot.snapshotId,
+                    filterFingerprint,
+                    resultFingerprint,
+                    personaFingerprint,
                     tiles,
+                    facts: storyResult.facts,
+                    story: storyResult.story,
                 }));
             }
             catch (err) {
@@ -4731,6 +6354,23 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'POST' && path === '/api/git/review/open') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitOpenReview(projectRoot, {
+                    title: body.title ?? '',
+                    body: body.body ?? '',
+                    base: body.base ?? 'main',
+                });
+                res.writeHead(result.ok ? 201 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
         if (req.method === 'POST' && path === '/api/git/pull') {
             try {
                 const result = await gitPull(projectRoot);
@@ -4772,6 +6412,21 @@ export async function startLocalServer(opts) {
         if (req.method === 'GET' && path === '/api/schema') {
             try {
                 const dataFiles = scanDataFiles(projectRoot);
+                const notebookDatasets = datasetWorkspace.list().map((dataset) => ({
+                    name: dataset.alias,
+                    path: dataset.sourcePath,
+                    columns: dataset.profile.columns.map((column) => ({
+                        name: column.name,
+                        type: column.type,
+                    })),
+                    source: "file",
+                    objectType: dataset.storageMode === "staged" ? "staged_dataset" : "dataset",
+                    datasetId: dataset.id,
+                    fileFingerprint: dataset.fileFingerprint,
+                    storageMode: dataset.storageMode,
+                    refreshedAt: dataset.refreshedAt,
+                    trustState: dataset.trustState,
+                }));
                 const { tables, columnsByPath } = connection
                     ? await introspectSchema(executor, connection)
                     : { tables: [], columnsByPath: new Map() };
@@ -4782,9 +6437,13 @@ export async function startLocalServer(opts) {
                     source: 'database',
                     objectType: t.type,
                 }));
-                const seen = new Set(dataFiles.map((f) => f.name));
+                const seen = new Set([
+                    ...dataFiles.map((f) => f.name),
+                    ...notebookDatasets.map((dataset) => dataset.name),
+                ]);
                 const merged = [
-                    ...dataFiles.map((f) => ({ ...f, source: 'file' })),
+                    ...notebookDatasets,
+                    ...dataFiles.map((f) => ({ ...f, source: "file" })),
                     ...dbTables.filter((t) => !seen.has(t.name)),
                 ];
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -4793,8 +6452,27 @@ export async function startLocalServer(opts) {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 console.warn(`[dql] /api/schema introspection failed: ${message}`);
-                const fallback = scanDataFiles(projectRoot).map((f) => ({ ...f, source: 'file' }));
-                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                const fallback = [
+                    ...datasetWorkspace.list().map((dataset) => ({
+                        name: dataset.alias,
+                        path: dataset.sourcePath,
+                        columns: dataset.profile.columns.map((column) => ({
+                            name: column.name,
+                            type: column.type,
+                        })),
+                        source: "file",
+                        objectType: dataset.storageMode === "staged" ? "staged_dataset" : "dataset",
+                        datasetId: dataset.id,
+                        fileFingerprint: dataset.fileFingerprint,
+                        storageMode: dataset.storageMode,
+                        refreshedAt: dataset.refreshedAt,
+                        trustState: dataset.trustState,
+                    })),
+                    ...scanDataFiles(projectRoot).map((f) => ({ ...f, source: "file" })),
+                ];
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
                 res.end(serializeJSON(fallback));
             }
             return;
@@ -4808,6 +6486,11 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'Missing block name' }));
                     return;
                 }
+                if (dbtFirstOwnsSemanticAuthoring(projectConfig)
+                    && (blockType === 'semantic' || /\btype\s*=\s*["']semantic["']/i.test(content ?? ''))) {
+                    sendDbtOwnedSemanticAuthoringError(res);
+                    return;
+                }
                 const created = createBlockArtifacts(projectRoot, {
                     name,
                     domain,
@@ -4835,12 +6518,16 @@ export async function startLocalServer(opts) {
         if (req.method === 'POST' && path === '/api/blocks/save-from-cell') {
             try {
                 const body = await readJSON(req);
-                const { name, domain, owner, content, description, tags, metricRefs, template, llmContext, examples, invariants, } = body;
+                const { name, domain, owner, content, description, tags, metricRefs, template, llmContext, examples, invariants, reviewRequired, datasetRefs, lineage, } = body;
                 if (!name || typeof name !== 'string' || !content || typeof content !== 'string') {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ error: 'name and content are required' }));
                     return;
                 }
+                if (dbtFirstOwnsSemanticAuthoring(projectConfig) && /\btype\s*=\s*["']semantic["']/i.test(content)) {
+                    sendDbtOwnedSemanticAuthoringError(res);
+                    return;
+                }
                 // OSS keeps the save flow deliberately small: the person saving the
                 // reusable answer is accountable for it. Domain/description/tags are
                 // helpful defaults, but not reasons to send a single-user back to a
@@ -4873,12 +6560,18 @@ export async function startLocalServer(opts) {
                 // Save first, then certify against the same local runtime used for the
                 // answer. Passing blocks become certified immediately; anything that
                 // cannot prove itself remains a clearly labelled draft at this path.
-                setBlockStudioStatus(projectRoot, created.path, 'draft');
-                let source = readFileSync(join(projectRoot, created.path), 'utf-8');
-                let status = 'draft';
-                let blockers = [];
+                setBlockStudioStatus(projectRoot, created.path, "draft");
+                let source = readFileSync(join(projectRoot, created.path), "utf-8");
+                let status = "draft";
+                let blockers = reviewRequired
+                    ? [
+                        "Imported or staged datasets require review and reproducibility checks before certification.",
+                    ]
+                    : [];
                 let certification;
                 try {
+                    if (reviewRequired)
+                        throw new Error(blockers[0]);
                     const verdict = await certifyBlockStudioSource(source, created.path);
                     blockers = Array.from(new Set(verdict.checklist.blockers));
                     certification = {
@@ -4893,7 +6586,10 @@ export async function startLocalServer(opts) {
                     }
                 }
                 catch (error) {
-                    blockers = [error instanceof Error ? error.message : String(error)];
+                    blockers = Array.from(new Set([
+                        ...blockers,
+                        error instanceof Error ? error.message : String(error),
+                    ]));
                 }
                 await refreshLocalMetadataCatalog(projectRoot);
                 res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -5166,7 +6862,9 @@ export async function startLocalServer(opts) {
                 // 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)) {
+                const validation = validateBlockStudioSource(source, semanticLayer);
+                const parameterNames = new Set((validation.parameters ?? []).map((parameter) => parameter.name));
+                if (parameterNames.has(column) || (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;
@@ -5182,7 +6880,6 @@ export async function startLocalServer(opts) {
                         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' });
@@ -5223,16 +6920,26 @@ export async function startLocalServer(opts) {
                     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 });
+                const snapshot = projectSnapshot();
+                const kgPath = defaultKgPath(projectRoot);
+                await reindexProject(projectRoot, { kgPath, manifest: snapshot.manifest });
+                const kg = new KGStore(kgPath);
+                let plan;
+                try {
+                    plan = planAppFromPrompt({
+                        prompt: goal,
+                        kg,
+                        domain: typeof body.domain === 'string' ? body.domain : undefined,
+                        audience: typeof body.audience === 'string' ? body.audience : undefined,
+                        mode: body.mode === 'personal' ? 'personal' : 'stakeholder',
+                        snapshotId: snapshot.snapshotId,
+                    });
+                }
+                finally {
+                    kg.close();
+                }
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ plan, blockCount: blocks.length, metricCount: metrics.length, certifiedOnly }));
+                res.end(serializeJSON({ plan, snapshotId: snapshot.snapshotId }));
             }
             catch (error) {
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -6049,7 +7756,10 @@ export async function startLocalServer(opts) {
                 const body = await readJSON(req);
                 const source = typeof body.source === 'string' ? body.source : '';
                 const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                const preview = await runBlockStudioPreviewSource(source, targetConnection);
+                const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
+                    ? body.parameters
+                    : {};
+                const preview = await runBlockStudioPreviewSource(source, targetConnection, parameters);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON(preview));
             }
@@ -6124,12 +7834,294 @@ export async function startLocalServer(opts) {
                 ?? Object.keys(connections)[0]
                 ?? 'default';
             const dbtProfiles = discoverDbtProfileConnections(projectRoot, cfg);
+            const activeDbtProfile = dbtProfiles.find((candidate) => candidate.missingFields.length === 0
+                && !candidate.warnings.some((warning) => warning.startsWith('DuckDB file not found'))
+                && !candidate.warnings.some((warning) => warning.startsWith('Not the default dbt target')));
+            const activeConnection = connection ? {
+                source: Object.keys(connections).length > 0 ? 'dql_config' : activeDbtProfile ? 'dbt_profile' : 'runtime',
+                driver: connection.driver,
+                ...(Object.keys(connections).length === 0 && activeDbtProfile ? { profileId: activeDbtProfile.id } : {}),
+            } : null;
             const connectorStatus = getConnectorInstallStatuses(projectRoot);
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-            res.end(serializeJSON({ default: defaultKey, connections, dbtProfiles, connectorStatus }));
+            res.end(serializeJSON({ default: defaultKey, connections, dbtProfiles, activeConnection, connectorStatus }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/connections/dbt-profiles/preview') {
+            const body = await readJSON(req).catch(() => ({}));
+            const profilePath = typeof body.path === 'string' ? body.path.trim() : '';
+            if (!profilePath) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Enter a profiles.yml file or folder path.' }));
+                return;
+            }
+            const dbtProfiles = discoverDbtProfileConnections(projectRoot, loadProjectConfig(projectRoot), profilePath);
+            if (dbtProfiles.length === 0) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'No supported dbt profile targets were found at that path.' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ dbtProfiles }));
+            return;
+        }
+        if (req.method === "GET" && path === "/api/datasets") {
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(serializeJSON({
+                datasets: datasetWorkspace.list(),
+                workspace: {
+                    target: "local",
+                    databasePath: relative(projectRoot, datasetWorkspace.databasePath).replaceAll("\\", "/"),
+                },
+            }));
+            return;
+        }
+        if (req.method === "POST" && path === "/api/datasets/import") {
+            try {
+                const multipart = String(req.headers["content-type"] ?? "")
+                    .toLowerCase()
+                    .startsWith("multipart/form-data")
+                    ? await readMultipartForm(req)
+                    : null;
+                const body = multipart?.fields ?? (await readJSON(req));
+                if (typeof body.contentBase64 === "string" &&
+                    body.contentBase64.length > 350_000_000) {
+                    throw new Error("Uploaded dataset exceeds the 250 MB local import limit. Link the local path or reduce the file first.");
+                }
+                if (multipart?.file &&
+                    multipart.file.content.byteLength > 250_000_000) {
+                    throw new Error("Uploaded dataset exceeds the 250 MB local import limit. Link the local path or reduce the file first.");
+                }
+                await ensureLocalWorkspaceReady();
+                const imported = await datasetWorkspace.import({
+                    filename: multipart?.file?.filename ??
+                        (typeof body.filename === "string" ? body.filename : undefined),
+                    sourcePath: typeof body.sourcePath === "string" ? body.sourcePath : undefined,
+                    contentBase64: typeof body.contentBase64 === "string"
+                        ? body.contentBase64
+                        : undefined,
+                    content: multipart?.file?.content,
+                    storageMode: body.storageMode === "project" ? "project" : "local",
+                    link: body.link === true || body.link === "true",
+                    name: typeof body.name === "string" ? body.name : undefined,
+                    alias: typeof body.alias === "string" ? body.alias : undefined,
+                    description: typeof body.description === "string" ? body.description : undefined,
+                    owner: typeof body.owner === "string" ? body.owner : undefined,
+                    tags: Array.isArray(body.tags)
+                        ? body.tags.map(String)
+                        : typeof body.tags === "string"
+                            ? body.tags
+                                .split(",")
+                                .map((tag) => tag.trim())
+                                .filter(Boolean)
+                            : undefined,
+                });
+                recordDatasetMetadataSnapshot();
+                res.writeHead(imported.duplicate ? 200 : 201, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON(imported));
+            }
+            catch (error) {
+                res.writeHead(400, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        if (req.method === "GET" && /^\/api\/datasets\/[^/]+$/.test(path)) {
+            const id = decodeURIComponent(path.slice("/api/datasets/".length));
+            const dataset = datasetWorkspace.get(id);
+            if (!dataset) {
+                res.writeHead(404, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({ error: "Dataset not found." }));
+            }
+            else {
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({ dataset }));
+            }
+            return;
+        }
+        if (req.method === "POST" &&
+            /^\/api\/datasets\/[^/]+\/refresh$/.test(path)) {
+            try {
+                const id = decodeURIComponent(path.match(/^\/api\/datasets\/([^/]+)\/refresh$/)?.[1] ?? "");
+                await ensureLocalWorkspaceReady();
+                const dataset = await datasetWorkspace.refresh(id);
+                recordDatasetMetadataSnapshot();
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({ dataset }));
+            }
+            catch (error) {
+                res.writeHead(400, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        if (req.method === "POST" &&
+            /^\/api\/datasets\/[^/]+\/(rename|pin)$/.test(path)) {
+            try {
+                const match = path.match(/^\/api\/datasets\/([^/]+)\/(rename|pin)$/);
+                const body = await readJSON(req);
+                const dataset = match[2] === "pin"
+                    ? datasetWorkspace.pin(decodeURIComponent(match[1]), body.pinned !== false)
+                    : datasetWorkspace.rename(decodeURIComponent(match[1]), String(body.name ?? ""), typeof body.alias === "string" ? body.alias : undefined);
+                recordDatasetMetadataSnapshot();
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({ dataset }));
+            }
+            catch (error) {
+                res.writeHead(400, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        if (req.method === "POST" &&
+            /^\/api\/datasets\/[^/]+\/schema$/.test(path)) {
+            try {
+                const id = decodeURIComponent(path.match(/^\/api\/datasets\/([^/]+)\/schema$/)?.[1] ?? "");
+                const body = await readJSON(req);
+                await ensureLocalWorkspaceReady();
+                const dataset = await datasetWorkspace.updateSchema(id, body.overrides && typeof body.overrides === "object"
+                    ? body.overrides
+                    : {});
+                recordDatasetMetadataSnapshot();
+                res.writeHead(200, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({ dataset }));
+            }
+            catch (error) {
+                res.writeHead(400, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        if (req.method === "DELETE" && /^\/api\/datasets\/[^/]+$/.test(path)) {
+            const id = decodeURIComponent(path.slice("/api/datasets/".length));
+            datasetWorkspace.remove(id);
+            recordDatasetMetadataSnapshot();
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === "POST" && path === "/api/datasets/stage") {
+            try {
+                const body = await readJSON(req);
+                if (body.confirmed !== true) {
+                    res.writeHead(428, {
+                        "Content-Type": "application/json; charset=utf-8",
+                    });
+                    res.end(serializeJSON({
+                        error: "Confirm the bounded local copy before staging warehouse data.",
+                    }));
+                    return;
+                }
+                const configured = projectConfig.notebook?.staging;
+                const maxRows = Math.max(1, Math.min(Number(body.maxRows ?? configured?.maxRows ?? 100_000), 500_000));
+                const maxBytes = Math.max(1_000_000, Math.min(Number(body.maxBytes ?? configured?.maxBytes ?? 250_000_000), 1_000_000_000));
+                const timeoutMs = Math.max(1_000, Math.min(Number(body.timeoutSeconds ?? configured?.timeoutSeconds ?? 120) *
+                    1000, 600_000));
+                const sql = typeof body.sql === "string" ? body.sql.trim() : "";
+                const validationError = readOnlySqlValidationError(sql, "Local staging");
+                if (validationError)
+                    throw new Error(validationError);
+                const semantic = prepareSemanticSql(sql, semanticLayer);
+                if (semantic.unresolvedRefs.length > 0)
+                    throw new Error(`Unknown semantic references: ${semantic.unresolvedRefs.join(", ")}`);
+                const named = typeof body.connectionName === "string"
+                    ? resolveNamedConnection(body.connectionName)
+                    : connection;
+                const sourceConnection = requireActiveConnection(named);
+                const prepared = prepareLocalExecution(`SELECT * FROM (${stripSqlTerminator(semantic.sql)}) AS dql_stage_source LIMIT ${maxRows + 1}`, sourceConnection, projectRoot, projectConfig);
+                const execution = executor.executeQuery(prepared.sql, [], runtimeVariables({}), prepared.connection);
+                const result = await Promise.race([
+                    execution,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Staging query exceeded ${Math.round(timeoutMs / 1000)} seconds.`)), timeoutMs)),
+                ]);
+                const rows = (result.rows ?? []);
+                if (rows.length > maxRows)
+                    throw new Error(`Staging would exceed the ${maxRows.toLocaleString()} row limit. Add filters or aggregate the warehouse query.`);
+                const rowPayload = serializeJSON(rows);
+                const byteCount = Buffer.byteLength(rowPayload);
+                if (byteCount > maxBytes)
+                    throw new Error(`Staging would exceed the ${(maxBytes / 1_000_000).toFixed(0)} MB limit. Add filters or aggregate the warehouse query.`);
+                await ensureLocalWorkspaceReady();
+                const dataset = await datasetWorkspace.stageRows({
+                    name: typeof body.name === "string" && body.name.trim()
+                        ? body.name.trim()
+                        : "Staged warehouse result",
+                    rows,
+                    expiresInDays: configured?.expiryDays ?? 7,
+                    lineage: {
+                        connectionName: typeof body.connectionName === "string"
+                            ? body.connectionName
+                            : projectConfig.defaultConnectionName,
+                        query: sql,
+                        blockPath: typeof body.blockPath === "string" ? body.blockPath : undefined,
+                        semanticMetrics: semantic.semanticRefs.metrics,
+                        semanticDimensions: semantic.semanticRefs.dimensions,
+                        filters: body.filters && typeof body.filters === "object"
+                            ? body.filters
+                            : undefined,
+                        parameters: body.parameters && typeof body.parameters === "object"
+                            ? body.parameters
+                            : undefined,
+                        extractedAt: new Date().toISOString(),
+                        rowCount: rows.length,
+                        byteCount,
+                        sourceFingerprint: createHash("sha256")
+                            .update(`${body.connectionName ?? projectConfig.defaultConnectionName ?? "default"}:${sql}`)
+                            .digest("hex"),
+                        resultFingerprint: createHash("sha256")
+                            .update(rowPayload)
+                            .digest("hex"),
+                    },
+                });
+                recordDatasetMetadataSnapshot();
+                res.writeHead(201, {
+                    "Content-Type": "application/json; charset=utf-8",
+                });
+                res.end(serializeJSON({
+                    dataset,
+                    limits: { maxRows, maxBytes, timeoutMs },
+                    trustLabel: "review_required",
+                }));
+            }
+            catch (error) {
+                res.writeHead(400, {
+                    "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/connectors/install') {
+        if (req.method === "POST" && path === "/api/connectors/install") {
             try {
                 const body = await readJSON(req);
                 const driver = typeof body.driver === 'string' ? body.driver : '';
@@ -6356,9 +8348,18 @@ export async function startLocalServer(opts) {
                 source: q.source ?? null,
             }));
             const provider = semanticConfig?.provider ?? semanticDetectedProvider ?? 'dql';
-            const dbtExecutionReady = provider === 'dbt'
+            const dbtManifestReady = provider === 'dbt'
                 ? hasDbtSemanticManifest(projectRoot, semanticConfig?.projectPath)
                 : false;
+            const metricFlowReady = provider === 'dbt' ? hasMetricFlowCli() : false;
+            const dbtExecutionReady = dbtManifestReady && metricFlowReady;
+            const dbtExecutionSetup = dbtExecutionReady
+                ? null
+                : !dbtManifestReady && !metricFlowReady
+                    ? 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists, and install MetricFlow so `mf` is on PATH.'
+                    : !dbtManifestReady
+                        ? 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists.'
+                        : 'Install MetricFlow so `mf` is on PATH, or set DQL_METRICFLOW_BIN to the MetricFlow executable.';
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
                 available: true,
@@ -6367,9 +8368,7 @@ export async function startLocalServer(opts) {
                     ? {
                         engine: 'metricflow',
                         ready: dbtExecutionReady,
-                        setup: dbtExecutionReady
-                            ? null
-                            : 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists, and install MetricFlow so `mf` is on PATH.',
+                        setup: dbtExecutionSetup,
                     }
                     : { engine: 'native', ready: true, setup: null },
                 errors: semanticLayerErrors,
@@ -6771,8 +8770,186 @@ export async function startLocalServer(opts) {
             }
             return;
         }
-        // ── Semantic completions for SQL cells ─────────────────────────────────────
-        if (req.method === 'GET' && path === '/api/semantic-completions') {
+        // ── Ranked, lazy editor completions (large-repo safe) ───────────────────────
+        if (req.method === "GET" && path === "/api/editor/completions") {
+            const query = (url.searchParams.get("q") ?? "").trim().toLowerCase();
+            const kind = (url.searchParams.get("kind") ?? "all").trim().toLowerCase();
+            const relationFilter = (url.searchParams.get("relation") ?? "")
+                .trim()
+                .toLowerCase();
+            const selectedDomain = (url.searchParams.get("domain") ?? "")
+                .trim()
+                .toLowerCase();
+            const limit = Math.max(1, Math.min(100, Number(url.searchParams.get("limit") ?? 50) || 50));
+            const recent = readUserPrefs(userPrefsPath).recentlyUsed.map((name) => name.toLowerCase());
+            const candidates = [];
+            if (semanticLayer && (kind === "all" || kind === "metric")) {
+                for (const metric of semanticLayer.listMetrics())
+                    candidates.push({
+                        type: "metric",
+                        name: metric.name,
+                        label: metric.label,
+                        description: metric.description ?? "",
+                        domain: metric.domain,
+                        tags: metric.tags ?? [],
+                        detail: "@metric",
+                        apply: metric.name,
+                        governance: "semantic",
+                    });
+            }
+            if (semanticLayer && (kind === "all" || kind === "dimension")) {
+                for (const dimension of semanticLayer.listDimensions())
+                    candidates.push({
+                        type: "dimension",
+                        name: dimension.name,
+                        label: dimension.label,
+                        description: dimension.description ?? "",
+                        domain: dimension.domain,
+                        tags: dimension.tags ?? [],
+                        detail: "@dim",
+                        apply: dimension.name,
+                        governance: "semantic",
+                    });
+            }
+            const datasets = datasetWorkspace.list();
+            if (kind === "all" || kind === "relation" || kind === "dataset") {
+                for (const dataset of datasets)
+                    candidates.push({
+                        type: kind === "dataset" ? "dataset" : "relation",
+                        name: dataset.alias,
+                        label: dataset.name,
+                        description: `${dataset.storageMode} ${dataset.format} · refreshed ${dataset.refreshedAt}`,
+                        relation: dataset.alias,
+                        detail: dataset.trustState,
+                        apply: `"${dataset.alias.replaceAll('"', '""')}"`,
+                        governance: dataset.trustState,
+                    });
+            }
+            if (kind === "all" || kind === "column") {
+                for (const dataset of datasets) {
+                    if (relationFilter &&
+                        ![dataset.id, dataset.alias, dataset.name].some((value) => value.toLowerCase() === relationFilter))
+                        continue;
+                    for (const column of dataset.profile.columns)
+                        candidates.push({
+                            type: "column",
+                            name: column.name,
+                            label: column.name,
+                            description: column.flags?.join(", ") ?? "",
+                            relation: dataset.alias,
+                            detail: column.type,
+                            apply: column.name,
+                            governance: dataset.trustState,
+                        });
+                }
+                const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+                for (const table of snapshot?.tables ?? []) {
+                    if (relationFilter &&
+                        ![table.relation, table.name]
+                            .filter(Boolean)
+                            .some((value) => value.toLowerCase() === relationFilter ||
+                            value.toLowerCase().endsWith(`.${relationFilter}`)))
+                        continue;
+                    for (const column of table.columns)
+                        candidates.push({
+                            type: "column",
+                            name: column.name,
+                            label: column.name,
+                            description: column.description ?? "",
+                            relation: table.relation,
+                            detail: column.type,
+                            apply: column.name,
+                            governance: "runtime_schema",
+                        });
+                }
+            }
+            if (kind === "all" || kind === "relation") {
+                const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+                for (const table of snapshot?.tables ?? [])
+                    candidates.push({
+                        type: "relation",
+                        name: table.relation,
+                        label: table.name ?? table.relation,
+                        description: table.description ?? "",
+                        relation: table.relation,
+                        detail: table.schema,
+                        apply: table.relation,
+                        governance: table.source ?? "runtime_schema",
+                    });
+            }
+            if (kind === "all" || kind === "block") {
+                for (const file of scanNotebookFiles(projectRoot).filter((entry) => entry.type === "block"))
+                    candidates.push({
+                        type: "block",
+                        name: file.name.replace(/\.dql$/i, ""),
+                        label: file.name.replace(/\.dql$/i, ""),
+                        description: file.path,
+                        detail: "@block",
+                        apply: `@block("${file.name.replace(/\.dql$/i, "")}")`,
+                        governance: file.path.includes("_draft") ? "draft" : "governed",
+                    });
+            }
+            if (kind === "all" || kind === "connection") {
+                for (const name of Object.keys(getStoredConnections(projectConfig)))
+                    candidates.push({
+                        type: "connection",
+                        name,
+                        label: name,
+                        description: "Configured connection",
+                        detail: name === projectConfig.defaultConnectionName
+                            ? "default"
+                            : undefined,
+                        apply: name,
+                    });
+            }
+            const uniqueCandidates = [
+                ...new Map(candidates.map((candidate) => [
+                    `${candidate.type}:${candidate.name.toLowerCase()}:${candidate.relation?.toLowerCase() ?? ""}`,
+                    candidate,
+                ])).values(),
+            ];
+            const scored = uniqueCandidates
+                .map((candidate) => {
+                const name = candidate.name.toLowerCase();
+                const label = candidate.label.toLowerCase();
+                const haystack = `${name} ${label} ${candidate.description.toLowerCase()} ${(candidate.tags ?? []).join(" ").toLowerCase()} ${candidate.domain?.toLowerCase() ?? ""}`;
+                let score = query
+                    ? name === query
+                        ? 100
+                        : name.startsWith(query)
+                            ? 80
+                            : label.startsWith(query)
+                                ? 70
+                                : haystack.includes(query)
+                                    ? 40
+                                    : 0
+                    : 10;
+                if (selectedDomain &&
+                    candidate.domain?.toLowerCase() === selectedDomain)
+                    score += 20;
+                if (recent.includes(name))
+                    score += 15;
+                if (candidate.governance === "certified" ||
+                    candidate.governance === "semantic" ||
+                    candidate.governance === "project_controlled")
+                    score += 10;
+                return { ...candidate, score };
+            })
+                .filter((candidate) => !query || (candidate.score ?? 0) > 0)
+                .sort((a, b) => (b.score ?? 0) - (a.score ?? 0) || a.name.localeCompare(b.name))
+                .slice(0, limit);
+            res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+            res.end(serializeJSON({
+                completions: scored,
+                query,
+                kind,
+                limit,
+                totalCandidates: uniqueCandidates.length,
+            }));
+            return;
+        }
+        // ── Legacy semantic completion endpoint ────────────────────────────────────
+        if (req.method === "GET" && path === "/api/semantic-completions") {
             const completions = [];
             if (semanticLayer) {
                 for (const m of semanticLayer.listMetrics()) {
@@ -6944,7 +9121,11 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ columns: [], rows: [], error: 'Missing SQL in request body.' }));
                     return;
                 }
-                const semantic = prepareSemanticSql(body.sql, semanticLayer);
+                const executionConnection = await resolveExecutionConnection(body);
+                const tableMapping = hasStandaloneSemanticRef(body.sql)
+                    ? await resolveSemanticTableMapping(executor, executionConnection, semanticLayer)
+                    : undefined;
+                const semantic = prepareSemanticSql(body.sql, semanticLayer, { tableMapping });
                 if (semantic.unresolvedRefs.length > 0) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
@@ -6956,7 +9137,7 @@ export async function startLocalServer(opts) {
                     }));
                     return;
                 }
-                const prepared = prepareLocalExecution(semantic.sql, requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection), projectRoot, projectConfig);
+                const prepared = prepareLocalExecution(semantic.sql, executionConnection, projectRoot, projectConfig);
                 const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
                 const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
                 assertAppAccess({ app, domain, level: 'execute' });
@@ -7214,6 +9395,10 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'name and at least one metric are required.' }));
                     return;
                 }
+                if (blockType === 'semantic' && dbtFirstOwnsSemanticAuthoring(projectConfig)) {
+                    sendDbtOwnedSemanticAuthoringError(res);
+                    return;
+                }
                 const targetConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
                 const composed = composeRuntimeSemanticQuery({
                     metrics,
@@ -7531,14 +9716,128 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ error: 'Missing file path.' }));
                 return;
             }
-            const filePath = safeJoin(projectRoot, relativePath);
-            if (!filePath || !existsSync(filePath) || statSync(filePath).isDirectory()) {
-                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ error: `File not found: ${relativePath}` }));
-                return;
+            const filePath = safeJoin(projectRoot, relativePath);
+            if (!filePath || !existsSync(filePath) || statSync(filePath).isDirectory()) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: `File not found: ${relativePath}` }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
+            res.end(readFileSync(filePath));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/dql/artifacts/execute') {
+            try {
+                const body = await readJSON(req);
+                const requestedArtifact = normalizeDqlArtifactReference(body.artifact);
+                const requestedBlockName = typeof body.blockName === 'string' ? body.blockName.trim() : '';
+                let source = requestedArtifact?.source ?? '';
+                let sourcePath = requestedArtifact?.sourcePath;
+                let blockName = requestedBlockName || requestedArtifact?.name;
+                let domain;
+                let chartType;
+                if (requestedBlockName) {
+                    const block = buildManifest({ projectRoot }).blocks[requestedBlockName];
+                    if (!block)
+                        throw new Error(`Block "${requestedBlockName}" was not found.`);
+                    source = readFileSync(join(projectRoot, block.filePath), 'utf-8');
+                    sourcePath = block.filePath;
+                    blockName = block.name;
+                    domain = block.domain;
+                    chartType = block.chartType;
+                }
+                else if (sourcePath) {
+                    const filePath = safeJoin(projectRoot, sourcePath);
+                    if (filePath && existsSync(filePath) && !statSync(filePath).isDirectory())
+                        source = readFileSync(filePath, 'utf-8');
+                }
+                if (!source.trim())
+                    throw new Error('Provide an executable DQL artifact or block name.');
+                const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
+                    ? body.parameters
+                    : requestedArtifact?.parameterValues ?? {};
+                const result = await executeDqlArtifactSourceForAgent(source, {
+                    name: blockName,
+                    path: sourcePath,
+                    domain,
+                    chartType,
+                }, {
+                    parameters,
+                    question: typeof body.question === 'string' ? body.question : undefined,
+                });
+                const contract = prepareBlockInvocation({ source, parameters, surface: 'ask_ai' });
+                const certified = /\bstatus\s*=\s*"certified"/i.test(source);
+                const semantic = /\btype\s*=\s*"semantic"/i.test(source);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    result,
+                    artifact: {
+                        ...(requestedArtifact ?? { kind: semantic ? 'semantic_block' : 'sql_block' }),
+                        source,
+                        ...(blockName ? { name: blockName } : {}),
+                        ...(sourcePath ? { sourcePath } : {}),
+                        parameters: contract.parameters,
+                        parameterValues: contract.values,
+                        persistence: sourcePath ? 'saved' : 'transient',
+                        trustState: certified ? 'certified' : semantic ? 'governed' : 'review_required',
+                        compiledSql: result.sql,
+                    },
+                }));
+            }
+            catch (error) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/blocks/parameters') {
+            try {
+                const blockName = url.searchParams.get('name')?.trim();
+                if (!blockName)
+                    throw new Error('Missing certified block name.');
+                const manifest = buildManifest({ projectRoot });
+                const block = manifest.blocks[blockName];
+                if (!block) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Block "${blockName}" was not found.` }));
+                    return;
+                }
+                if (block.status !== 'certified')
+                    throw new Error(`Block "${blockName}" is not certified.`);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    blockName: block.name,
+                    blockPath: block.filePath,
+                    parameters: block.parameters ?? [],
+                }));
+            }
+            catch (error) {
+                res.writeHead(400, { '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/blocks/invoke') {
+            try {
+                const body = await readJSON(req);
+                const blockName = typeof body.blockName === 'string' ? body.blockName.trim() : '';
+                if (!blockName)
+                    throw new Error('Missing certified block name.');
+                const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
+                    ? body.parameters
+                    : {};
+                const result = await executeCertifiedBlockByNameForAgent(blockName, { parameters, question: typeof body.question === 'string' ? body.question : undefined }, true);
+                const manifest = buildManifest({ projectRoot });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    result,
+                    parameters: manifest.blocks[blockName]?.parameters ?? [],
+                }));
+            }
+            catch (error) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
-            res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
-            res.end(readFileSync(filePath));
             return;
         }
         if (req.method === 'POST' && path === '/api/notebook/execute') {
@@ -7556,11 +9855,30 @@ export async function startLocalServer(opts) {
                 }
                 const resolved = resolveNotebookBlockReferenceCell(cell, projectRoot);
                 const executableCell = resolved.cell;
-                const cellConnection = requireActiveConnection(isConnectionConfig(body.connection) ? body.connection : connection);
+                const invocation = executableCell.type === 'dql'
+                    ? prepareBlockInvocation({
+                        source: executableCell.source,
+                        parameters: body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
+                            ? body.parameters
+                            : {},
+                        surface: 'notebook',
+                    })
+                    : null;
+                if (invocation?.errors.length)
+                    throw new Error(invocation.errors.join(' '));
+                if (invocation?.unresolvedParameters.length) {
+                    throw new Error(`Provide required parameter${invocation.unresolvedParameters.length === 1 ? '' : 's'}: ${invocation.unresolvedParameters.join(', ')}.`);
+                }
+                const cellConnection = await resolveExecutionConnection(body);
                 const tableMapping = needsSemanticTableMapping(executableCell)
                     ? await resolveSemanticTableMapping(executor, cellConnection, semanticLayer)
                     : undefined;
-                const plan = buildExecutionPlan(executableCell, { semanticLayer, driver: cellConnection.driver, tableMapping });
+                const plan = buildExecutionPlan(executableCell, {
+                    semanticLayer,
+                    driver: cellConnection.driver,
+                    tableMapping,
+                    parameters: invocation?.values,
+                });
                 if (!plan) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ cellType: cell.type, result: null }));
@@ -7569,7 +9887,7 @@ export async function startLocalServer(opts) {
                 const prepared = prepareLocalExecution(plan.sql, cellConnection, projectRoot, projectConfig);
                 const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
                 assertAppAccess({ app, domain: resolved.domain ?? app?.domain, level: 'execute' });
-                const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables(plan.variables), prepared.connection);
+                const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables({ ...plan.variables, ...(invocation?.values ?? {}) }), 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
@@ -7607,6 +9925,13 @@ export async function startLocalServer(opts) {
                     chartConfig: plan.chartConfig,
                     tests: plan.tests,
                     result: normalized,
+                    ...(invocation ? {
+                        invocation: {
+                            resolvedParameters: invocation.resolvedParameters,
+                            unresolvedParameters: invocation.unresolvedParameters,
+                            auditId: invocation.auditId,
+                        },
+                    } : {}),
                     ...(invariants
                         ? {
                             invariantResults: invariants.invariantResults,
@@ -7640,6 +9965,10 @@ export async function startLocalServer(opts) {
         // Create a new metric YAML file in semantic-layer/metrics/
         if (req.method === 'POST' && path === '/api/semantic-layer/metric') {
             try {
+                if (dbtFirstOwnsSemanticAuthoring(projectConfig)) {
+                    sendDbtOwnedSemanticAuthoringError(res);
+                    return;
+                }
                 const body = await readJSON(req);
                 const { name, label, description, domain, sql, type, table, tags } = body;
                 if (!name || !sql || !type || !table) {
@@ -7709,6 +10038,148 @@ table: ${table}${tagList}
         });
     });
 }
+async function validateModelingRelationship(relationship, manifest, execute, quoteIdentifier = quoteSqlIdentifier) {
+    const fromEntity = manifest.modeling?.entities[relationship.from];
+    const toEntity = manifest.modeling?.entities[relationship.to];
+    if (!fromEntity || !toEntity)
+        throw new Error('Both relationship entities must be bound to dbt models before validation.');
+    const fromNode = manifest.dbtProvenance?.nodes[fromEntity.dbtUniqueId];
+    const toNode = manifest.dbtProvenance?.nodes[toEntity.dbtUniqueId];
+    if (!fromNode?.relation || !toNode?.relation)
+        throw new Error('Both dbt models must expose warehouse relation names.');
+    if (!relationship.keys.length)
+        throw new Error('At least one join key pair is required.');
+    const safeQuote = (identifier) => quoteIdentifier(assertSafeSqlIdentifier(identifier));
+    const fromRelation = quoteQualifiedIdentifier(fromNode.relation, safeQuote);
+    const toRelation = quoteQualifiedIdentifier(toNode.relation, safeQuote);
+    const fromNull = relationship.keys.map((key) => `f.${safeQuote(key.from)} IS NULL`).join(' OR ');
+    const toNull = relationship.keys.map((key) => `t.${safeQuote(key.to)} IS NULL`).join(' OR ');
+    const join = relationship.keys.map((key) => `f.${safeQuote(key.from)} = t.${safeQuote(key.to)}`).join(' AND ');
+    const fromKeys = relationship.keys.map((key) => safeQuote(key.from)).join(', ');
+    const toKeys = relationship.keys.map((key) => safeQuote(key.to)).join(', ');
+    const firstToKey = safeQuote(relationship.keys[0].to);
+    const sql = `WITH
+from_counts AS (SELECT COUNT(*) AS rows, SUM(CASE WHEN ${fromNull} THEN 1 ELSE 0 END) AS null_keys FROM ${fromRelation} f),
+to_counts AS (SELECT COUNT(*) AS rows, SUM(CASE WHEN ${toNull} THEN 1 ELSE 0 END) AS null_keys FROM ${toRelation} t),
+from_max AS (SELECT COALESCE(MAX(key_count), 0) AS max_per_key FROM (SELECT COUNT(*) AS key_count FROM ${fromRelation} GROUP BY ${fromKeys}) x),
+to_max AS (SELECT COALESCE(MAX(key_count), 0) AS max_per_key FROM (SELECT COUNT(*) AS key_count FROM ${toRelation} GROUP BY ${toKeys}) x),
+joined AS (SELECT COUNT(*) AS rows FROM ${fromRelation} f JOIN ${toRelation} t ON ${join}),
+unmatched AS (SELECT COUNT(*) AS rows FROM ${fromRelation} f LEFT JOIN ${toRelation} t ON ${join} WHERE t.${firstToKey} IS NULL)
+SELECT from_counts.rows AS from_rows, to_counts.rows AS to_rows, joined.rows AS joined_rows,
+  from_counts.null_keys AS from_null_keys, to_counts.null_keys AS to_null_keys,
+  unmatched.rows AS unmatched_from, from_max.max_per_key AS max_from_per_key, to_max.max_per_key AS max_to_per_key
+FROM from_counts, to_counts, joined, unmatched, from_max, to_max`;
+    const result = await execute(sql);
+    const row = result.rows[0] ?? {};
+    const maxFromPerKey = numericValue(row.max_from_per_key);
+    const maxToPerKey = numericValue(row.max_to_per_key);
+    const cardinalityPassed = relationship.cardinality === 'one_to_one'
+        ? maxFromPerKey <= 1 && maxToPerKey <= 1
+        : relationship.cardinality === 'one_to_many'
+            ? maxFromPerKey <= 1
+            : relationship.cardinality === 'many_to_one'
+                ? maxToPerKey <= 1
+                : false;
+    const policyPassed = relationship.fanout === 'safe' && cardinalityPassed;
+    const queryFingerprint = createHash('sha256').update(sql).digest('hex');
+    return {
+        status: policyPassed ? 'passed' : 'failed',
+        checkedAt: new Date().toISOString(),
+        queryFingerprint,
+        proofFingerprint: relationshipValidationProofFingerprint({
+            fromRelation: fromNode.relation,
+            toRelation: toNode.relation,
+            keys: relationship.keys,
+            cardinality: relationship.cardinality,
+            fanout: relationship.fanout,
+            queryFingerprint,
+        }),
+        fromRows: numericValue(row.from_rows),
+        toRows: numericValue(row.to_rows),
+        joinedRows: numericValue(row.joined_rows),
+        fromNullKeys: numericValue(row.from_null_keys),
+        toNullKeys: numericValue(row.to_null_keys),
+        unmatchedFrom: numericValue(row.unmatched_from),
+        maxFromPerKey,
+        maxToPerKey,
+        message: policyPassed
+            ? 'Warehouse evidence matches the declared cardinality and safe fanout policy.'
+            : 'Warehouse evidence does not prove the declared cardinality and safe fanout policy.',
+    };
+}
+function relatedProductsForDomain(manifest, domainId) {
+    const apps = Object.values(manifest.apps ?? {})
+        .filter((app) => app.ownerDomain === domainId || app.usesDomains.includes(domainId))
+        .map((app) => ({
+        id: app.id,
+        name: app.name,
+        filePath: app.filePath,
+        ownerDomain: app.ownerDomain ?? app.domain,
+        usesDomains: app.usesDomains,
+        purpose: app.purpose,
+        requiredExports: app.requiredExports,
+        classification: app.classification,
+        lifecycle: app.lifecycle,
+        legacyLayout: app.filePath.startsWith('domains/'),
+    }));
+    const notebooks = Object.entries(manifest.notebooks)
+        .filter(([, notebook]) => notebook.ownerDomain === domainId || notebook.usesDomains.includes(domainId))
+        .map(([id, notebook]) => ({
+        id,
+        title: notebook.title,
+        filePath: notebook.filePath,
+        ownerDomain: notebook.ownerDomain,
+        usesDomains: notebook.usesDomains,
+        purpose: notebook.purpose,
+        requiredExports: notebook.requiredExports,
+        classification: notebook.classification,
+        legacyLayout: notebook.filePath.startsWith('domains/'),
+    }));
+    return { apps, notebooks };
+}
+function domainWorkspaceSummary(manifest, domainId) {
+    const pkg = manifest.modeling?.packages[domainId];
+    const entities = Object.values(manifest.modeling?.entities ?? {}).filter((entity) => entity.domain === domainId);
+    const entityKeys = new Set(Object.entries(manifest.modeling?.entities ?? {}).filter(([, entity]) => entity.domain === domainId).map(([key]) => key));
+    const relationships = Object.values(manifest.modeling?.relationships ?? {}).filter((relationship) => entityKeys.has(relationship.from) || entityKeys.has(relationship.to));
+    const contracts = Object.values(manifest.modeling?.contracts ?? {}).filter((contract) => contract.domain === domainId);
+    const imports = Object.values(manifest.modeling?.interfaces?.imports ?? {}).filter((value) => value.domain === domainId);
+    const exports = Object.values(manifest.modeling?.interfaces?.exports ?? {}).filter((value) => value.domain === domainId);
+    return {
+        id: domainId,
+        parent: pkg?.parent,
+        owner: pkg?.owner,
+        filePath: pkg?.filePath,
+        counts: {
+            entities: entities.length,
+            relationships: relationships.length,
+            safeRelationships: relationships.filter((relationship) => relationship.automaticJoinAllowed).length,
+            staleRelationships: relationships.filter((relationship) => relationship.staleCertification).length,
+            contracts: contracts.length,
+            imports: imports.length,
+            exports: exports.length,
+            relatedProducts: Object.values(relatedProductsForDomain(manifest, domainId)).reduce((sum, values) => sum + values.length, 0),
+        },
+        readiness: relationships.some((relationship) => relationship.staleCertification) ? 'attention' : entities.length > 0 ? 'ready' : 'setup',
+    };
+}
+function quoteQualifiedIdentifier(value, quote = quoteSqlIdentifier) {
+    return value.split('.').map((part) => quote(assertSafeSqlIdentifier(part))).join('.');
+}
+function quoteSqlIdentifier(value) {
+    return `"${value.replace(/"/g, '""')}"`;
+}
+function assertSafeSqlIdentifier(value) {
+    if (!value || !/^[A-Za-z_][A-Za-z0-9_$]*$/.test(value))
+        throw new Error(`Unsafe SQL identifier: ${value}`);
+    return value;
+}
+function numericValue(value) {
+    if (typeof value === 'bigint')
+        return Number(value);
+    const numeric = Number(value ?? 0);
+    return Number.isFinite(numeric) ? numeric : 0;
+}
 export async function assertLocalQueryRuntimeReady(executor, connection) {
     try {
         const connector = await executor.getConnector(connection);
@@ -8010,6 +10481,7 @@ function serializeSkill(skill) {
         user: undefined,
         domain: skill.domain,
         domains: skill.domains,
+        modelAreaRefs: skill.modelAreaRefs,
         kind: skill.kind,
         status: skill.status,
         owner: skill.owner,
@@ -8063,6 +10535,7 @@ function parseSkillInput(raw, fallbackId) {
         user: undefined,
         domain: typeof skill.domain === 'string' && skill.domain.trim() ? skill.domain.trim() : undefined,
         domains: asStrings(skill.domains),
+        modelAreaRefs: asStrings(skill.modelAreaRefs),
         kind: skill.kind === 'domain_reference' || skill.kind === 'metric_policy' || skill.kind === 'glossary' || skill.kind === 'analysis_pattern' || skill.kind === 'sql_policy' ? skill.kind : 'custom',
         status: skill.status === 'draft' || skill.status === 'deprecated' ? skill.status : 'active',
         owner: typeof skill.owner === 'string' ? skill.owner : undefined,
@@ -8089,7 +10562,7 @@ function domainKey(value) {
 }
 function manifestDomainToDto(domain, counts) {
     return {
-        id: domain.name,
+        id: domain.id ?? domain.name,
         name: domain.name,
         parent: domain.parent,
         owner: domain.owner,
@@ -8139,7 +10612,7 @@ export function listDomains(projectRoot) {
     }
     return Object.values(domains)
         .map((domain) => {
-        const key = domainKey(domain.name);
+        const key = domainKey(domain.id ?? domain.name);
         return manifestDomainToDto(domain, {
             blockCount: blockCounts.get(key) ?? 0,
             skillCount: skillCounts.get(key) ?? 0,
@@ -8151,7 +10624,56 @@ export function listDomains(projectRoot) {
 /** 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);
+    return listDomains(projectRoot).find((domain) => domainKey(domain.id) === key || domainKey(domain.name) === key);
+}
+function deleteCanonicalDomainDeclaration(projectRoot, nameOrId) {
+    const registry = loadDomainPackageRegistry(projectRoot);
+    const key = domainKey(nameOrId);
+    const pkg = registry.values().find((candidate) => domainKey(candidate.id) === key || domainKey(candidate.name) === key);
+    if (!pkg)
+        return false;
+    const declaration = join(projectRoot, pkg.declarationPath);
+    if (existsSync(declaration))
+        rmSync(declaration, { force: true });
+    if (pkg.legacyYamlPath) {
+        const legacy = join(projectRoot, pkg.legacyYamlPath);
+        if (existsSync(legacy))
+            rmSync(legacy, { force: true });
+    }
+    return true;
+}
+async function refreshUnifiedProjectIndexes(projectRoot) {
+    const dbtManifestPath = resolveDbtManifestPath(projectRoot) ?? undefined;
+    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook', dbtManifestPath });
+    invalidateAgentProjectState(projectRoot);
+    await reindexProject(projectRoot, {
+        manifest,
+        kgPath: defaultKgPath(projectRoot),
+        forceMetadataCatalog: true,
+        forceKgIndex: true,
+    });
+}
+function collectDomainPackageAssets(projectRoot, registry) {
+    const output = {};
+    for (const pkg of registry.values())
+        output[pkg.id] = {};
+    for (const path of listProjectFiles(projectRoot).filter((candidate) => candidate.startsWith('domains/'))) {
+        const pkg = registry.packageForPath(join(projectRoot, path));
+        if (!pkg || path === pkg.declarationPath)
+            continue;
+        const local = relative(pkg.root, join(projectRoot, path)).replace(/\\/g, '/');
+        const top = local.split('/')[0] ?? '';
+        const kind = top === 'business-views' ? 'views' : top;
+        if (!['terms', 'skills', 'blocks', 'views', 'notebooks', 'apps', 'evaluations', 'tests'].includes(kind))
+            continue;
+        const bucket = output[pkg.id] ?? (output[pkg.id] = {});
+        (bucket[kind] ??= []).push(path);
+    }
+    for (const assets of Object.values(output)) {
+        for (const paths of Object.values(assets))
+            paths.sort();
+    }
+    return output;
 }
 /** Validate + normalize an inbound `{ domain }` body into a DomainInput. */
 export function parseDomainInput(raw, fallbackId) {
@@ -8169,6 +10691,7 @@ export function parseDomainInput(raw, fallbackId) {
         ? value.filter((v) => typeof v === 'string' && v.trim().length > 0)
         : undefined;
     return {
+        id: typeof domain.id === 'string' && domain.id.trim() ? domain.id.trim() : domainFolderSlug(name).replace(/-/g, '_'),
         name,
         parent: typeof domain.parent === 'string' ? domain.parent : undefined,
         owner: typeof domain.owner === 'string' ? domain.owner : undefined,
@@ -8405,6 +10928,29 @@ export function loadProjectConfig(projectRoot) {
     }
     return config;
 }
+/** Current Git-backed Skills folder and what the loader can read from it. */
+export function buildSkillPathSettings(projectRoot) {
+    const resolvedPath = skillsDir(projectRoot);
+    const loaded = loadSkills(projectRoot);
+    return {
+        path: configuredSkillsPath(projectRoot),
+        resolvedPath,
+        exists: existsSync(resolvedPath) && statSync(resolvedPath).isDirectory(),
+        skillCount: loaded.skills.filter((skill) => skill.scope === 'project').length,
+        errorCount: loaded.errors.length,
+    };
+}
+function dbtFirstOwnsSemanticAuthoring(config) {
+    return config.manifestVersion === 3 && config.modeling?.mode === 'dbt-first';
+}
+function sendDbtOwnedSemanticAuthoringError(res) {
+    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(serializeJSON({
+        error: 'dbt-first projects use dbt/MetricFlow as the physical and metric source of truth. Edit the dbt project and refresh artifacts instead of creating duplicate local semantic definitions.',
+        code: 'DQL_MODELING_DBT_OWNED',
+        nextAction: 'Create or edit the metric in dbt/MetricFlow, run dbt parse or dbt build, then run dql sync dbt.',
+    }));
+}
 /**
  * Core of the `/api/propose` endpoint, factored out as a pure function so it can
  * be unit-tested without standing up an HTTP server.
@@ -9359,6 +11905,38 @@ export function dashboardRuntimeVariables(dashboard, overrides = {}) {
     }
     return { ...variables, ...overrides };
 }
+/**
+ * Resolve only declared tile parameter bindings.  Dashboard filters remain
+ * values; they never become SQL identifiers or an implicit name-based binding.
+ */
+export function dashboardTileParameterValues(input) {
+    const values = {};
+    const requestValues = input.requestValues ?? {};
+    const persona = requestValues.persona && typeof requestValues.persona === 'object' && !Array.isArray(requestValues.persona)
+        ? requestValues.persona
+        : {};
+    for (const binding of input.item.parameterBindings ?? []) {
+        const lookup = binding.filter ?? binding.field ?? binding.param;
+        let value;
+        switch (binding.source) {
+            case 'constant':
+                value = binding.value;
+                break;
+            case 'dashboard_filter':
+                value = input.dashboardValues[lookup];
+                break;
+            case 'persona':
+                value = persona[lookup] ?? requestValues[`persona.${lookup}`];
+                break;
+            case 'variable':
+                value = requestValues[lookup];
+                break;
+        }
+        if (value !== undefined)
+            values[binding.param] = value;
+    }
+    return values;
+}
 export function applyDashboardFiltersToBlockExecution(input) {
     const variables = { ...input.variables };
     const sqlParams = [...input.sqlParams];
@@ -9723,6 +12301,297 @@ export function buildAgentPreviewSql(sql) {
         throw new Error(readOnlyError);
     return `SELECT * FROM (\n${withoutTrailingSemicolon}\n) AS dql_agent_preview LIMIT 200`;
 }
+/**
+ * EXP-001 preflight for model-authored exploratory SQL.
+ *
+ * This is deliberately narrow and deterministic: it repairs a singular/plural
+ * qualifier typo only when it resolves to exactly one relation already present
+ * in the query, and it changes SUM to MAX for a non-additive parent attribute
+ * only when the owning entity is retained in GROUP BY. It never invents a
+ * relation, join key, or allocation rule.
+ */
+export function repairExploratorySqlBeforeExecution(sql, schemaContext, question = '') {
+    const repairs = [];
+    let repairedSql = qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs);
+    repairedSql = repairExploratoryRelationQualifiers(repairedSql, repairs);
+    repairedSql = repairExploratoryLifetimeMeasureSelection(repairedSql, schemaContext, question, repairs);
+    repairedSql = repairExploratoryMisleadingPercentAliases(repairedSql, question, repairs);
+    const grainRepair = repairExploratoryNonAdditiveAggregates(repairedSql, schemaContext, repairs);
+    repairedSql = grainRepair.sql;
+    return {
+        sql: repairedSql,
+        repairs,
+        ...(grainRepair.blockedReason ? { blockedReason: grainRepair.blockedReason } : {}),
+    };
+}
+/**
+ * Prevent a generated amount/count from being presented as a percentage.
+ * The repair is intentionally conservative: percent-intent questions and
+ * expressions that visibly calculate a ratio/percentage are left untouched.
+ */
+function repairExploratoryMisleadingPercentAliases(sql, question, repairs) {
+    if (/\b(percent(?:age)?|pct|share|ratio|rate|proportion)\b/i.test(question))
+        return sql;
+    const aggregateAlias = /((?:SUM|AVG|COUNT|MIN|MAX)\s*\([^)]*\))\s+AS\s+([a-zA-Z_][a-zA-Z0-9_]*?)(?:_pct|_percent|_percentage)\b/gi;
+    const aliases = new Map();
+    for (const match of sql.matchAll(aggregateAlias)) {
+        const expression = match[1];
+        const oldAlias = match[0].match(/\bAS\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*$/i)?.[1];
+        const newAlias = match[2];
+        if (!oldAlias || !newAlias)
+            continue;
+        if (/\/|\bpercent(?:age)?\b|\bratio\b|\brate\b|\*\s*100\b|\b100\s*\*/i.test(expression))
+            continue;
+        aliases.set(oldAlias, newAlias);
+    }
+    let repaired = sql;
+    for (const [oldAlias, newAlias] of aliases) {
+        repaired = repaired.replace(new RegExp(`\\b${escapeExploratoryRegex(oldAlias)}\\b`, 'g'), newAlias);
+        repairs.push(`Renamed misleading percentage alias ${oldAlias} to ${newAlias}; the expression returns an amount, not a percentage.`);
+    }
+    return repaired;
+}
+/**
+ * EXP-003 — make the typed overall ranking contract executable before the host
+ * runs a review-required exploratory candidate. The answer-shape gate remains a
+ * backstop, but a provider's generic LIMIT 100 must not trigger a second model
+ * call when the planner already established top 10.
+ */
+export function applyRequestedTopNToExploratorySql(sql, requestedTopN) {
+    if (!Number.isInteger(requestedTopN) || requestedTopN <= 0)
+        return sql;
+    const withoutTerminator = sql.trim().replace(/;\s*$/, '');
+    const trailingLimit = /\blimit\s+\d+\s*$/i;
+    if (trailingLimit.test(withoutTerminator)) {
+        return withoutTerminator.replace(trailingLimit, `LIMIT ${requestedTopN}`);
+    }
+    return `${withoutTerminator}\nLIMIT ${requestedTopN}`;
+}
+function qualifyExploratoryRelationsFromSchema(sql, schemaContext, repairs) {
+    const analysis = analyzeSqlReferences(sql);
+    if (!analysis.parsed)
+        return sql;
+    let repaired = sql;
+    for (const relation of analysis.tables) {
+        const cleanRelation = relation.replace(/["`\[\]]/g, '');
+        if (cleanRelation.includes('.'))
+            continue;
+        const basename = cleanRelation.toLowerCase();
+        const candidates = schemaContext
+            .map((table) => table.relation)
+            .filter((candidate) => (candidate.split('.').at(-1) ?? candidate).toLowerCase() === basename)
+            .filter((candidate, index, values) => values.indexOf(candidate) === index);
+        if (candidates.length === 0)
+            continue;
+        const compatible = candidates.every((candidate) => candidates.every((other) => candidate.toLowerCase() === other.toLowerCase()
+            || candidate.toLowerCase().endsWith(`.${other.toLowerCase()}`)
+            || other.toLowerCase().endsWith(`.${candidate.toLowerCase()}`)));
+        if (!compatible)
+            continue;
+        const replacement = [...candidates].sort((left, right) => right.split('.').length - left.split('.').length)[0];
+        if (replacement.toLowerCase() === basename)
+            continue;
+        repaired = repaired.replace(new RegExp(`\\b(from|join)\\s+${escapeExploratoryRegex(cleanRelation)}\\b`, 'gi'), (_match, keyword) => `${keyword} ${replacement}`);
+        repairs.push(`Qualified exploratory relation ${cleanRelation} as inspected relation ${replacement}.`);
+    }
+    return repaired;
+}
+function repairExploratoryRelationQualifiers(sql, repairs) {
+    const analysis = analyzeSqlReferences(sql);
+    if (!analysis.parsed)
+        return sql;
+    const declared = Object.entries(analysis.aliasToRelation).map(([qualifier, relation]) => ({
+        qualifier,
+        subject: normalizeExploratoryRelationSubject(relation.split('.').at(-1) ?? relation),
+    }));
+    let repaired = sql;
+    const unresolved = analysis.columns
+        .filter((column) => column.tableAlias && column.relation === column.tableAlias && !analysis.aliasToRelation[column.tableAlias])
+        .map((column) => column.tableAlias)
+        .filter((value, index, values) => values.indexOf(value) === index);
+    for (const qualifier of unresolved) {
+        const subject = normalizeExploratoryRelationSubject(qualifier);
+        const matches = declared.filter((candidate) => candidate.subject === subject);
+        if (matches.length !== 1 || matches[0].qualifier === qualifier)
+            continue;
+        const replacement = matches[0].qualifier;
+        repaired = repaired.replace(new RegExp(`\\b${escapeExploratoryRegex(qualifier)}\\s*\\.`, 'gi'), `${replacement}.`);
+        repairs.push(`Corrected unresolved SQL qualifier ${qualifier} to the inspected relation alias ${replacement}.`);
+    }
+    return repaired;
+}
+function repairExploratoryLifetimeMeasureSelection(sql, schemaContext, question, repairs) {
+    if (!/\b(lifetime|life\s*span|lifespan|customer\s+life)\b/i.test(question))
+        return sql;
+    const analysis = analyzeSqlReferences(sql);
+    if (!analysis.parsed || analysis.joins.length === 0)
+        return sql;
+    const groupClause = sql.match(/\bgroup\s+by\s+([\s\S]*?)(?:\border\s+by\b|\blimit\b|\bqualify\b|\bhaving\b|$)/i)?.[1] ?? '';
+    let repaired = sql;
+    for (const aggregate of analysis.aggregates) {
+        if (aggregate.func.toLowerCase() !== 'sum' || !aggregate.column)
+            continue;
+        const lifetimeColumn = `lifetime_${aggregate.column.toLowerCase()}`;
+        const owner = resolveUniqueExploratoryColumnOwner(schemaContext, lifetimeColumn);
+        if (!owner)
+            continue;
+        const ownerAliases = Object.entries(analysis.aliasToRelation)
+            .filter(([, relation]) => exploratoryRelationsMatch(relation, owner.relation))
+            .map(([alias]) => alias);
+        const ownerRetained = owner.columns.some((ownerColumn) => new RegExp(`(?:^|[^A-Za-z0-9_$])${escapeExploratoryRegex(ownerColumn.name)}(?:[^A-Za-z0-9_$]|$)`, 'i').test(groupClause));
+        if (!ownerRetained || ownerAliases.length === 0)
+            continue;
+        const sourcePattern = new RegExp(`\\bsum\\s*\\(\\s*(?:[A-Za-z_][A-Za-z0-9_$]*\\s*\\.\\s*)?${escapeExploratoryRegex(aggregate.column)}\\s*\\)`, 'gi');
+        if (!sourcePattern.test(repaired))
+            continue;
+        repaired = repaired.replace(sourcePattern, `MAX(${ownerAliases[0]}.${lifetimeColumn})`);
+        repairs.push(`Used ${lifetimeColumn} from ${owner.name} at the retained entity grain instead of multiplying ${aggregate.column} across lower-grain joined rows.`);
+    }
+    return repaired;
+}
+function repairExploratoryNonAdditiveAggregates(sql, schemaContext, repairs) {
+    const analysis = analyzeSqlReferences(sql);
+    if (!analysis.parsed || analysis.joins.length === 0)
+        return { sql };
+    const risky = analysis.aggregates.filter((aggregate) => aggregate.func.toLowerCase() === 'sum'
+        && Boolean(aggregate.column)
+        && /(^|_)(lifetime|cumulative|balance|snapshot|rate|ratio|average|avg)(_|$)/i.test(aggregate.column));
+    if (risky.length === 0)
+        return { sql };
+    const groupClause = sql.match(/\bgroup\s+by\s+([\s\S]*?)(?:\border\s+by\b|\blimit\b|\bqualify\b|\bhaving\b|$)/i)?.[1] ?? '';
+    let repaired = sql;
+    for (const aggregate of risky) {
+        const column = aggregate.column;
+        const owner = resolveUniqueExploratoryColumnOwner(schemaContext, column);
+        if (!owner) {
+            return {
+                sql: repaired,
+                blockedReason: `The exploratory query sums non-additive measure ${column} after a join, but DQL cannot prove its owning grain. Clarify the desired allocation or keep the owning entity in the result.`,
+            };
+        }
+        const ownerAliases = Object.entries(analysis.aliasToRelation)
+            .filter(([, relation]) => exploratoryRelationsMatch(relation, owner.relation))
+            .map(([alias]) => alias);
+        const ownerRetained = owner.columns.some((ownerColumn) => {
+            const name = escapeExploratoryRegex(ownerColumn.name);
+            if (new RegExp(`(?:^|[^A-Za-z0-9_$])${name}(?:[^A-Za-z0-9_$]|$)`, 'i').test(groupClause))
+                return true;
+            return ownerAliases.some((alias) => new RegExp(`\\b${escapeExploratoryRegex(alias)}\\s*\\.\\s*${name}\\b`, 'i').test(groupClause));
+        });
+        if (!ownerRetained) {
+            return {
+                sql: repaired,
+                blockedReason: `The exploratory query would allocate non-additive measure ${column} below its owning ${owner.name} grain. Keep ${owner.name} in the output or provide an allocation policy.`,
+            };
+        }
+        const sumPattern = new RegExp(`\\bsum\\s*\\(\\s*((?:[A-Za-z_][A-Za-z0-9_$]*\\s*\\.\\s*)?${escapeExploratoryRegex(column)})\\s*\\)`, 'gi');
+        if (!sumPattern.test(repaired))
+            continue;
+        repaired = repaired.replace(sumPattern, 'MAX($1)');
+        repairs.push(`Preserved non-additive ${column} at ${owner.name} grain instead of summing repeated values after the join.`);
+    }
+    return { sql: repaired };
+}
+function resolveUniqueExploratoryColumnOwner(schemaContext, column) {
+    const candidates = schemaContext.filter((table) => table.columns.some((candidate) => candidate.name.toLowerCase() === column.toLowerCase()));
+    if (candidates.length === 0)
+        return undefined;
+    const compatible = candidates.every((candidate) => candidates.every((other) => exploratoryRelationsMatch(candidate.relation, other.relation)));
+    if (!compatible)
+        return undefined;
+    const preferred = [...candidates].sort((left, right) => right.relation.split('.').length - left.relation.split('.').length)[0];
+    const columns = new Map();
+    for (const candidate of candidates) {
+        for (const candidateColumn of candidate.columns)
+            columns.set(candidateColumn.name.toLowerCase(), candidateColumn);
+    }
+    return { ...preferred, columns: [...columns.values()] };
+}
+function normalizeExploratoryRelationSubject(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9_]/g, '');
+    if (normalized.endsWith('ies') && normalized.length > 4)
+        return `${normalized.slice(0, -3)}y`;
+    if (normalized.endsWith('s') && normalized.length > 3)
+        return normalized.slice(0, -1);
+    return normalized;
+}
+function exploratoryRelationsMatch(left, right) {
+    const leftLower = left.toLowerCase();
+    const rightLower = right.toLowerCase();
+    return leftLower === rightLower
+        || leftLower.endsWith(`.${rightLower}`)
+        || rightLower.endsWith(`.${leftLower}`)
+        || normalizeExploratoryRelationSubject(leftLower.split('.').at(-1) ?? leftLower)
+            === normalizeExploratoryRelationSubject(rightLower.split('.').at(-1) ?? rightLower);
+}
+function escapeExploratoryRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Render parser-derived physical identifiers only; exploratory probes never interpolate arbitrary SQL. */
+function quoteExploratoryIdentifier(value, label) {
+    const parts = value
+        .replace(/["`\[\]]/g, '')
+        .split('.')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (parts.length === 0 || parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_$]*$/.test(part))) {
+        throw new Error(`Exploratory ${label} is not a safe physical identifier.`);
+    }
+    return parts.map((part) => `"${part.replace(/"/g, '""')}"`).join('.');
+}
+/** One bounded, sampled relationship observation per inferred equality join. */
+export function buildExploratoryJoinProbeSql(input) {
+    const leftRelation = quoteExploratoryIdentifier(input.leftRelation, 'left relation');
+    const leftColumn = quoteExploratoryIdentifier(input.leftColumn, 'left column');
+    const rightRelation = quoteExploratoryIdentifier(input.rightRelation, 'right relation');
+    const rightColumn = quoteExploratoryIdentifier(input.rightColumn, 'right column');
+    return `WITH
+  left_sample AS (
+    SELECT ${leftColumn} AS join_key
+    FROM ${leftRelation}
+    WHERE ${leftColumn} IS NOT NULL
+    LIMIT 5000
+  ),
+  right_sample AS (
+    SELECT ${rightColumn} AS join_key
+    FROM ${rightRelation}
+    WHERE ${rightColumn} IS NOT NULL
+    LIMIT 5000
+  ),
+  matches AS (
+    SELECT l.join_key AS left_key, r.join_key AS right_key
+    FROM left_sample AS l
+    INNER JOIN right_sample AS r ON l.join_key = r.join_key
+  ),
+  left_counts AS (
+    SELECT left_key, COUNT(*) AS match_count
+    FROM matches
+    GROUP BY left_key
+  ),
+  right_counts AS (
+    SELECT right_key, COUNT(*) AS match_count
+    FROM matches
+    GROUP BY right_key
+  )
+SELECT
+  (SELECT COUNT(*) FROM left_sample) AS left_sample_rows,
+  (SELECT COUNT(*) FROM right_sample) AS right_sample_rows,
+  (SELECT COUNT(*) FROM matches) AS joined_rows,
+  (SELECT COUNT(*) FROM left_sample AS l WHERE NOT EXISTS (SELECT 1 FROM right_sample AS r WHERE r.join_key = l.join_key)) AS unmatched_left_sample_rows,
+  (SELECT COUNT(*) FROM right_sample AS r WHERE NOT EXISTS (SELECT 1 FROM left_sample AS l WHERE l.join_key = r.join_key)) AS unmatched_right_sample_rows,
+  (SELECT COALESCE(MAX(match_count), 0) FROM left_counts) AS max_matches_per_left_key,
+  (SELECT COALESCE(MAX(match_count), 0) FROM right_counts) AS max_matches_per_right_key`;
+}
+function summarizeExploratoryJoinProbe(rows, leftRelation, leftColumn, rightRelation, rightColumn) {
+    const row = Array.isArray(rows) && rows[0] && typeof rows[0] === 'object'
+        ? rows[0]
+        : {};
+    const number = (key) => {
+        const value = Number(row[key]);
+        return Number.isFinite(value) ? value : 0;
+    };
+    return `${leftRelation}.${leftColumn} ↔ ${rightRelation}.${rightColumn}: sample left=${number('left_sample_rows')}, right=${number('right_sample_rows')}, joined=${number('joined_rows')}, unmatched left/right=${number('unmatched_left_sample_rows')}/${number('unmatched_right_sample_rows')}, max matches left/right=${number('max_matches_per_left_key')}/${number('max_matches_per_right_key')}`;
+}
 function readOnlySqlValidationError(sql, subject) {
     const scanSql = stripSqlStringsAndComments(sql).trim();
     if (!/^(select|with)\b/i.test(scanSql)) {
@@ -9793,11 +12662,11 @@ function stripSqlStringsAndComments(sql) {
  * Used by notebook SQL execution and Block Studio validation so both paths
  * behave identically. If the SQL has no refs, returns it unchanged.
  */
-export function prepareSemanticSql(sql, semanticLayer) {
+export function prepareSemanticSql(sql, semanticLayer, options) {
     if (!hasSemanticRefs(sql)) {
         return { sql, semanticRefs: { metrics: [], dimensions: [] }, unresolvedRefs: [] };
     }
-    const resolution = resolveSemanticRefs(sql, semanticLayer);
+    const resolution = resolveSemanticRefs(sql, semanticLayer, options);
     return {
         sql: resolution.resolvedSql,
         semanticRefs: {
@@ -9870,6 +12739,34 @@ function readJSON(req) {
         req.on('error', reject);
     });
 }
+async function readMultipartForm(req) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value))
+            value.forEach((item) => headers.append(key, item));
+        else if (value !== undefined)
+            headers.set(key, value);
+    }
+    const request = new Request("http://127.0.0.1/upload", {
+        method: "POST",
+        headers,
+        body: Readable.toWeb(req),
+        duplex: "half",
+    });
+    const form = await request.formData();
+    const fields = {};
+    let file;
+    for (const [key, value] of form.entries()) {
+        if (typeof value === "string")
+            fields[key] = value;
+        else if (key === "file")
+            file = {
+                filename: value.name,
+                content: Buffer.from(await value.arrayBuffer()),
+            };
+    }
+    return { fields, file };
+}
 function safeJoin(rootDir, requestPath) {
     const normalized = normalize(requestPath).replace(/^([.][.][/\\])+/, '');
     const fullPath = resolve(rootDir, `.${normalized.startsWith('/') ? normalized : `/${normalized}`}`);
@@ -9987,7 +12884,43 @@ function scanNotebookFiles(projectRoot) {
             continue;
         collect(dir, folder, type);
     }
+    collectDomainArtifacts(join(projectRoot, 'domains'), 'domains');
     return result;
+    function collectDomainArtifacts(currentDir, relativeDir) {
+        if (!existsSync(currentDir))
+            return;
+        try {
+            for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+                if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                    continue;
+                const fullPath = join(currentDir, entry.name);
+                const relativePath = `${relativeDir}/${entry.name}`;
+                if (entry.isDirectory()) {
+                    collectDomainArtifacts(fullPath, relativePath);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                const segments = relativePath.split('/');
+                const ownerFolder = segments.find((segment) => ['notebooks', 'blocks', 'terms', 'views'].includes(segment));
+                const type = ownerFolder === 'notebooks' ? 'notebook'
+                    : ownerFolder === 'blocks' ? 'block'
+                        : ownerFolder === 'terms' ? 'term'
+                            : ownerFolder === 'views' ? 'business_view'
+                                : undefined;
+                if (!type || (!entry.name.endsWith('.dql') && !entry.name.endsWith('.dqlnb')))
+                    continue;
+                const fallbackName = entry.name.replace(/\.(dql|dqlnb)$/, '');
+                result.push({
+                    name: inferDqlArtifactName(fullPath, type, fallbackName),
+                    path: relativePath,
+                    type,
+                    folder: relativeDir,
+                });
+            }
+        }
+        catch { /* skip unreadable domain package dirs */ }
+    }
     function collect(currentDir, relativeDir, type) {
         try {
             for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
@@ -10315,7 +13248,13 @@ export function buildSemanticTableMapping(semanticLayer, rows) {
         allSemanticTables.add(metric.table);
     for (const dimension of semanticLayer.listDimensions())
         allSemanticTables.add(dimension.table);
+    for (const measure of semanticLayer.listMeasures())
+        allSemanticTables.add(measure.table);
+    for (const model of semanticLayer.listSemanticModels())
+        allSemanticTables.add(model.table);
     for (const semTable of allSemanticTables) {
+        if (!semTable)
+            continue;
         if (dbTableNames.has(semTable) && schemaQualified.has(semTable)) {
             tableMapping[semTable] = schemaQualified.get(semTable);
         }
@@ -10335,23 +13274,32 @@ function composeRuntimeSemanticQuery(request, semanticLayer, context) {
         const dbtProjectPath = effectiveSemanticConfig?.provider === 'dbt'
             ? effectiveSemanticConfig.projectPath
             : context.projectConfig.dbt?.projectDir;
-        const compiled = compileMetricFlowQuery({
-            projectRoot: context.projectRoot,
-            dbtProjectPath,
-            metrics: request.metrics,
-            dimensions: request.dimensions,
-            filters: request.filters,
-            timeDimension: request.timeDimension,
-            orderBy: request.orderBy,
-            limit: request.limit,
-            savedQuery: request.savedQuery,
-        });
-        return {
-            sql: compiled.sql,
-            joins: [],
-            tables: [],
-            engine: 'metricflow',
-        };
+        try {
+            const compiled = compileMetricFlowQuery({
+                projectRoot: context.projectRoot,
+                dbtProjectPath,
+                metrics: request.metrics,
+                dimensions: request.dimensions,
+                filters: request.filters,
+                timeDimension: request.timeDimension,
+                orderBy: request.orderBy,
+                limit: request.limit,
+                savedQuery: request.savedQuery,
+            });
+            return {
+                sql: compiled.sql,
+                joins: [],
+                tables: [],
+                engine: 'metricflow',
+            };
+        }
+        catch (error) {
+            // An explicit MetricFlow request must retain its strict engine contract.
+            // For the default dbt path, a missing local CLI may fall back only if the
+            // native composer can safely materialize the requested simple metrics.
+            if (request.engine === 'metricflow' || !(error instanceof MetricFlowUnavailableError))
+                throw error;
+        }
     }
     const composed = semanticLayer.composeQuery({
         metrics: request.metrics,
@@ -10367,6 +13315,7 @@ function composeRuntimeSemanticQuery(request, semanticLayer, context) {
 }
 function composeSemanticBlockSql(source, semanticLayer, options) {
     const config = parseSemanticBlockConfig(source);
+    const runtimeBindings = semanticRuntimeParameterBindings(source, options?.parameters ?? {});
     const metrics = config.metrics.length > 0
         ? config.metrics
         : config.metric
@@ -10423,11 +13372,11 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
             ? composeRuntimeSemanticQuery({
                 metrics,
                 dimensions: config.dimensions,
-                filters: config.filters,
+                filters: mergeSemanticRuntimeFilters(config.filters, runtimeBindings.filters),
                 timeDimension: config.timeDimension && config.granularity
                     ? { name: config.timeDimension, granularity: config.granularity }
                     : undefined,
-                limit: config.limit,
+                limit: runtimeBindings.limit ?? config.limit,
             }, semanticLayer, {
                 projectRoot: options.projectRoot,
                 projectConfig: options.projectConfig,
@@ -10438,11 +13387,11 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
             : semanticLayer.composeQuery({
                 metrics,
                 dimensions: config.dimensions,
-                filters: config.filters,
+                filters: mergeSemanticRuntimeFilters(config.filters, runtimeBindings.filters),
                 timeDimension: config.timeDimension && config.granularity
                     ? { name: config.timeDimension, granularity: config.granularity }
                     : undefined,
-                limit: config.limit,
+                limit: runtimeBindings.limit ?? config.limit,
                 driver: options?.driver,
                 tableMapping: options?.tableMapping,
             });
@@ -10469,6 +13418,39 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
         semanticRefs,
     };
 }
+function semanticRuntimeParameterBindings(source, values) {
+    const program = new Parser(source, '<semantic-parameters>').parse();
+    const block = program.statements.find((statement) => statement.kind === NodeKind.BlockDecl);
+    if (!block || block.kind !== NodeKind.BlockDecl || block.blockType !== 'semantic')
+        return { filters: [] };
+    const filters = [];
+    let limit;
+    for (const definition of blockParameterDefinitions(block)) {
+        const value = values[definition.name];
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (definition.binding?.kind === 'semantic_filter') {
+            const rawValues = Array.isArray(value) ? value : [value];
+            filters.push({
+                dimension: definition.binding.field,
+                operator: definition.binding.operator,
+                values: rawValues.map((item) => String(item)),
+            });
+        }
+        else if (definition.binding?.kind === 'limit') {
+            const parsed = typeof value === 'number' ? value : Number(value);
+            if (Number.isFinite(parsed) && parsed > 0)
+                limit = Math.floor(parsed);
+        }
+    }
+    return { filters, ...(limit !== undefined ? { limit } : {}) };
+}
+function mergeSemanticRuntimeFilters(declared, runtime) {
+    if (runtime.length === 0)
+        return declared;
+    const runtimeDimensions = new Set(runtime.map((filter) => filter.dimension));
+    return [...declared.filter((filter) => !runtimeDimensions.has(filter.dimension)), ...runtime];
+}
 function resolveCustomBlockSql(sql, semanticLayer) {
     if (!sql) {
         return {
@@ -10597,12 +13579,17 @@ export function validateBlockStudioSource(source, semanticLayer) {
                 message: 'No executable SQL found in the block source.',
             });
     }
+    const parameterInvocation = prepareBlockInvocation({ source, surface: 'block_studio' });
+    if (parameterInvocation.errors.length > 0) {
+        diagnostics.push(...parameterInvocation.errors.map((message) => ({ severity: 'error', code: 'parameter_parse', message })));
+    }
     return {
         valid: diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
         diagnostics,
         semanticRefs,
         chartConfig: chartConfig ?? undefined,
         executableSql,
+        parameters: parameterInvocation.parameters,
     };
 }
 export async function createDqlArtifactGenerationSessionForProject(projectRoot, options, semanticLayer) {
@@ -13286,26 +16273,117 @@ function yamlScalar(value) {
 function buildNotebookTemplate(title, template) {
     const id = () => Math.random().toString(36).slice(2, 10);
     let cells;
-    if (template === 'revenue') {
+    if (template === "analysis") {
+        cells = [
+            {
+                id: id(),
+                type: "markdown",
+                content: "# TL;DR\n\nSummarize the answer and decision here.",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Context and methods\n\nState the business question, scope, definitions, and assumptions.",
+            },
+            {
+                id: id(),
+                type: "dql",
+                name: "analysis_data",
+                content: "",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Results\n\nExplain the material findings and uncertainty.",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Takeaways\n\nRecord the decision, risks, and next action.",
+            },
+        ];
+    }
+    else if (template === "metric_diagnostic") {
         cells = [
-            { id: id(), type: 'markdown', content: `# ${title}\n\nRevenue analysis using DQL and DuckDB.` },
-            { id: id(), type: 'sql', name: 'revenue_summary', content: "SELECT\n  segment_tier AS segment,\n  SUM(amount) AS total_revenue,\n  COUNT(*) AS deals\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY segment_tier\nORDER BY total_revenue DESC" },
-            { id: id(), type: 'sql', name: 'revenue_trend', content: "SELECT\n  recognized_at AS date,\n  SUM(amount) AS revenue\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY recognized_at\nORDER BY recognized_at" },
+            {
+                id: id(),
+                type: "markdown",
+                content: "# Metric diagnostic\n\nWhat changed, when, and for whom?",
+            },
+            {
+                id: id(),
+                type: "dql",
+                name: "metric_trend",
+                content: "",
+            },
+            {
+                id: id(),
+                type: "dql",
+                name: "driver_breakdown",
+                content: "",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Diagnosis\n\nSeparate validated drivers from hypotheses and data limitations.",
+            },
         ];
     }
-    else if (template === 'pipeline') {
+    else if (template === "data_quality") {
         cells = [
-            { id: id(), type: 'markdown', content: `# ${title}\n\nPipeline health and conversion analysis.` },
-            { id: id(), type: 'sql', name: 'pipeline_overview', content: "SELECT *\nFROM read_csv_auto('./data/pipeline.csv')\nLIMIT 100" },
+            {
+                id: id(),
+                type: "markdown",
+                content: "# Data-quality investigation\n\nDocument the source, owner, freshness expectation, and affected decisions.",
+            },
+            {
+                id: id(),
+                type: "dql",
+                name: "quality_profile",
+                content: "",
+            },
+            {
+                id: id(),
+                type: "dql",
+                name: "quality_checks",
+                content: "",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Findings and disposition\n\nRecord severity, impacted metrics, owner, and remediation.",
+            },
         ];
     }
-    else {
+    else if (template === "experiment") {
         cells = [
-            { id: id(), type: 'markdown', content: `# ${title}\n\nAdd your analysis here.` },
-            { id: id(), type: 'sql', name: 'query_1', content: 'SELECT 1 AS hello' },
+            {
+                id: id(),
+                type: "markdown",
+                content: "# Experiment log\n\nHypothesis, primary metric, guardrails, population, and dates.",
+            },
+            {
+                id: id(),
+                type: "dql",
+                name: "experiment_results",
+                content: "",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Results\n\nReport effect size, uncertainty, guardrails, and data-quality checks.",
+            },
+            {
+                id: id(),
+                type: "markdown",
+                content: "## Decision\n\nShip, iterate, or stop — with rationale.",
+            },
         ];
     }
-    return JSON.stringify({ version: 1, title, cells }, null, 2);
+    else {
+        cells = [];
+    }
+    return JSON.stringify({ dqlnbVersion: 2, version: 1, title, cells }, null, 2);
 }
 /** Build a lineage graph from the project's blocks and semantic layer. */
 // Simple lineage graph cache: rebuilds at most every 5 seconds
@@ -13401,15 +16479,23 @@ function resolveDbtManifestPath(projectRoot, projectConfig = {}) {
     candidates.push(join(projectRoot, 'target', 'manifest.json'), join(resolve(projectRoot, '..'), 'target', 'manifest.json'), join(resolve(projectRoot, '../dbt'), 'target', 'manifest.json'), join(resolve(projectRoot, '../../dbt'), 'target', 'manifest.json'));
     return candidates.find((candidate, index, list) => list.indexOf(candidate) === index && existsSync(candidate));
 }
-export function discoverDbtProfileConnections(projectRoot, projectConfig) {
+export function discoverDbtProfileConnections(projectRoot, projectConfig, explicitPath) {
     const dbtProjectPath = findDbtProjectPath(projectRoot, projectConfig);
-    const projectProfileName = readDbtProjectProfileName(dbtProjectPath);
-    const profilePaths = findDbtProfilePaths(projectRoot, dbtProjectPath);
+    const projectProfileName = explicitPath ? null : readDbtProjectProfileName(dbtProjectPath);
+    const configuredProfilesDir = projectConfig.dbt?.profilesDir
+        ? resolve(projectRoot, projectConfig.dbt.profilesDir)
+        : undefined;
+    const profilePaths = explicitPath
+        ? findExplicitDbtProfilePaths(projectRoot, explicitPath)
+        : findDbtProfilePaths(projectRoot, dbtProjectPath, configuredProfilesDir);
     const candidates = [];
     for (const profilePath of profilePaths) {
         const profiles = readYamlFile(profilePath);
         if (!profiles)
             continue;
+        const profileRelativeBase = explicitPath && existsSync(join(dirname(profilePath), 'dbt_project.yml'))
+            ? dirname(profilePath)
+            : dbtProjectPath;
         for (const [profileName, rawProfile] of Object.entries(profiles)) {
             if (!rawProfile || typeof rawProfile !== 'object')
                 continue;
@@ -13433,7 +16519,7 @@ export function discoverDbtProfileConnections(projectRoot, projectConfig) {
                     mapped.connection.filepath &&
                     mapped.connection.filepath !== ':memory:') {
                     if (!isAbsoluteLikePath(mapped.connection.filepath)) {
-                        mapped.connection.filepath = resolve(dbtProjectPath, mapped.connection.filepath);
+                        mapped.connection.filepath = resolve(profileRelativeBase, 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.`);
@@ -13458,6 +16544,21 @@ export function discoverDbtProfileConnections(projectRoot, projectConfig) {
     }
     return candidates.slice(0, 20);
 }
+export function buildDbtParseArgs(dbtProjectDir, profilesDir) {
+    return [
+        'parse',
+        '--project-dir', dbtProjectDir,
+        ...(profilesDir ? ['--profiles-dir', profilesDir] : []),
+    ];
+}
+/** CFG-003: use a complete default dbt target when no saved DQL connection exists. */
+export function resolveDbtProfileRuntimeConnection(projectRoot, projectConfig) {
+    const candidates = discoverDbtProfileConnections(projectRoot, projectConfig);
+    const complete = candidates.filter((candidate) => candidate.missingFields.length === 0
+        && !candidate.warnings.some((warning) => warning.startsWith('DuckDB file not found')));
+    const defaultTarget = complete.find((candidate) => !candidate.warnings.some((warning) => warning.startsWith('Not the default dbt target')));
+    return defaultTarget?.connection ?? (complete.length === 1 ? complete[0].connection : null);
+}
 function findDbtProjectPath(projectRoot, projectConfig) {
     const configuredDbtDir = projectConfig.dbt?.projectDir
         ? resolve(projectRoot, projectConfig.dbt.projectDir)
@@ -13478,8 +16579,18 @@ function findDbtProjectPath(projectRoot, projectConfig) {
         ?? semanticDbtDir
         ?? projectRoot;
 }
-function findDbtProfilePaths(projectRoot, dbtProjectPath) {
+function portableProjectPath(projectRoot, absolutePath) {
+    const normalizedAbsolute = resolve(absolutePath).replace(/\\/g, '/');
+    const relativePath = relative(projectRoot, absolutePath).replace(/\\/g, '/');
+    return !relativePath
+        ? '.'
+        : relativePath === '..' || relativePath.startsWith('../')
+            ? normalizedAbsolute
+            : relativePath;
+}
+function findDbtProfilePaths(projectRoot, dbtProjectPath, configuredProfilesDir) {
     const dirs = [
+        configuredProfilesDir,
         process.env.DBT_PROFILES_DIR,
         dbtProjectPath,
         projectRoot,
@@ -13487,7 +16598,7 @@ function findDbtProfilePaths(projectRoot, dbtProjectPath) {
     ].filter((value) => Boolean(value));
     const paths = [];
     for (const dir of dirs) {
-        for (const filename of ['profiles.yml', 'profiles.yaml']) {
+        for (const filename of ['profiles.yml', 'profiles.yaml', 'profile.yml', 'profile.yaml']) {
             const profilePath = resolve(dir, filename);
             if (existsSync(profilePath) && !paths.includes(profilePath)) {
                 paths.push(profilePath);
@@ -13496,6 +16607,24 @@ function findDbtProfilePaths(projectRoot, dbtProjectPath) {
     }
     return paths;
 }
+function findExplicitDbtProfilePaths(projectRoot, input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return [];
+    const expanded = trimmed === '~'
+        ? homedir()
+        : trimmed.startsWith('~/')
+            ? join(homedir(), trimmed.slice(2))
+            : trimmed;
+    const absolute = resolve(projectRoot, expanded);
+    if (!existsSync(absolute))
+        return [];
+    if (!statSync(absolute).isDirectory())
+        return [absolute];
+    return ['profiles.yml', 'profiles.yaml', 'profile.yml', 'profile.yaml']
+        .map((filename) => join(absolute, filename))
+        .filter((profilePath) => existsSync(profilePath));
+}
 function readDbtProjectProfileName(dbtProjectPath) {
     const projectFile = join(dbtProjectPath, 'dbt_project.yml');
     const projectYaml = readYamlFile(projectFile);
@@ -14185,6 +17314,33 @@ function ensureGitignoreEntry(projectRoot, pattern) {
         // Best-effort; failure to write .gitignore shouldn't fail the snapshot.
     }
 }
+/**
+ * UI-001, SEC-001, E2E-001: local runtime, credential, and generated artifacts must never be offered as
+ * shareable source-control changes. Project skills are intentionally absent:
+ * `.dql/skills` remains readable during migration and can be governed in Git.
+ */
+const LOCAL_RUNTIME_GITIGNORE_RULES = [
+    'dql-manifest.json',
+    '*.duckdb',
+    '*.duckdb.wal',
+    '*.run.json',
+    '**/.dql/runs/',
+    '**/.dql/cache/',
+    '**/.dql/imports/',
+    '**/.dql/local/',
+    '**/.dql/connectors/',
+    '**/.dql/memory/',
+    '**/.dql/migration-staging/',
+    '**/.dql/docker-starter/',
+    '**/.dql/oauth-credentials.json',
+    '**/.dql/provider-settings.json',
+    '**/.dql/mcp-servers.json',
+    '**/.dql-user-prefs.json',
+];
+export function ensureLocalRuntimeGitignore(projectRoot) {
+    for (const rule of LOCAL_RUNTIME_GITIGNORE_RULES)
+        ensureGitignoreEntry(projectRoot, rule);
+}
 async function readGitDiff(cwd, filePath, staged = false) {
     const gitRoot = await resolveGitRoot(cwd);
     if (!gitRoot) {
@@ -14469,6 +17625,39 @@ async function gitCreateReview(cwd, input) {
         warning: `Branch pushed. Open the compare page to create the PR: ${gitErrorOutput(pr) || 'GitHub CLI is not available or authenticated.'}`,
     };
 }
+/** UI-001, SEC-001, E2E-001: open a PR for a branch already committed and pushed by the guided share flow. */
+async function gitOpenReview(cwd, input) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const title = input.title.trim();
+    if (!title)
+        return { ok: false, error: 'Review title required' };
+    const base = input.base.trim() || 'main';
+    const status = await readGitStatus(gitRoot);
+    const branch = status.branch;
+    if (!branch || branch === 'HEAD' || branch === base || branch === 'master') {
+        return { ok: false, error: 'Share the changes to a review branch before opening a review request.' };
+    }
+    const remote = await readGitRemote(gitRoot);
+    if (!remote.url)
+        return { ok: false, error: 'Add a Git remote before requesting review.' };
+    const compareUrl = gitHubCompareUrl(remote.url, branch, base);
+    const pr = await execGh(gitRoot, [
+        'pr', 'create', '--base', base, '--head', branch, '--title', title,
+        '--body', input.body.trim() || `Review governed analytics changes: ${title}`,
+    ]);
+    if (pr.code === 0) {
+        const prUrl = pr.stdout.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/)?.[0] ?? compareUrl;
+        return { ok: true, branch, prUrl };
+    }
+    return {
+        ok: true,
+        branch,
+        prUrl: compareUrl,
+        warning: `Branch is ready. Open the compare page to create the PR: ${gitErrorOutput(pr) || 'GitHub CLI is not available or authenticated.'}`,
+    };
+}
 async function gitPull(cwd) {
     const gitRoot = await resolveGitRoot(cwd);
     if (!gitRoot)
@@ -14565,8 +17754,7 @@ async function enableGitGovernedContextTracking(cwd) {
     const existing = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf-8') : '';
     const lines = existing.split(/\r?\n/);
     const next = lines.filter((line) => !/^\s*\/?\.dql\/\s*$/.test(line));
-    const keepLocal = ['.dql/runs/', '.dql/cache/', '.dql/imports/', '.dql/local/', '.dql/docker-starter/'];
-    for (const rule of keepLocal) {
+    for (const rule of LOCAL_RUNTIME_GITIGNORE_RULES) {
         if (!next.some((line) => line.trim() === rule))
             next.push(rule);
     }
@@ -15813,7 +19001,7 @@ const NON_ENTITY_PLURALS = new Set([
  * project vocabulary — so it fires for ANY repo's join-shaped questions, not just
  * jaffle. Over-triggering only costs a few extra bounded probes (all in try/catch).
  */
-function shouldAugmentAgentRuntimeSchema(question) {
+export function shouldAugmentAgentRuntimeSchema(question, questionPlan) {
     const lower = question.toLowerCase();
     const wantsMetric = /\brevenu|\bsales\b|\bamount\b|\bspend\b|\bcost\b|\bcount\b|\btotal\b|\bsum\b|\bavg\b|\baverage\b|\bvalue\b|\bprice\b/.test(lower);
     const wantsDetail = /\bdetails?\b|\bcomplete\b|\bbreakdown\b|\ball\s+values?\b|\beach\b|\bevery\b/.test(lower);
@@ -15822,7 +19010,12 @@ function shouldAugmentAgentRuntimeSchema(question) {
     // Multi-entity intent: a linking word + >= 2 distinct plural content nouns.
     const nouns = new Set((lower.match(/\b[a-z]{4,}s\b/g) ?? []).filter((word) => !NON_ENTITY_PLURALS.has(word)));
     const multiEntity = /\b(?:and|with|plus|per|for\s+each|by)\b/.test(lower) && nouns.size >= 2;
-    return explicitJoin || referencesPriorRows || (multiEntity && (wantsMetric || wantsDetail));
+    const plannedConcepts = new Set([
+        ...(questionPlan?.entities ?? []).map((entity) => typeof entity === 'string' ? entity : entity.typeHint ?? entity.text ?? ''),
+        ...(questionPlan?.dimensionTerms ?? []),
+    ].map((value) => value.trim().toLowerCase()).filter(Boolean));
+    const plannedCompositeMetric = (questionPlan?.metricTerms?.length ?? 0) > 0 && plannedConcepts.size >= 2;
+    return explicitJoin || referencesPriorRows || plannedCompositeMetric || (multiEntity && (wantsMetric || wantsDetail));
 }
 async function enrichAgentSchemaContextWithValueMatches(question, schemaContext, executor, connection) {
     const searchTerms = extractAgentValueSearchTerms(question);