@duckcodeailabs/dql-cli 1.7.0 → 1.7.1

package/dist/local-runtime.js

@@ -10,13 +10,13 @@ import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, pla
 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, 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 { 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, invalidateAgentProjectState, resolveDomainContextEnvelope, defaultKgPath, planApp, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, 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';
@@ -389,13 +389,19 @@ export async function startLocalServer(opts) {
     const gitRoot = await resolveGitRoot(projectRoot);
     if (gitRoot)
         ensureLocalRuntimeGitignore(projectRoot);
-    let connection = rawConnection ? normalizeProjectConnection(rawConnection, projectRoot) : null;
     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) ?? undefined;
+        const dbtManifestPath = resolveDbtManifestPath(projectRoot, projectConfig) ?? undefined;
         const inputs = collectInputFiles({ projectRoot, dbtManifestPath });
         const signatureHash = createHash('sha256');
         for (const input of inputs.sort()) {
@@ -421,14 +427,26 @@ export async function startLocalServer(opts) {
         };
     };
     const onboardingDbtPaths = (body = {}) => {
-        const projectDirInput = typeof body.projectDir === 'string' ? body.projectDir : projectConfig.dbt?.projectDir ?? '.';
+        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' });
         }
-        return { dbtProjectDir, manifestPath, projectDirInput, manifestInput };
+        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);
@@ -445,8 +463,11 @@ export async function startLocalServer(opts) {
         }
         const fingerprint = createHash('sha256').update(readFileSync(paths.manifestPath)).digest('hex');
         return {
-            projectDir: relative(projectRoot, paths.dbtProjectDir).replace(/\\/g, '/') || '.',
+            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: {
@@ -1900,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.'
@@ -1924,6 +1947,7 @@ export async function startLocalServer(opts) {
                         dashboardId: session.dashboardId,
                         plan: session.plan,
                         proposal,
+                        proposalHash: session.proposalHash,
                         warnings: session.warnings,
                     }, session.appId)] : [],
                 evaluations: [
@@ -3390,8 +3414,10 @@ export async function startLocalServer(opts) {
         }
         if (req.method === 'GET' && path === '/api/onboarding/status') {
             const requestId = apiRequestId('onboarding-status');
-            const dbtProjectDir = resolve(projectRoot, projectConfig.dbt?.projectDir ?? '.');
+            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;
@@ -3412,6 +3438,12 @@ export async function startLocalServer(opts) {
                     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,
                 },
@@ -3457,7 +3489,9 @@ export async function startLocalServer(opts) {
                         throw error;
                     const { dbtProjectDir } = onboardingDbtPaths(body);
                     try {
-                        execFileSync('dbt', ['parse', '--project-dir', dbtProjectDir], {
+                        const { profilesDir } = onboardingDbtPaths(body);
+                        const parseArgs = buildDbtParseArgs(dbtProjectDir, profilesDir);
+                        execFileSync('dbt', parseArgs, {
                             cwd: dbtProjectDir,
                             timeout: 120_000,
                             maxBuffer: 1024 * 1024,
@@ -3483,16 +3517,24 @@ export async function startLocalServer(opts) {
                     ...projectConfig,
                     manifestVersion: 3,
                     modeling: { mode: 'dbt-first' },
-                    dbt: { projectDir: preview.projectDir, manifestPath: preview.manifestPath },
+                    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;
@@ -3504,6 +3546,7 @@ export async function startLocalServer(opts) {
                     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' });
@@ -4446,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
@@ -5148,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 {
@@ -5160,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
@@ -5258,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({
@@ -5381,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) {
@@ -6691,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' });
@@ -7595,9 +7834,35 @@ 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") {
@@ -10663,6 +10928,18 @@ 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';
 }
@@ -16202,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;
@@ -16234,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.`);
@@ -16259,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)
@@ -16279,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,
@@ -16288,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);
@@ -16297,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);