@duckcodeailabs/dql-cli 1.11.10 → 1.12.0

package/dist/local-runtime.js

@@ -9,6 +9,7 @@ import { dirname, extname, join, normalize, relative, resolve, sep, } from "node
 import { Readable } from "node:stream";
 import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, planMixedSourceNotebookSql, planMixedSourceSql, } from "./mixed-source-sql.js";
 import { resolveNpmInvocation } from './npm-runtime.js';
+import { ensureDqlGitignore, isGovernedSourceFile, isLegacyBroadDqlIgnore, } from './git-contract.js';
 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, normalizeAnalyticalFailureV1, relationshipValidationProofFingerprint, renderSemanticBlockSource, discoverDbtDomains, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, semanticDimensionReference, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
@@ -19,7 +20,7 @@ import { fetchLatestPublishedDqlVersion, resolveDqlRuntimeVersionStatus } from '
 import { resolveRetrievalHealthStatus } from './retrieval-health.js';
 import { createDqlAgentProviderRunner, resolveAgentFollowUpContext } 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, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, propose, proposePlan, recordCorrectionTrace, listHintsFromGit, evaluateHint, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, conversationHistoryFromContext, recallRelevantTurns, renderConversationEnvelopeForPrompt, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildAnalysisQuestionPlan, composeSemanticQueryForQuestion, aggregationIntegrityIssuesForSql, buildLocalContextPack, applyContextPackCompatibility, toAgentRetrievalEvidence, prepareConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureAgentProjectReady, isAgentProjectIndexReady, currentMetadataFingerprint, ensureMetadataCatalogFresh, readIndexedDomainKnowledge, readIndexedKnowledge360, compactSemanticRuntimeFailure, classifyAnalyticalFailure, propose, proposePlan, recordGovernedCorrection, HintStore, defaultHintIndexPath, ensureHintIndexFresh, listHintsFromGit, getHintEvaluationFromGit, getCorrectionTraceFromGit, inspectGovernedHint, editGovernedHintCandidate, reopenGovernedHint, retireHint, supersedeHint, hintsConflict, mineJoinPatterns, reviewGovernedHint, AgentRunEngine, SqliteAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, buildDeterministicDashboardStory, synthesizeAnswer, streamOrGenerate, narrateResult, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, deriveAnalyticalRepair, reindexProject, invalidateAgentProjectState, recordAgentRuntimeVersion, resolveDomainContextEnvelope, projectEmbeddingProvider, isHashedEmbeddingProvider, clearProjectEmbeddingCache, upgradeVectorIndexForProject, openMetadataCatalog, defaultKgPath, planAppFromPrompt, KGStore, planResearch, loadSemanticMetrics, cascadeTraceToEvidenceRouteSteps, createCascadeAnswerResult, createCascadeTrace, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, upsertGeneratedDqlArtifactDraft, loadAgentSemanticLayer, } 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';
@@ -39,6 +40,7 @@ import { observeWarehouseTargetIdentity } from './semantic-execution/connection-
 import { configuredWarehouseTargetIdentity } from './semantic-execution/connection-identity.js';
 import { executeTargetBoundSemanticQuery, semanticExecutionFailureCode, semanticExecutionFailureDetails, } from './semantic-execution/execution-gateway.js';
 import { buildSemanticTargetBinding } from './semantic-execution/target-binding.js';
+import { normalizeConnectionMetadataScope, syncWarehouseMetadata, warehouseMetadataStatus, } from './warehouse-metadata.js';
 import { NotebookDatasetWorkspace, } from "./notebook-datasets.js";
 import { prepareBlockInvocation } from './block-invocation.js';
 const NOTEBOOK_EXECUTE_PREVIEW_ROW_LIMIT = 500;
@@ -418,6 +420,8 @@ async function conversationContextFromThread(store, threadId, clientContext, que
             sourceCertifiedBlock: turn.sourceCertifiedBlock,
             route: turn.route,
             trustLabel: turn.trustLabel,
+            runStatus: turn.runStatus,
+            stopReason: turn.stopReason,
             certification: turn.certification,
             contextPackId: turn.contextPackId,
             dqlArtifact: turn.dqlArtifact,
@@ -453,6 +457,7 @@ async function conversationContextFromThread(store, threadId, clientContext, que
         ...(clientContext ?? {}),
         conversationStateVersion: 1,
         threadId,
+        ...(serverSnapshot ? { conversationEnvelope: serverSnapshot } : {}),
         ...(serverSnapshot ? { serverSnapshot } : {}),
         ...(thread?.rollingSummary ? { conversationSummary: thread.rollingSummary } : {}),
         ...(turns.length > 0 ? { turns, activeTurnId: turns[turns.length - 1].id } : {}),
@@ -509,6 +514,8 @@ export function conversationTurnInputFromRun(run) {
         answerText: run.answer,
         route: run.route,
         trustLabel: agentRunString(payload?.trustLabel) ?? run.trustState,
+        runStatus: run.status,
+        stopReason: run.stopReason,
         certification: agentRunString(payload?.certification),
         sourceCertifiedBlock: agentRunString(payload?.sourceCertifiedBlock)
             ?? (artifact?.kind === 'answer' ? agentRunString(artifact.ref) : undefined),
@@ -640,6 +647,17 @@ export async function startLocalServer(opts) {
         ensureLocalRuntimeGitignore(projectRoot);
     let projectConfig = loadProjectConfig(projectRoot);
     recordAgentRuntimeVersion(projectRoot, runtimeVersion);
+    // A clone carries governed Hint Graph files in Git, never the rebuildable
+    // `.dql/cache` database. Materialize that projection as soon as the Notebook
+    // opens so Agent Learning and the first retrieval see the same shared truth.
+    // Malformed/local cache state must not prevent the rest of the OSS notebook
+    // from starting; normal review/reindex surfaces can still report and repair it.
+    try {
+        ensureHintIndexFresh(projectRoot);
+    }
+    catch {
+        // Best-effort bootstrap, consistent with the existing agent reindex path.
+    }
     const configuredConnection = rawConnection
         ? normalizeProjectConnection(rawConnection, projectRoot)
         : projectConfig.defaultConnection
@@ -1304,7 +1322,7 @@ export async function startLocalServer(opts) {
             semanticDriver = undefined;
         }
         const semanticTableMapping = semanticLayer && semanticConnection
-            ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer)
+            ? await resolveSemanticTableMapping(executor, semanticConnection, semanticLayer, projectRoot)
             : undefined;
         const requestedDomain = normalizeAgentRunDomain(agentRunWorkspaceValue(request, 'domain'));
         const requestedPurpose = agentRunWorkspaceValue(request, 'purpose');
@@ -2188,13 +2206,16 @@ export async function startLocalServer(opts) {
                 message: 'Building catalog-grounded research plan.',
                 route: 'research',
             });
+            const conversationHistory = request.history?.length
+                ? request.history
+                : conversationHistoryFromContext(request.conversationContext);
             const plan = await planResearch({
                 question: request.question,
                 metrics,
                 blocks,
                 intent: request.intent,
-                isFollowUp: Boolean(request.history?.length),
-                history: request.history,
+                isFollowUp: conversationHistory.length > 0,
+                history: conversationHistory,
                 // When the user explicitly picked research, investigate — don't collapse to one step.
                 forceInvestigate: request.requestedMode === 'research',
                 rootPlan: routeDecision?.resolvedAnalyticalPlan,
@@ -2663,7 +2684,8 @@ export async function startLocalServer(opts) {
         // this only inside the provider adapter allowed stale catalog matches to win
         // before "they" / "this amount" became customer-scoped context.
         const followUp = resolveAgentFollowUpContext(request.conversationContext, request.question);
-        const serverSnapshot = agentRunRecord(request.conversationContext?.serverSnapshot);
+        const serverSnapshot = agentRunRecord(request.conversationContext?.conversationEnvelope
+            ?? request.conversationContext?.serverSnapshot);
         const topicRelation = agentRunString(serverSnapshot?.topicRelation);
         // The readiness marker is source-versioned. When it matches, pass the
         // already-built metadata identity into retrieval so buildLocalContextPack
@@ -2815,6 +2837,7 @@ export async function startLocalServer(opts) {
         path: defaultAgentRunSqlitePath(projectRoot),
         legacyJsonPath: defaultAgentRunStorePath(projectRoot),
     });
+    const conversationStorePath = await prepareConversationPath(projectRoot);
     // A run may outlive its streaming browser connection, so cancellation is
     // server-owned and keyed by run id rather than relying on fetch abort alone.
     const activeAgentRunControllers = new Map();
@@ -2826,7 +2849,7 @@ export async function startLocalServer(opts) {
         if (conversationStoreInstance !== undefined)
             return conversationStoreInstance;
         try {
-            conversationStoreInstance = new ConversationStore(defaultConversationPath(projectRoot));
+            conversationStoreInstance = new ConversationStore(conversationStorePath);
         }
         catch {
             conversationStoreInstance = null;
@@ -2882,7 +2905,7 @@ export async function startLocalServer(opts) {
                     };
                     const resolved = resolveNotebookBlockReferenceCell(cell, projectRoot);
                     const activeConnection = requireActiveConnection();
-                    const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+                    const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot);
                     const semanticCompose = resolved.cell.type === 'dql'
                         && semanticLayer
                         && /\btype\s*=\s*"semantic"/i.test(resolved.cell.source)
@@ -2969,7 +2992,7 @@ export async function startLocalServer(opts) {
         const activeConnection = requireActiveConnection();
         const precompiledSemanticQuery = Boolean(extractBlockStudioSql(source));
         const tableMapping = !precompiledSemanticQuery
-            ? await resolveSemanticTableMapping(executor, activeConnection, semanticLayer)
+            ? await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot)
             : undefined;
         const semanticCompose = semanticLayer
             ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
@@ -3231,6 +3254,13 @@ export async function startLocalServer(opts) {
             };
         };
         const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question, preparedContextPack).catch(() => []);
+        const activeScope = connection
+            ? optionalActiveConnectionMetadataScope(projectRoot, projectConfig, connection, projectConfig.defaultConnectionName ?? 'default')
+            : null;
+        const activeRuntimeSnapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+        const hasActivatedMetadataGeneration = Boolean(activeScope
+            && activeRuntimeSnapshot?.scopeFingerprint === activeScope.scopeFingerprint
+            && activeRuntimeSnapshot.status !== 'stale');
         const valueGrounding = resolveAgentRuntimeValueGrounding(projectConfig);
         if (catalogContext.length > 0) {
             if (!connection || valueGrounding.mode !== 'safe_automatic')
@@ -3239,9 +3269,17 @@ export async function startLocalServer(opts) {
             // row value must not turn a warm Ask into an information_schema scan over
             // thousands of enterprise tables; only field-scoped value probes are live.
             const enriched = await enrichAgentSchemaContextWithValueMatches(question, catalogContext, executor, connection, valueGrounding.searchSafeColumns);
-            recordAgentRuntimeSchemaSnapshot(projectRoot, catalogContext, 'catalog runtime schema');
+            if (!hasActivatedMetadataGeneration) {
+                recordAgentRuntimeSchemaSnapshot(projectRoot, catalogContext, 'catalog runtime schema');
+            }
             return enriched;
         }
+        // An activated, scope-qualified warehouse generation is the complete warm
+        // metadata authority. A lexical miss is not permission to rescan every
+        // visible schema for each question; the governed planner may clarify or the
+        // user may explicitly refresh the selected scope.
+        if (hasActivatedMetadataGeneration)
+            return [];
         if (!connection)
             return [];
         try {
@@ -4039,15 +4077,7 @@ export async function startLocalServer(opts) {
         const activeConnection = requireActiveConnection(targetConnection);
         let tableMapping;
         if (semanticLayer) {
-            try {
-                const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
-           FROM information_schema.tables
-           WHERE UPPER(table_schema) NOT IN ('INFORMATION_SCHEMA', 'PG_CATALOG')`, [], {}, activeConnection);
-                tableMapping = buildSemanticTableMapping(semanticLayer, tablesResult.rows);
-            }
-            catch {
-                tableMapping = undefined;
-            }
+            tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot);
         }
         const invocation = prepareBlockInvocation({ source, parameters, surface: 'block_studio' });
         if (invocation.errors.length > 0)
@@ -4091,7 +4121,7 @@ export async function startLocalServer(opts) {
     const runBlockStudioTestSummary = async (source, targetConnection) => {
         const activeConnection = requireActiveConnection(targetConnection);
         const start = Date.now();
-        const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+        const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot);
         // Run tests against the SAME SQL the preview runs: for a semantic block with a
         // pre-compiled query, that's the query (not a recompiled metric), so the test's
         // output columns match the block's declared outputs.
@@ -4810,6 +4840,18 @@ export async function startLocalServer(opts) {
                 }));
                 return;
             }
+            if (req.method === 'GET' && path === '/api/domain-workspaces/related-products') {
+                const requestId = apiRequestId('domain-related-products');
+                const snapshot = projectSnapshot();
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    requestId,
+                    domain: null,
+                    ...relatedProductsForDomain(snapshot.manifest, undefined, scanNotebookFiles(projectRoot)),
+                    snapshotId: snapshot.snapshotId,
+                }));
+                return;
+            }
             if (req.method === 'GET' && path.startsWith('/api/domain-workspaces/')) {
                 const requestId = apiRequestId('domain-workspace');
                 const suffix = decodeURIComponent(path.slice('/api/domain-workspaces/'.length));
@@ -4842,7 +4884,7 @@ export async function startLocalServer(opts) {
                 }
                 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, domain: domainId, ...relatedProductsForDomain(manifest, domainId, scanNotebookFiles(projectRoot)), snapshotId: snapshot.snapshotId }
                     : {
                         requestId,
                         snapshotId: snapshot.snapshotId,
@@ -6588,32 +6630,180 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ ok: true, files }));
                 return;
             }
-            // Local learning loop (OSS): record an analyst's wrong→right correction as a
-            // scope-matched Hint-Graph hint plus an advisory memory, so future similar
-            // questions avoid the same mistake. Single-user self-serve — the correction IS
-            // the approval, so the derived candidate is approved immediately unless the
-            // caller opts out. Advisory only: never overrides certified routing. The
-            // multi-tenant review workflow + automated distillation stay a cloud feature.
-            // Hint review queue. Corrections are captured as CANDIDATES; a hint only
-            // starts shaping other people's answers once a human approves it here.
+            // CTX-005 / API-003 / E2E-001 local-first Hint Graph review queue.
+            // Corrections are captured as
+            // candidates; only the shared governed lifecycle can evaluate and approve
+            // them for future advisory retrieval.
             if (req.method === 'GET' && path === '/api/agent/hints') {
                 try {
                     const status = url.searchParams.get('status');
                     const all = listHintsFromGit(projectRoot);
-                    const hints = status ? all.filter((hint) => hint.status === status) : all;
+                    const selected = (status ? all.filter((hint) => hint.status === status) : all)
+                        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+                        .slice(0, 200);
+                    const hintIndex = new HintStore(defaultHintIndexPath(projectRoot));
+                    const graphEdgesByHint = new Map(selected.map((hint) => [hint.id, hintIndex.edgesForHint(hint.id)]));
+                    hintIndex.close();
+                    const snapshotId = projectSnapshot().snapshotId;
+                    const approved = all.filter((hint) => hint.status === 'approved');
+                    const inspectionById = new Map(await Promise.all(all
+                        .filter((hint) => hint.status === 'candidate' || hint.status === 'approved')
+                        .map(async (hint) => [
+                        hint.id,
+                        await inspectGovernedHint(projectRoot, { hintId: hint.id, snapshotId }),
+                    ])));
+                    // Match retrieval truth: stale/invalid approved hints cannot create a
+                    // conflict or supersede another otherwise-current hint.
+                    const eligibleApproved = approved.filter((hint) => inspectionById.get(hint.id)?.state === 'current');
+                    const conflictIds = new Map();
+                    for (let left = 0; left < eligibleApproved.length; left += 1) {
+                        for (let right = left + 1; right < eligibleApproved.length; right += 1) {
+                            if (!hintsConflict(eligibleApproved[left], eligibleApproved[right]))
+                                continue;
+                            conflictIds.set(eligibleApproved[left].id, [...(conflictIds.get(eligibleApproved[left].id) ?? []), eligibleApproved[right].id]);
+                            conflictIds.set(eligibleApproved[right].id, [...(conflictIds.get(eligibleApproved[right].id) ?? []), eligibleApproved[left].id]);
+                        }
+                    }
+                    const supersededIds = new Map(eligibleApproved.filter((hint) => hint.supersedes).map((hint) => [hint.supersedes, hint.id]));
+                    const hints = await Promise.all(selected.map(async (hint) => {
+                        const inspection = inspectionById.get(hint.id) ?? null;
+                        const exclusions = [
+                            ...(inspection && inspection.state !== 'current'
+                                ? [{ reason: inspection.state, detail: inspection.checks.filter((check) => !check.passed).map((check) => check.evidence).join(' ') }]
+                                : []),
+                            ...(supersededIds.has(hint.id)
+                                ? [{ reason: 'superseded', detail: `Superseded by ${supersededIds.get(hint.id)}.`, relatedHintId: supersededIds.get(hint.id) }]
+                                : []),
+                            ...((conflictIds.get(hint.id) ?? []).map((relatedHintId) => ({
+                                reason: 'conflict',
+                                detail: `Conflicts with approved hint ${relatedHintId}.`,
+                                relatedHintId,
+                            }))),
+                        ];
+                        return {
+                            ...hint,
+                            graphEdges: graphEdgesByHint.get(hint.id) ?? [],
+                            trace: hint.traceId ? getCorrectionTraceFromGit(projectRoot, hint.traceId) : undefined,
+                            evaluation: hint.evaluationId ? getHintEvaluationFromGit(projectRoot, hint.evaluationId) : undefined,
+                            inspection: inspection ? {
+                                currentSnapshotId: inspection.currentSnapshotId,
+                                snapshotCurrent: inspection.snapshotCurrent,
+                                dependenciesCurrent: inspection.dependenciesCurrent,
+                                driftedDependencies: inspection.driftedDependencies,
+                                checks: inspection.checks,
+                                state: inspection.state,
+                            } : undefined,
+                            exclusions,
+                        };
+                    }));
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
-                        hints: hints.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)).slice(0, 200),
+                        hints,
                         counts: {
                             candidate: all.filter((hint) => hint.status === 'candidate').length,
                             approved: all.filter((hint) => hint.status === 'approved').length,
                             rejected: all.filter((hint) => hint.status === 'rejected').length,
+                            retired: all.filter((hint) => hint.status === 'retired').length,
                         },
                     }));
                 }
                 catch (error) {
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ hints: [], counts: { candidate: 0, approved: 0, rejected: 0 }, error: error instanceof Error ? error.message : String(error) }));
+                    res.end(serializeJSON({ hints: [], counts: { candidate: 0, approved: 0, rejected: 0, retired: 0 }, error: error instanceof Error ? error.message : String(error) }));
+                }
+                return;
+            }
+            const hintEditMatch = /^\/api\/agent\/hints\/([^/]+)$/.exec(path);
+            if (req.method === 'PATCH' && hintEditMatch) {
+                try {
+                    const hintId = decodeURIComponent(hintEditMatch[1]);
+                    const body = await readJSON(req).catch(() => null);
+                    if (!body) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: false, error: 'Candidate fields are required.' }));
+                        return;
+                    }
+                    const rawScope = body.scope && typeof body.scope === 'object' ? body.scope : undefined;
+                    const scopeValue = (key) => {
+                        const value = rawScope?.[key];
+                        return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+                    };
+                    const hint = await editGovernedHintCandidate(projectRoot, {
+                        hintId,
+                        title: typeof body.title === 'string' ? body.title : undefined,
+                        guidance: typeof body.guidance === 'string' ? body.guidance : undefined,
+                        correctedSql: typeof body.correctedSql === 'string' ? body.correctedSql : undefined,
+                        scope: rawScope ? {
+                            metric: scopeValue('metric'),
+                            dbtModel: scopeValue('dbtModel'),
+                            domain: scopeValue('domain'),
+                            dialect: scopeValue('dialect'),
+                            term: scopeValue('term'),
+                            block: scopeValue('block'),
+                        } : undefined,
+                        snapshotId: projectSnapshot().snapshotId,
+                    });
+                    if (!hint) {
+                        res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: false, error: 'Hint not found.' }));
+                        return;
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: true, hint }));
+                }
+                catch (error) {
+                    res.writeHead(error instanceof Error && error.name === 'HintLifecycleError' ? 409 : 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+                }
+                return;
+            }
+            const hintLifecycleMatch = /^\/api\/agent\/hints\/([^/]+)\/lifecycle$/.exec(path);
+            if (req.method === 'POST' && hintLifecycleMatch) {
+                try {
+                    const hintId = decodeURIComponent(hintLifecycleMatch[1]);
+                    const body = await readJSON(req).catch(() => null);
+                    const action = body?.action;
+                    const reviewer = typeof body?.reviewer === 'string' && body.reviewer.trim()
+                        ? body.reviewer.trim()
+                        : (resolveLocalOwner(projectRoot) ?? 'local');
+                    const note = typeof body?.note === 'string' && body.note.trim() ? body.note.trim() : undefined;
+                    let result;
+                    if (action === 'retire') {
+                        result = retireHint(projectRoot, { hintId, reviewer, note });
+                    }
+                    else if (action === 'reopen') {
+                        result = await reopenGovernedHint(projectRoot, {
+                            hintId,
+                            reviewer,
+                            note,
+                            snapshotId: projectSnapshot().snapshotId,
+                        });
+                    }
+                    else if (action === 'supersede') {
+                        const targetHintId = typeof body?.targetHintId === 'string' ? body.targetHintId.trim() : '';
+                        if (!targetHintId) {
+                            res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                            res.end(serializeJSON({ ok: false, error: 'targetHintId is required for supersede.' }));
+                            return;
+                        }
+                        result = supersedeHint(projectRoot, { hintId, targetHintId, reviewer, note });
+                    }
+                    else {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: false, error: "action must be 'retire', 'reopen', or 'supersede'." }));
+                        return;
+                    }
+                    if (!result) {
+                        res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ ok: false, error: 'Hint not found.' }));
+                        return;
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: true, hint: result.hint, review: result.review }));
+                }
+                catch (error) {
+                    res.writeHead(error instanceof Error && error.name === 'HintLifecycleError' ? 409 : 500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
                 }
                 return;
             }
@@ -6633,85 +6823,30 @@ export async function startLocalServer(opts) {
                         : (resolveLocalOwner(projectRoot) ?? 'local');
                     const note = typeof body?.note === 'string' && body.note.trim() ? body.note.trim() : undefined;
                     const snapshotId = projectSnapshot().snapshotId;
-                    // dbt-first v3 requires a PASSED evaluation artifact recorded against the
-                    // same snapshot before a candidate may be approved. Approving from the
-                    // review queue therefore runs the hint's required evaluation first: the
-                    // corrected SQL is re-validated against the current project so a hint can
-                    // never be promoted on evidence that has gone stale.
-                    if (decision === 'approved') {
-                        const pending = listHintsFromGit(projectRoot).find((entry) => entry.id === hintId);
-                        if (pending?.status === 'candidate' && pending.requiredEvaluation && !pending.evaluationId) {
-                            // The evaluation must be a real check, not a rubber stamp: the
-                            // corrected SQL has to parse and reference at least one relation
-                            // against the CURRENT project. A correction that no longer analyses
-                            // cannot be promoted into everyone's prompt.
-                            const validation = (() => {
-                                const sql = pending.correctedSql?.trim();
-                                if (!sql)
-                                    return { ok: false, error: 'The correction carries no SQL to verify.' };
-                                try {
-                                    const analysis = analyzeSqlReferences(sql);
-                                    if (!analysis.tables.length)
-                                        return { ok: false, error: 'Corrected SQL references no known relation.' };
-                                    return { ok: true };
-                                }
-                                catch (error) {
-                                    return { ok: false, error: error instanceof Error ? error.message : String(error) };
-                                }
-                            })();
-                            try {
-                                evaluateHint(projectRoot, {
-                                    hintId,
-                                    snapshotId,
-                                    evaluator: reviewer,
-                                    evaluation: pending.requiredEvaluation,
-                                    checks: [{
-                                            name: 'corrected-sql-validates',
-                                            passed: validation.ok,
-                                            evidence: validation.ok ? 'Corrected SQL passed local context validation.' : validation.error,
-                                        }],
-                                    evidence: [`snapshot: ${snapshotId}`, `reviewer: ${reviewer}`],
-                                });
-                            }
-                            catch (evaluationError) {
-                                res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
-                                res.end(serializeJSON({ ok: false, error: evaluationError instanceof Error ? evaluationError.message : String(evaluationError) }));
-                                return;
-                            }
-                        }
-                    }
-                    const reviewed = reviewHint(projectRoot, { hintId, decision, reviewer, snapshotId, ...(note ? { note } : {}) });
+                    const reviewed = await reviewGovernedHint(projectRoot, {
+                        hintId,
+                        decision,
+                        reviewer,
+                        snapshotId,
+                        ...(note ? { note } : {}),
+                        ...(decision === 'approved' ? {
+                            executeSql: async (sql, execution) => executeGeneratedSqlForAgent(sql, {
+                                ...generatedSqlArtifactContract(execution.question, sql),
+                                limit: execution.rowLimit,
+                            }),
+                        } : {}),
+                    });
                     if (!reviewed) {
                         res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
                         res.end(serializeJSON({ ok: false, error: 'Hint not found.' }));
                         return;
                     }
                     const hint = reviewed.hint;
-                    // Keep the mirrored advisory memory in step with the decision, so an
-                    // approved lesson is recalled and a rejected one stops being recalled.
-                    try {
-                        const memory = new MemoryStore(defaultMemoryPath(projectRoot));
-                        memory.upsert({
-                            id: `mem_${hint.id}`,
-                            scope: 'project',
-                            title: hint.title,
-                            content: hint.guidance,
-                            tags: [hint.scope.metric, hint.scope.domain, hint.scope.dbtModel].filter((x) => Boolean(x)),
-                            source: 'correction',
-                            confidence: 0.9,
-                            importance: 0.85,
-                            enabled: decision === 'approved',
-                        });
-                        memory.close();
-                    }
-                    catch {
-                        /* best-effort */
-                    }
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ ok: true, hint }));
+                    res.end(serializeJSON({ ok: true, hint, evaluation: reviewed.evaluation }));
                 }
                 catch (error) {
-                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.writeHead(error instanceof Error && error.name === 'HintLifecycleError' ? 409 : 500, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ ok: false, error: error instanceof Error ? error.message : String(error) }));
                 }
                 return;
@@ -6757,12 +6892,12 @@ export async function startLocalServer(opts) {
                     const correctionFailedRoute = typeof body.failedRoute === 'string' && body.failedRoute.trim()
                         ? body.failedRoute.trim()
                         : 'generated_answer';
-                    // Must match the name emitCorrectionEvalCase writes, so the required
-                    // evaluation and the emitted regression case are the same artifact.
+                    // Stable name linked to the Git evaluation artifacts created during
+                    // review. Capture itself does not silently write a regression source.
                     const correctionEvaluation = typeof body.requiredEvaluation === 'string' && body.requiredEvaluation.trim()
                         ? body.requiredEvaluation.trim()
                         : `correction: ${question.slice(0, 60)}`;
-                    const { trace, hint } = recordCorrectionTrace(projectRoot, {
+                    const { trace, hint } = await recordGovernedCorrection(projectRoot, {
                         question,
                         scope,
                         wrongAnswer: wrongSql || '(no prior SQL captured)',
@@ -6778,49 +6913,19 @@ export async function startLocalServer(opts) {
                         hintGuidance: typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance.trim() : undefined,
                         tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
                     });
-                    // Capture always, approve deliberately. A hint is injected into the
-                    // generation prompt as a "human-approved correction" and shapes every
-                    // future answer in scope — one analyst's local fix must not silently
-                    // become a team-wide rule across thousands of models. The trace and the
-                    // candidate are always recorded, so nothing is lost; approval is a
-                    // one-click review in Settings. Callers may still opt in explicitly.
-                    let approvedHint = hint;
-                    if (body.approve === true) {
-                        reviewHint(projectRoot, { hintId: hint.id, decision: 'approved', reviewer: author ?? 'local', note: 'Approved on capture.' });
-                        approvedHint = { ...hint, status: 'approved' };
-                    }
-                    // W4.3 — turn the correction into a durable regression eval case so the wrong
-                    // answer can never silently return. Best-effort; never blocks the correction.
-                    try {
-                        emitCorrectionEvalCase(projectRoot, { question, correctedSql, name: correctionEvaluation });
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                    // Plain-language advisory memory mirroring the lesson, for transparency + recall.
-                    try {
-                        const memory = new MemoryStore(defaultMemoryPath(projectRoot));
-                        memory.upsert({
-                            id: `mem_${hint.id}`,
-                            scope: 'project',
-                            title: approvedHint.title,
-                            content: `${approvedHint.guidance}${rationale ? ` (${rationale})` : ''}`,
-                            tags: [scope.metric, scope.domain, scope.dbtModel].filter((x) => Boolean(x)),
-                            source: 'correction',
-                            confidence: 0.9,
-                            importance: 0.85,
-                            // A candidate is evidence, not a rule. Mirroring it as an ENABLED
-                            // memory would inject it into prompts through the side door and
-                            // defeat the approval gate; it is enabled when the hint is approved.
-                            enabled: approvedHint.status === 'approved',
-                        });
-                        memory.close();
-                    }
-                    catch {
-                        /* best-effort */
-                    }
+                    // `approve` is intentionally ignored: capture never promotes a hint.
+                    // Review must use /api/agent/hints/:id/review so the same evidence gates
+                    // run for notebook, CLI runtime, and MCP callers.
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ ok: true, trace, hint: approvedHint }));
+                    res.end(serializeJSON({
+                        ok: true,
+                        trace,
+                        hint,
+                        approvalRequested: body.approve === true,
+                        note: body.approve === true
+                            ? 'Captured as a candidate. Automatic approval is not permitted; use the review queue.'
+                            : undefined,
+                    }));
                 }
                 catch (error) {
                     res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -6984,7 +7089,7 @@ export async function startLocalServer(opts) {
                                 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 tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot);
                                 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)] }));
@@ -7054,7 +7159,7 @@ export async function startLocalServer(opts) {
                             const absBlockPath = join(projectRoot, block.filePath);
                             const source = readFileSync(absBlockPath, 'utf-8');
                             const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                            const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                            const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot);
                             const boundParameters = dashboardTileParameterValues({
                                 item,
                                 dashboardValues: dashboardVariables,
@@ -7303,12 +7408,31 @@ export async function startLocalServer(opts) {
             if (req.method === 'POST' && path === '/api/notebooks') {
                 try {
                     const body = await readJSON(req);
-                    const { name, template } = body;
+                    const { name, template, ownerDomain, usesDomains } = body;
                     if (!name || typeof name !== 'string') {
                         res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                         res.end(serializeJSON({ error: 'Missing notebook name' }));
                         return;
                     }
+                    const normalizedOwnerDomain = typeof ownerDomain === 'string' && ownerDomain.trim()
+                        ? ownerDomain.trim()
+                        : undefined;
+                    if (normalizedOwnerDomain && !loadDomainPackageRegistry(projectRoot).get(normalizedOwnerDomain)) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: `Unknown domain: ${normalizedOwnerDomain}` }));
+                        return;
+                    }
+                    const normalizedUsesDomains = Array.from(new Set([
+                        ...(normalizedOwnerDomain ? [normalizedOwnerDomain] : []),
+                        ...(Array.isArray(usesDomains) ? usesDomains : []),
+                    ].map((domain) => typeof domain === 'string' ? domain.trim() : '').filter(Boolean)));
+                    const registry = loadDomainPackageRegistry(projectRoot);
+                    const unknownUsedDomain = normalizedUsesDomains.find((domain) => !registry.get(domain));
+                    if (unknownUsedDomain) {
+                        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ error: `Unknown domain: ${unknownUsedDomain}` }));
+                        return;
+                    }
                     const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'notebook';
                     const nbDir = join(projectRoot, 'notebooks');
                     mkdirSync(nbDir, { recursive: true });
@@ -7318,7 +7442,10 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Notebook already exists' }));
                         return;
                     }
-                    const content = buildNotebookTemplate(name, template ?? 'blank');
+                    const content = buildNotebookTemplate(name, template ?? 'blank', {
+                        ownerDomain: normalizedOwnerDomain,
+                        usesDomains: normalizedUsesDomains,
+                    });
                     writeFileSync(nbPath, content, 'utf-8');
                     res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ path: `notebooks/${slug}.dqlnb`, content }));
@@ -8020,6 +8147,15 @@ export async function startLocalServer(opts) {
             if (req.method === 'POST' && path === '/api/git/pull') {
                 try {
                     const result = await gitPull(projectRoot);
+                    if (result.ok) {
+                        try {
+                            await refreshUnifiedProjectIndexes(projectRoot);
+                        }
+                        catch (error) {
+                            const refreshWarning = `Git pull succeeded, but local DQL indexes could not be refreshed: ${error instanceof Error ? error.message : String(error)}`;
+                            result.output = [result.output, refreshWarning].filter(Boolean).join('\n');
+                        }
+                    }
                     res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(result));
                 }
@@ -8033,6 +8169,9 @@ export async function startLocalServer(opts) {
                 try {
                     const body = (await readJSON(req));
                     const result = await gitCreateBranch(projectRoot, body.name ?? '', body.checkout !== false);
+                    if (result.ok && body.checkout !== false) {
+                        await refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
+                    }
                     res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(result));
                 }
@@ -8046,6 +8185,8 @@ export async function startLocalServer(opts) {
                 try {
                     const body = (await readJSON(req));
                     const result = await gitCheckout(projectRoot, body.name ?? '');
+                    if (result.ok)
+                        await refreshUnifiedProjectIndexes(projectRoot).catch(() => undefined);
                     res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(result));
                 }
@@ -8076,13 +8217,45 @@ export async function startLocalServer(opts) {
                     const schemaLimit = Math.min(500, Math.max(1, Number(url.searchParams.get('limit')) || 200));
                     const schemaOffset = Math.max(0, Number(url.searchParams.get('offset')) || 0);
                     const schemaSearch = (url.searchParams.get('q') ?? '').trim();
-                    const { tables, columnsByPath } = connection
-                        ? await introspectSchema(executor, connection, {
-                            limit: schemaLimit,
-                            offset: schemaOffset,
-                            search: schemaSearch,
+                    const activeScope = connection
+                        ? optionalActiveConnectionMetadataScope(projectRoot, projectConfig, connection, projectConfig.defaultConnectionName ?? 'default')
+                        : null;
+                    const cachedSnapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+                    const cachedScopeMatches = Boolean(cachedSnapshot
+                        && activeScope
+                        && cachedSnapshot.scopeFingerprint === activeScope.scopeFingerprint);
+                    const cachedTables = cachedScopeMatches
+                        ? cachedSnapshot.tables
+                            .filter((table) => {
+                            if (!schemaSearch)
+                                return true;
+                            const needle = schemaSearch.toLowerCase();
+                            return table.relation.toLowerCase().includes(needle)
+                                || table.name?.toLowerCase().includes(needle)
+                                || table.schema?.toLowerCase().includes(needle);
                         })
-                        : { tables: [], columnsByPath: new Map() };
+                            .slice(schemaOffset, schemaOffset + schemaLimit)
+                        : [];
+                    const { tables, columnsByPath } = cachedScopeMatches
+                        ? {
+                            tables: cachedTables.map((table) => ({
+                                schema: table.schema ?? '',
+                                name: table.name ?? table.relation.split('.').at(-1) ?? table.relation,
+                                path: table.relation,
+                                type: 'TABLE',
+                            })),
+                            columnsByPath: new Map(cachedTables.map((table) => [
+                                table.relation,
+                                table.columns.map((column) => ({ name: column.name, type: column.type ?? '' })),
+                            ])),
+                        }
+                        : connection
+                            ? await introspectSchema(executor, connection, {
+                                limit: schemaLimit,
+                                offset: schemaOffset,
+                                search: schemaSearch,
+                            })
+                            : { tables: [], columnsByPath: new Map() };
                     const dbTables = tables.map((t) => ({
                         name: t.path,
                         path: t.path,
@@ -8133,7 +8306,7 @@ export async function startLocalServer(opts) {
             if (req.method === 'POST' && path === '/api/blocks') {
                 try {
                     const body = await readJSON(req);
-                    const { name, domain, content, description, tags, metricRefs, template, blockType, } = body;
+                    const { name, domain, content, description, tags, folderPath, metricRefs, template, blockType, } = body;
                     if (!name || typeof name !== 'string') {
                         res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                         res.end(serializeJSON({ error: 'Missing block name' }));
@@ -8150,6 +8323,7 @@ export async function startLocalServer(opts) {
                         content,
                         description,
                         tags,
+                        folderPath,
                         metricRefs,
                         template,
                         blockType,
@@ -8301,7 +8475,7 @@ export async function startLocalServer(opts) {
                                     const llmMatch = /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/.exec(source);
                                     blocks.push({
                                         name: nameMatch?.[1] ?? entry.name.replace('.dql', ''),
-                                        domain: (domainMatch?.[1] ?? inferBlockStudioPathDomain(relPath)) || 'uncategorized',
+                                        domain: (domainMatch?.[1] ?? inferBlockStudioPathDomain(projectRoot, relPath)) || 'uncategorized',
                                         status: statusMatch?.[1] ?? 'draft',
                                         owner: ownerMatch?.[1] ?? null,
                                         tags: parsedTags,
@@ -8523,7 +8697,7 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const activeConnection = requireActiveConnection();
-                    const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer);
+                    const tableMapping = await resolveSemanticTableMapping(executor, activeConnection, semanticLayer, projectRoot);
                     const semanticCompose = semanticLayer
                         ? await composeSemanticBlockSqlForRuntime(source, semanticLayer, {
                             driver: activeConnection.driver,
@@ -9445,7 +9619,7 @@ export async function startLocalServer(opts) {
                         driver = undefined;
                     }
                     const tableMapping = composeConnection
-                        ? await resolveSemanticTableMapping(executor, composeConnection, semanticLayer)
+                        ? await resolveSemanticTableMapping(executor, composeConnection, semanticLayer, projectRoot)
                         : undefined;
                     const composed = composeSemanticQueryForQuestion({
                         semanticLayer,
@@ -9649,6 +9823,105 @@ export async function startLocalServer(opts) {
                 }
                 return;
             }
+            const metadataScopePreviewMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-scope\/preview$/);
+            const metadataScopeMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-scope$/);
+            const metadataSyncMatch = path.match(/^\/api\/connections\/([^/]+)\/metadata-sync$/);
+            if (metadataScopePreviewMatch && req.method === 'POST') {
+                try {
+                    const connectionId = decodeURIComponent(metadataScopePreviewMatch[1]);
+                    const cfg = loadProjectConfig(projectRoot);
+                    const selectedConnection = projectConnectionById(projectRoot, cfg, connectionId);
+                    if (!selectedConnection)
+                        throw new Error(`Unknown connection "${connectionId}".`);
+                    const body = await readJSON(req).catch(() => ({}));
+                    const scope = normalizeConnectionMetadataScope(connectionId, selectedConnection, body, metadataScopeDbtDefaults(projectRoot, cfg));
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        scope,
+                        status: warehouseMetadataStatus(projectRoot, scope.scopeFingerprint),
+                    }));
+                }
+                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 (metadataScopeMatch && req.method === 'GET') {
+                try {
+                    const connectionId = decodeURIComponent(metadataScopeMatch[1]);
+                    const cfg = loadProjectConfig(projectRoot);
+                    const selectedConnection = projectConnectionById(projectRoot, cfg, connectionId);
+                    if (!selectedConnection)
+                        throw new Error(`Unknown connection "${connectionId}".`);
+                    const scope = normalizeConnectionMetadataScope(connectionId, selectedConnection, configuredMetadataScopeInput(cfg, connectionId), metadataScopeDbtDefaults(projectRoot, cfg));
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        scope,
+                        status: warehouseMetadataStatus(projectRoot, scope.scopeFingerprint),
+                    }));
+                }
+                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 (metadataScopeMatch && req.method === 'PUT') {
+                try {
+                    const connectionId = decodeURIComponent(metadataScopeMatch[1]);
+                    const cfg = loadProjectConfig(projectRoot);
+                    const selectedConnection = projectConnectionById(projectRoot, cfg, connectionId);
+                    if (!selectedConnection)
+                        throw new Error(`Unknown connection "${connectionId}".`);
+                    const body = await readJSON(req);
+                    const scope = normalizeConnectionMetadataScope(connectionId, selectedConnection, body, metadataScopeDbtDefaults(projectRoot, cfg));
+                    const synced = await syncWarehouseMetadata({
+                        projectRoot,
+                        executor,
+                        connection: selectedConnection,
+                        scope,
+                    });
+                    persistConnectionMetadataScope(projectRoot, connectionId, scope);
+                    projectConfig = loadProjectConfig(projectRoot);
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        scope: synced.scope,
+                        status: warehouseMetadataStatus(projectRoot, synced.scope.scopeFingerprint),
+                    }));
+                }
+                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 (metadataSyncMatch && req.method === 'POST') {
+                try {
+                    const connectionId = decodeURIComponent(metadataSyncMatch[1]);
+                    const cfg = loadProjectConfig(projectRoot);
+                    const selectedConnection = projectConnectionById(projectRoot, cfg, connectionId);
+                    if (!selectedConnection)
+                        throw new Error(`Unknown connection "${connectionId}".`);
+                    const scope = normalizeConnectionMetadataScope(connectionId, selectedConnection, configuredMetadataScopeInput(cfg, connectionId), metadataScopeDbtDefaults(projectRoot, cfg));
+                    const synced = await syncWarehouseMetadata({
+                        projectRoot,
+                        executor,
+                        connection: selectedConnection,
+                        scope,
+                    });
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        scope: synced.scope,
+                        status: warehouseMetadataStatus(projectRoot, synced.scope.scopeFingerprint),
+                    }));
+                }
+                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/connections') {
                 const cfg = loadProjectConfig(projectRoot);
                 const connections = getProjectConnectionsForApi(cfg);
@@ -9665,8 +9938,21 @@ export async function startLocalServer(opts) {
                     ...(Object.keys(connections).length === 0 && activeDbtProfile ? { profileId: activeDbtProfile.id } : {}),
                 } : null;
                 const connectorStatus = getConnectorInstallStatuses(projectRoot);
+                const metadataScope = connection
+                    ? optionalActiveConnectionMetadataScope(projectRoot, cfg, connection, defaultKey)
+                    : null;
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ default: defaultKey, connections, dbtProfiles, activeConnection, connectorStatus }));
+                res.end(serializeJSON({
+                    default: defaultKey,
+                    connections,
+                    dbtProfiles,
+                    activeConnection,
+                    connectorStatus,
+                    metadataScope,
+                    metadataStatus: metadataScope
+                        ? warehouseMetadataStatus(projectRoot, metadataScope.scopeFingerprint)
+                        : warehouseMetadataStatus(projectRoot),
+                }));
                 return;
             }
             if (req.method === 'POST' && path === '/api/connections/dbt-profiles/preview') {
@@ -11113,7 +11399,7 @@ export async function startLocalServer(opts) {
                     }
                     const executionConnection = await resolveExecutionConnection(body);
                     const tableMapping = hasStandaloneSemanticRef(body.sql)
-                        ? await resolveSemanticTableMapping(executor, executionConnection, semanticLayer)
+                        ? await resolveSemanticTableMapping(executor, executionConnection, semanticLayer, projectRoot)
                         : undefined;
                     const semantic = prepareSemanticSql(body.sql, semanticLayer, { tableMapping });
                     if (semantic.unresolvedRefs.length > 0) {
@@ -11243,7 +11529,7 @@ export async function startLocalServer(opts) {
                         metricFlow,
                         compile: async () => {
                             const tableMapping = plannedAdapter === 'native'
-                                ? await resolveSemanticTableMapping(executor, targetConnection, semanticLayer)
+                                ? await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot)
                                 : undefined;
                             return composeRuntimeSemanticQuery({
                                 metrics,
@@ -11346,7 +11632,7 @@ export async function startLocalServer(opts) {
                         metricFlow,
                         compile: async () => {
                             const tableMapping = plannedAdapter === 'native'
-                                ? await resolveSemanticTableMapping(executor, targetConnection, semanticLayer)
+                                ? await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot)
                                 : undefined;
                             return composeRuntimeSemanticQuery({
                                 metrics,
@@ -11441,7 +11727,7 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const targetConnection = await resolveExecutionConnection(body);
-                    const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer);
+                    const tableMapping = await resolveSemanticTableMapping(executor, targetConnection, semanticLayer, projectRoot);
                     const composed = await composeRuntimeSemanticQuery({
                         metrics,
                         dimensions,
@@ -11818,7 +12104,9 @@ export async function startLocalServer(opts) {
                     const sourceRefreshedFromDisk = Boolean(requestedBlockName)
                         && receiptSource.trim().length > 0
                         && receiptSource !== source;
-                    if (expectedReceipt && !sourceRefreshedFromDisk && expectedReceipt.sourceFingerprint !== executionFingerprint(source)) {
+                    if (expectedReceipt
+                        && !sourceRefreshedFromDisk
+                        && !executionSourceFingerprintMatches(expectedReceipt.sourceFingerprint, source)) {
                         throw new Error('DQL artifact source changed after the answer was produced. Refresh the answer before applying it.');
                     }
                     const parameters = body.parameters && typeof body.parameters === 'object' && !Array.isArray(body.parameters)
@@ -11958,7 +12246,7 @@ export async function startLocalServer(opts) {
                     }
                     const cellConnection = await resolveExecutionConnection(body);
                     const tableMapping = needsSemanticTableMapping(executableCell)
-                        ? await resolveSemanticTableMapping(executor, cellConnection, semanticLayer)
+                        ? await resolveSemanticTableMapping(executor, cellConnection, semanticLayer, projectRoot)
                         : undefined;
                     const semanticCompose = executableCell.type === 'dql'
                         && semanticLayer
@@ -12297,9 +12585,9 @@ FROM from_counts, to_counts, joined, unmatched, from_max, to_max`;
             : 'Warehouse evidence does not prove the declared cardinality and safe fanout policy.',
     };
 }
-function relatedProductsForDomain(manifest, domainId) {
+function relatedProductsForDomain(manifest, domainId, liveNotebookFiles = []) {
     const apps = Object.values(manifest.apps ?? {})
-        .filter((app) => app.ownerDomain === domainId || app.usesDomains.includes(domainId))
+        .filter((app) => !domainId || app.ownerDomain === domainId || app.usesDomains.includes(domainId))
         .map((app) => ({
         id: app.id,
         name: app.name,
@@ -12312,8 +12600,8 @@ function relatedProductsForDomain(manifest, domainId) {
         lifecycle: app.lifecycle,
         legacyLayout: app.filePath.startsWith('domains/'),
     }));
-    const notebooks = Object.entries(manifest.notebooks)
-        .filter(([, notebook]) => notebook.ownerDomain === domainId || notebook.usesDomains.includes(domainId))
+    const compiledNotebooks = Object.entries(manifest.notebooks)
+        .filter(([, notebook]) => !domainId || notebook.ownerDomain === domainId || notebook.usesDomains.includes(domainId))
         .map(([id, notebook]) => ({
         id,
         title: notebook.title,
@@ -12325,6 +12613,29 @@ function relatedProductsForDomain(manifest, domainId) {
         classification: notebook.classification,
         legacyLayout: notebook.filePath.startsWith('domains/'),
     }));
+    const notebooksByPath = new Map(compiledNotebooks.map((notebook) => [String(notebook.filePath), notebook]));
+    for (const file of liveNotebookFiles) {
+        if (file.type !== 'notebook')
+            continue;
+        const usesDomains = file.usesDomains ?? [];
+        if (domainId && file.ownerDomain !== domainId && !usesDomains.includes(domainId))
+            continue;
+        if (notebooksByPath.has(file.path))
+            continue;
+        notebooksByPath.set(file.path, {
+            id: file.path,
+            title: file.name,
+            filePath: file.path,
+            ownerDomain: file.ownerDomain,
+            usesDomains,
+            purpose: undefined,
+            requiredExports: [],
+            classification: undefined,
+            legacyLayout: file.path.startsWith('domains/'),
+        });
+    }
+    const notebooks = [...notebooksByPath.values()]
+        .sort((a, b) => String(a.title).localeCompare(String(b.title)));
     return { apps, notebooks };
 }
 function domainWorkspaceSummary(manifest, domainId) {
@@ -12709,6 +13020,8 @@ export function analyticalFreshnessObservedThrough(result, request) {
 function serializeSkill(skill) {
     return {
         id: skill.id,
+        localId: skill.localId,
+        qualifiedId: skill.qualifiedId,
         scope: 'project',
         user: undefined,
         domain: skill.domain,
@@ -13875,6 +14188,19 @@ function createDqlArtifactExecutionReceipt(source, compiledSql, parameters, resu
 function executionFingerprint(value) {
     return createHash('sha256').update(value).digest('hex');
 }
+/**
+ * Older clients normalized executable DQL with trim(), while the receipt was
+ * correctly created from the original renderer output ending in one newline.
+ * Accept only that exact legacy line-ending variant; any substantive source
+ * change still fails closed.
+ */
+function executionSourceFingerprintMatches(expected, source) {
+    return [
+        source,
+        `${source}\n`,
+        `${source}\r\n`,
+    ].some((candidate) => executionFingerprint(candidate) === expected);
+}
 function stableExecutionValue(value) {
     const seen = new WeakSet();
     return JSON.stringify(value, (_key, item) => {
@@ -13986,6 +14312,66 @@ function getProjectConnectionsForApi(config) {
     }
     return connections;
 }
+function metadataScopeDbtDefaults(projectRoot, config) {
+    const manifestPath = resolveDbtManifestPath(projectRoot, config);
+    if (!manifestPath || !existsSync(manifestPath))
+        return { relations: [] };
+    try {
+        const source = readFileSync(manifestPath, 'utf-8');
+        const lookup = buildDbtRelationLookup(JSON.parse(source));
+        return {
+            relations: Array.from(new Set([...lookup.models.values(), ...lookup.sources.values()])).sort(),
+            dbtFingerprint: createHash('sha256').update(source).digest('hex'),
+        };
+    }
+    catch {
+        return { relations: [] };
+    }
+}
+function configuredMetadataScopeInput(config, connectionId) {
+    const value = config.metadataScopes?.[connectionId];
+    return value && typeof value === 'object' ? value : undefined;
+}
+function activeConnectionMetadataScope(projectRoot, config, activeConnection, connectionId = config.defaultConnectionName ?? 'default') {
+    return normalizeConnectionMetadataScope(connectionId, activeConnection, configuredMetadataScopeInput(config, connectionId), metadataScopeDbtDefaults(projectRoot, config));
+}
+function optionalActiveConnectionMetadataScope(projectRoot, config, activeConnection, connectionId) {
+    try {
+        return activeConnectionMetadataScope(projectRoot, config, activeConnection, connectionId);
+    }
+    catch {
+        return null;
+    }
+}
+function projectConnectionById(projectRoot, config, connectionId) {
+    const stored = getStoredConnections(config);
+    const normalized = normalizeStoredConnection(stored[connectionId]);
+    if (normalized)
+        return normalizeProjectConnection(normalized, projectRoot);
+    if (connectionId === (config.defaultConnectionName ?? 'default') && config.defaultConnection) {
+        return normalizeProjectConnection(config.defaultConnection, projectRoot);
+    }
+    return null;
+}
+function persistConnectionMetadataScope(projectRoot, connectionId, scope) {
+    const configPath = join(projectRoot, 'dql.config.json');
+    const raw = existsSync(configPath)
+        ? JSON.parse(readFileSync(configPath, 'utf-8'))
+        : {};
+    const existing = raw.metadataScopes && typeof raw.metadataScopes === 'object' && !Array.isArray(raw.metadataScopes)
+        ? raw.metadataScopes
+        : {};
+    raw.metadataScopes = {
+        ...existing,
+        [connectionId]: {
+            mode: scope.mode,
+            scopes: scope.selectedScopes,
+            relations: scope.relations.length > 0 ? scope.relations : undefined,
+            dbtFingerprint: scope.dbtFingerprint,
+        },
+    };
+    writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n', 'utf-8');
+}
 const CONNECTOR_INSTALLS = {
     duckdb: {
         driver: 'duckdb',
@@ -15340,6 +15726,7 @@ function scanNotebookFiles(projectRoot) {
                     path: relativePath,
                     type,
                     folder: relativeDir,
+                    ...readNotebookFileProductContext(fullPath, type),
                 });
             }
         }
@@ -15364,12 +15751,29 @@ function scanNotebookFiles(projectRoot) {
                     path: relativePath,
                     type,
                     folder: relativeDir.split('/')[0] ?? relativeDir,
+                    ...readNotebookFileProductContext(fullPath, type),
                 });
             }
         }
         catch { /* skip unreadable dirs */ }
     }
 }
+function readNotebookFileProductContext(fullPath, type) {
+    if ((type !== 'notebook' && type !== 'workbook') || !fullPath.endsWith('.dqlnb'))
+        return {};
+    try {
+        const metadata = deserializeNotebook(readFileSync(fullPath, 'utf-8')).metadata;
+        return {
+            ...(metadata.ownerDomain ? { ownerDomain: metadata.ownerDomain } : {}),
+            usesDomains: metadata.usesDomains ?? [],
+        };
+    }
+    catch {
+        // A malformed notebook must remain visible in the file list so the user
+        // can open and repair it; it simply falls back to the Project folder.
+        return {};
+    }
+}
 function inferDqlArtifactName(fullPath, type, fallbackName) {
     if (!fullPath.endsWith('.dql'))
         return fallbackName;
@@ -15573,15 +15977,15 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         throw new Error(`File not found: ${normalizedPath}`);
     }
     const source = readFileSync(absPath, 'utf-8');
-    const companionPath = blockCompanionRelativePath(normalizedPath);
+    const companionPath = blockCompanionRelativePath(projectRoot, normalizedPath);
     const companion = companionPath ? readBlockCompanionFile(projectRoot, companionPath) : null;
     const parsedMetadata = parseBlockSourceMetadata(source);
     const fileName = normalizedPath.split('/').pop()?.replace(/\.dql$/, '') ?? 'block';
     const metadata = {
         name: parsedMetadata.name || companion?.name || fileName,
         path: normalizedPath,
-        domain: parsedMetadata.domain || companion?.domain || inferBlockStudioPathDomain(normalizedPath) || 'uncategorized',
-        folderPath: inferBlockStudioFolderPath(normalizedPath),
+        domain: parsedMetadata.domain || companion?.domain || inferBlockStudioPathDomain(projectRoot, normalizedPath) || 'uncategorized',
+        folderPath: inferBlockStudioFolderPath(projectRoot, normalizedPath),
         description: parsedMetadata.description || companion?.description || '',
         owner: parsedMetadata.owner || companion?.owner || '',
         tags: parsedMetadata.tags.length > 0 ? parsedMetadata.tags : companion?.tags ?? [],
@@ -15640,9 +16044,20 @@ function parseSemanticBlockConfig(source) {
         limit: limitMatch ? Number.parseInt(limitMatch[1], 10) : undefined,
     };
 }
-export async function resolveSemanticTableMapping(executor, connection, semanticLayer) {
+export async function resolveSemanticTableMapping(executor, connection, semanticLayer, projectRoot) {
     if (!semanticLayer)
         return undefined;
+    if (projectRoot) {
+        const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+        if (snapshot?.scopeFingerprint && snapshot.tables.length) {
+            return buildSemanticTableMapping(semanticLayer, snapshot.tables.map((table) => ({
+                table_catalog: table.catalogOrDatabase,
+                table_schema: table.schema,
+                table_name: table.name ?? table.relation.split('.').at(-1),
+                table_relation: table.relation,
+            })));
+        }
+    }
     try {
         const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
        FROM information_schema.tables
@@ -15660,10 +16075,11 @@ export function buildSemanticTableMapping(semanticLayer, rows) {
     for (const row of rows) {
         const schema = String(row['table_schema'] ?? '');
         const name = String(row['table_name'] ?? '');
+        const relation = typeof row['table_relation'] === 'string' ? row['table_relation'] : undefined;
         if (!name)
             continue;
         dbTableNames.add(name);
-        schemaQualified.set(name, schema ? `${schema}.${name}` : name);
+        schemaQualified.set(name, relation ?? (schema ? `${schema}.${name}` : name));
     }
     const tableMapping = {};
     const allSemanticTables = new Set();
@@ -16587,7 +17003,7 @@ export function saveBlockStudioArtifacts(projectRoot, options) {
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
-        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/[^a-z0-9._/-]+/g, '-')
         .replace(/^\/+|\/+$/g, '') || 'uncategorized';
     const safeFolderPath = normalizeBlockStudioFolderPath(options.folderPath);
     const previousPath = options.currentPath ? normalize(options.currentPath).replace(/^\/+/, '') : null;
@@ -16615,7 +17031,7 @@ export function saveBlockStudioArtifacts(projectRoot, options) {
         const previousAbsPath = join(projectRoot, previousPath);
         if (existsSync(previousAbsPath))
             rmSync(previousAbsPath, { force: true });
-        const previousCompanion = blockCompanionRelativePath(previousPath);
+        const previousCompanion = blockCompanionRelativePath(projectRoot, previousPath);
         if (previousCompanion) {
             const previousCompanionPath = join(projectRoot, previousCompanion);
             if (existsSync(previousCompanionPath))
@@ -16643,7 +17059,7 @@ export function deleteBlockStudioArtifacts(projectRoot, relativePath) {
     if (!existsSync(absolutePath)) {
         throw new Error(`File not found: ${normalizedPath}`);
     }
-    const companionPath = blockCompanionRelativePath(normalizedPath);
+    const companionPath = blockCompanionRelativePath(projectRoot, normalizedPath);
     rmSync(absolutePath, { force: true });
     if (companionPath) {
         const absoluteCompanionPath = resolve(rootPath, companionPath);
@@ -16701,7 +17117,12 @@ export function saveBlockStudioDraftArtifacts(projectRoot, options) {
 }
 function canonicalBlockRelativePath(projectRoot, safeDomain, safeFolderPath, slug, previousPath) {
     const folder = safeFolderPath ? `${safeFolderPath}/` : '';
-    const previousDomainFirst = Boolean(previousPath?.match(/^domains\/[^/]+\/blocks\//));
+    const packageRoot = loadDomainPackageRegistry(projectRoot).get(safeDomain)?.root;
+    if (packageRoot) {
+        const relativePackageRoot = relative(projectRoot, packageRoot).replaceAll('\\', '/');
+        return `${relativePackageRoot}/blocks/${folder}${slug}.dql`;
+    }
+    const previousDomainFirst = Boolean(previousPath?.match(/^domains\/.+\/blocks\//));
     if (previousDomainFirst || existsSync(join(projectRoot, 'domains', safeDomain))) {
         return `domains/${safeDomain}/blocks/${folder}${slug}.dql`;
     }
@@ -16724,19 +17145,23 @@ function isDraftBlockPath(value) {
     if (!value)
         return false;
     const normalized = normalize(value).replace(/^\/+/, '');
-    return normalized.startsWith('blocks/_drafts/') || /^domains\/[^/]+\/blocks\/_drafts\//.test(normalized);
+    return normalized.startsWith('blocks/_drafts/') || /^domains\/.+\/blocks\/_drafts\//.test(normalized);
 }
 function isBlockStudioBlockPath(value) {
     if (!value)
         return false;
     const normalized = normalize(value).replace(/^\/+/, '');
-    return normalized.startsWith('blocks/') || /^domains\/[^/]+\/blocks\//.test(normalized);
+    return normalized.startsWith('blocks/') || /^domains\/.+\/blocks\//.test(normalized);
 }
-function inferBlockStudioPathDomain(blockPath) {
+function inferBlockStudioPathDomain(projectRoot, blockPath) {
     const normalized = normalize(blockPath).replace(/^\/+/, '');
     if (normalized.startsWith('blocks/')) {
         return normalized.split('/')[1] ?? '';
     }
+    const resolved = domainBlockPathParts(projectRoot, normalized);
+    if (resolved) {
+        return resolved.subpath.startsWith('_drafts/') ? `_drafts/${resolved.domain}` : resolved.domain;
+    }
     const domainFirst = normalized.match(/^domains\/([^/]+)\/blocks\/(.+)$/);
     if (!domainFirst)
         return '';
@@ -16746,8 +17171,11 @@ function inferBlockStudioPathDomain(blockPath) {
         return `_drafts/${domain}`;
     return domain;
 }
-function inferBlockStudioFolderPath(blockPath) {
+function inferBlockStudioFolderPath(projectRoot, blockPath) {
     const normalized = normalize(blockPath).replace(/^\/+/, '').replaceAll('\\', '/');
+    const resolved = domainBlockPathParts(projectRoot, normalized);
+    if (resolved)
+        return resolved.subpath.split('/').slice(0, -1).join('/');
     const domainFirst = normalized.match(/^domains\/[^/]+\/blocks\/(.+)$/);
     if (domainFirst)
         return domainFirst[1].split('/').slice(0, -1).join('/');
@@ -16756,12 +17184,20 @@ function inferBlockStudioFolderPath(blockPath) {
         return legacy[1].split('/').slice(0, -1).join('/');
     return '';
 }
-function blockCompanionRelativePath(blockPath) {
+function blockCompanionRelativePath(projectRoot, blockPath) {
     const normalized = normalize(blockPath).replace(/^\/+/, '');
     if (normalized.startsWith('blocks/')) {
         const withoutRoot = normalized.slice('blocks/'.length).replace(/\.dql$/, '.yaml');
         return join('semantic-layer', 'blocks', withoutRoot).replaceAll('\\', '/');
     }
+    const resolved = domainBlockPathParts(projectRoot, normalized);
+    if (resolved && resolved.subpath.endsWith('.dql')) {
+        const blockPath = resolved.subpath.replace(/\.dql$/, '');
+        const companionBlockPath = blockPath.startsWith('_drafts/')
+            ? join('_drafts', resolved.domain, blockPath.slice('_drafts/'.length))
+            : join(resolved.domain, blockPath);
+        return join('semantic-layer', 'blocks', `${companionBlockPath}.yaml`).replaceAll('\\', '/');
+    }
     const domainFirst = normalized.match(/^domains\/([^/]+)\/blocks\/(.+)\.dql$/);
     if (domainFirst) {
         const domain = domainFirst[1];
@@ -16773,6 +17209,19 @@ function blockCompanionRelativePath(blockPath) {
     }
     return null;
 }
+function domainBlockPathParts(projectRoot, blockPath) {
+    const normalized = normalize(blockPath).replace(/^\/+/, '').replaceAll('\\', '/');
+    if (!normalized.startsWith('domains/'))
+        return null;
+    const absolute = join(projectRoot, normalized);
+    const pkg = loadDomainPackageRegistry(projectRoot).packageForPath(absolute);
+    if (!pkg)
+        return null;
+    const local = relative(pkg.root, absolute).replaceAll('\\', '/');
+    if (!local.startsWith('blocks/'))
+        return null;
+    return { domain: pkg.id, subpath: local.slice('blocks/'.length) };
+}
 function readBlockCompanionFile(projectRoot, relativePath) {
     const absPath = join(projectRoot, relativePath);
     if (!existsSync(absPath))
@@ -17085,7 +17534,7 @@ export function setBlockStudioStatus(projectRoot, blockPath, newStatus) {
         throw new Error('Block file not found');
     const source = setBlockStudioStatusInSource(readFileSync(absPath, 'utf-8'), newStatus);
     writeFileSync(absPath, source, 'utf-8');
-    const companionPath = blockCompanionRelativePath(normalizedPath);
+    const companionPath = blockCompanionRelativePath(projectRoot, normalizedPath);
     if (!companionPath)
         return;
     const absCompanionPath = join(projectRoot, companionPath);
@@ -18254,16 +18703,18 @@ function buildConversationSystemPrompt(kind, isGeneralKnowledge, catalogContext,
     return lines.join('\n');
 }
 function renderConversationMemoryForPrompt(context) {
+    const envelope = renderConversationEnvelopeForPrompt(context);
     const recap = buildConversationContextRecap(context);
-    if (!recap)
+    if (!recap && !envelope)
         return undefined;
     return [
         'Current conversation context:',
+        envelope,
         recap,
         'If the user asks what this conversation is about, summarize this context directly. Do not query data or invent values.',
-    ].join('\n');
+    ].filter(Boolean).join('\n');
 }
-function buildConversationContextRecap(context) {
+export function buildConversationContextRecap(context) {
     if (!context)
         return undefined;
     const turnRecap = buildConversationTurnsRecap(context);
@@ -18273,10 +18724,7 @@ function buildConversationContextRecap(context) {
     const sourceAnswerSummary = agentRunString(context.sourceAnswerSummary);
     const columns = agentRunStringArray(context.resultColumns ?? context.outputColumns).slice(0, 8);
     const values = agentRunRecord(context.resultDimensionValues);
-    const rows = Array.isArray(context.resultRowsSample)
-        ? context.resultRowsSample.map(agentRunRecord).filter((row) => Boolean(row)).slice(0, 1)
-        : [];
-    const firstRow = rows[0];
+    const firstRow = firstConversationResultRow(context.resultRowsSample, columns);
     const leadParts = buildPriorValueLeadParts(values);
     const rowFacts = firstRow
         ? columns
@@ -18308,16 +18756,19 @@ function buildConversationTurnsRecap(context) {
     const active = activeTurnId
         ? turns.find((turn) => agentRunString(turn.id) === activeTurnId)
         : undefined;
-    const selected = active ?? turns[turns.length - 1];
+    // A recap turn is persisted like every other turn, but it must not become the
+    // subject of the next recap. Prefer the newest analytical/authoring turn and
+    // fall back to the active turn only when the thread contains conversation alone.
+    const substantiveTurns = turns.filter((turn) => agentRunString(turn.route) !== 'conversation');
+    const selected = active && agentRunString(active.route) !== 'conversation'
+        ? active
+        : substantiveTurns[substantiveTurns.length - 1] ?? active ?? turns[turns.length - 1];
     if (!selected)
         return undefined;
     const result = agentRunRecord(selected.result);
     const values = agentRunRecord(result?.dimensionValues);
     const columns = agentRunStringArray(result?.columns).slice(0, 8);
-    const rows = Array.isArray(result?.rowsSample)
-        ? result.rowsSample.map(agentRunRecord).filter((row) => Boolean(row)).slice(0, 1)
-        : [];
-    const firstRow = rows[0];
+    const firstRow = firstConversationResultRow(result?.rowsSample, columns);
     const leadParts = buildPriorValueLeadParts(values);
     const rowFacts = firstRow
         ? columns
@@ -18329,7 +18780,7 @@ function buildConversationTurnsRecap(context) {
             .filter(Boolean)
         : [];
     const previous = turns
-        .filter((turn) => turn !== selected)
+        .filter((turn) => turn !== selected && agentRunString(turn.route) !== 'conversation')
         .map((turn) => agentRunString(turn.question))
         .filter((value) => Boolean(value))
         .slice(-2);
@@ -18343,6 +18794,17 @@ function buildConversationTurnsRecap(context) {
     ].filter(Boolean);
     return bits.length > 0 ? `We were talking about ${bits.join('. ')}.` : undefined;
 }
+function firstConversationResultRow(value, columns) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    const first = value[0];
+    const record = agentRunRecord(first);
+    if (record)
+        return record;
+    if (!Array.isArray(first))
+        return undefined;
+    return Object.fromEntries(columns.map((column, index) => [column, first[index]]));
+}
 function agentRunStringArray(value) {
     if (!Array.isArray(value))
         return [];
@@ -18526,12 +18988,19 @@ export function readGitMetadata(projectRoot) {
         return null;
     }
 }
-function resolveBlockWriteTarget(projectRoot, safeDomain, slug) {
+function resolveBlockWriteTarget(projectRoot, safeDomain, safeFolderPath, slug) {
+    const folder = safeFolderPath ? `${safeFolderPath}/` : '';
+    const packageRoot = safeDomain ? loadDomainPackageRegistry(projectRoot).get(safeDomain)?.root : undefined;
+    if (packageRoot) {
+        const relativePackageRoot = relative(projectRoot, packageRoot).replaceAll('\\', '/');
+        const relativePath = `${relativePackageRoot}/blocks/${folder}${slug}.dql`;
+        return { relativePath, absPath: join(projectRoot, relativePath) };
+    }
     if (safeDomain && existsSync(join(projectRoot, 'domains', safeDomain))) {
-        const relativePath = `domains/${safeDomain}/blocks/${slug}.dql`;
+        const relativePath = `domains/${safeDomain}/blocks/${folder}${slug}.dql`;
         return { relativePath, absPath: join(projectRoot, relativePath) };
     }
-    const relativePath = safeDomain ? `blocks/${safeDomain}/${slug}.dql` : `blocks/${slug}.dql`;
+    const relativePath = safeDomain ? `blocks/${safeDomain}/${folder}${slug}.dql` : `blocks/${folder}${slug}.dql`;
     return { relativePath, absPath: join(projectRoot, relativePath) };
 }
 export function createBlockArtifacts(projectRoot, options) {
@@ -18539,9 +19008,10 @@ export function createBlockArtifacts(projectRoot, options) {
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
-        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/[^a-z0-9._/-]+/g, '-')
         .replace(/^\/+|\/+$/g, '');
-    const target = resolveBlockWriteTarget(projectRoot, safeDomain, slug);
+    const safeFolderPath = normalizeBlockStudioFolderPath(options.folderPath);
+    const target = resolveBlockWriteTarget(projectRoot, safeDomain, safeFolderPath, slug);
     mkdirSync(dirname(target.absPath), { recursive: true });
     const blockPath = target.absPath;
     if (existsSync(blockPath)) {
@@ -18575,6 +19045,7 @@ export function createBlockArtifacts(projectRoot, options) {
         slug,
         name: options.name,
         domain: safeDomain || 'uncategorized',
+        folderPath: safeFolderPath,
         owner: options.owner,
         description: options.description,
         tags: options.tags,
@@ -18594,9 +19065,9 @@ export function createSemanticBuilderBlock(projectRoot, options) {
     const safeDomain = (options.domain ?? '')
         .trim()
         .toLowerCase()
-        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/[^a-z0-9._/-]+/g, '-')
         .replace(/^\/+|\/+$/g, '') || 'uncategorized';
-    const target = resolveBlockWriteTarget(projectRoot, safeDomain, slug);
+    const target = resolveBlockWriteTarget(projectRoot, safeDomain, '', slug);
     mkdirSync(dirname(target.absPath), { recursive: true });
     const blockPath = target.absPath;
     if (existsSync(blockPath)) {
@@ -18922,7 +19393,7 @@ function yamlScalar(value) {
         return value;
     return JSON.stringify(value);
 }
-function buildNotebookTemplate(title, template) {
+function buildNotebookTemplate(title, template, productContext = {}) {
     const id = () => Math.random().toString(36).slice(2, 10);
     let cells;
     if (template === "analysis") {
@@ -19035,7 +19506,18 @@ function buildNotebookTemplate(title, template) {
     else {
         cells = [];
     }
-    return JSON.stringify({ dqlnbVersion: 2, version: 1, title, cells }, null, 2);
+    return JSON.stringify({
+        dqlnbVersion: 2,
+        version: 1,
+        title,
+        metadata: {
+            createdWith: 'dql',
+            ...(productContext.ownerDomain ? { ownerDomain: productContext.ownerDomain } : {}),
+            usesDomains: productContext.usesDomains ?? (productContext.ownerDomain ? [productContext.ownerDomain] : []),
+            requiredExports: [],
+        },
+        cells,
+    }, null, 2);
 }
 /** Build a lineage graph from the project's blocks and semantic layer. */
 // Cache per project + source fingerprint. A process can serve different roots,
@@ -20081,33 +20563,8 @@ 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/runtimes/',
-    '**/.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);
+    ensureDqlGitignore(projectRoot);
 }
 async function readGitDiff(cwd, filePath, staged = false) {
     const gitRoot = await resolveGitRoot(cwd);
@@ -20458,8 +20915,11 @@ async function readGitRemote(cwd) {
     const url = await execGit(gitRoot, ['remote', 'get-url', name]);
     return { inRepo: true, url: url.code === 0 ? url.stdout.trim() : null, name };
 }
-function collectGovernedSourcePaths(root, folder, predicate) {
-    const start = join(root, folder);
+function collectGovernedSourcePaths(root, folder, predicate = () => true) {
+    // `layout.skillsPath` may point at a sibling folder in the same Git
+    // repository. Resolve both project-relative and absolute source roots so the
+    // governed inventory follows the loader instead of assuming `./skills`.
+    const start = resolve(root, folder);
     if (!existsSync(start))
         return [];
     const paths = [];
@@ -20472,13 +20932,16 @@ function collectGovernedSourcePaths(root, folder, predicate) {
             const absolute = join(dir, entry.name);
             if (entry.isDirectory())
                 walk(absolute);
-            else if (entry.isFile() && predicate(entry.name))
+            else if (entry.isFile() && predicate(entry.name, relative(root, absolute).replace(/\\/g, '/')))
                 paths.push(absolute);
         }
     };
     walk(start);
     return paths;
 }
+function uniqueGovernedSourcePaths(paths) {
+    return [...new Set(paths.map((path) => resolve(path)))].sort();
+}
 async function gitGovernedFileState(gitRoot, path) {
     const tracked = await execGit(gitRoot, ['ls-files', '--error-unmatch', '--', path]);
     const status = await execGit(gitRoot, ['status', '--porcelain=v1', '--untracked-files=all', '--', path]);
@@ -20490,13 +20953,23 @@ async function gitGovernedFileState(gitRoot, path) {
 async function readGitGovernedContext(cwd) {
     const gitRoot = await resolveGitRoot(cwd);
     const empty = () => ({ total: 0, tracked: 0, changed: 0, untracked: 0, ignored: 0, paths: [] });
-    if (!gitRoot)
-        return { inRepo: false, trackingReady: false, domains: empty(), skills: empty() };
+    if (!gitRoot) {
+        return {
+            inRepo: false,
+            trackingReady: false,
+            legacyBroadIgnore: false,
+            domains: empty(),
+            skills: empty(),
+            artifacts: empty(),
+            learning: empty(),
+        };
+    }
     const summarize = async (files) => {
         const group = empty();
-        for (const absolute of files) {
-            const path = relative(gitRoot, absolute).replace(/\\/g, '/');
-            const state = await gitGovernedFileState(gitRoot, path);
+        for (const absolute of uniqueGovernedSourcePaths(files)) {
+            const gitPath = relative(gitRoot, absolute).replace(/\\/g, '/');
+            const path = relative(cwd, absolute).replace(/\\/g, '/');
+            const state = await gitGovernedFileState(gitRoot, gitPath);
             group.total += 1;
             group[state] += 1;
             if (group.paths.length < 24)
@@ -20504,33 +20977,57 @@ async function readGitGovernedContext(cwd) {
         }
         return group;
     };
-    const [domains, skills] = await Promise.all([
-        summarize(collectGovernedSourcePaths(cwd, 'domains', (name) => name === 'domain.dql')),
+    const rootArtifacts = [
+        'blocks',
+        'terms',
+        'business-views',
+        'notebooks',
+        'workbooks',
+        'apps',
+        'dashboards',
+        'semantic-layer',
+        'tests',
+    ].flatMap((folder) => collectGovernedSourcePaths(cwd, folder));
+    const configArtifacts = ['dql.config.json', 'package.json']
+        .map((path) => join(cwd, path))
+        .filter(existsSync);
+    const [domains, skills, artifacts, learning] = await Promise.all([
+        summarize(collectGovernedSourcePaths(cwd, 'domains', (name, path) => !name.endsWith('.skill.md') && isGovernedSourceFile(path))),
         summarize([
-            ...collectGovernedSourcePaths(cwd, 'skills', (name) => name.endsWith('.skill.md')),
+            ...collectGovernedSourcePaths(cwd, skillsDir(cwd), (name) => name.endsWith('.skill.md')),
+            ...collectGovernedSourcePaths(cwd, 'domains', (name) => name.endsWith('.skill.md')),
             ...collectGovernedSourcePaths(cwd, '.dql/skills', (name) => name.endsWith('.skill.md')),
         ]),
+        summarize([...rootArtifacts.filter((path) => isGovernedSourceFile(relative(cwd, path))), ...configArtifacts]),
+        summarize([
+            ...collectGovernedSourcePaths(cwd, '.dql/hints'),
+            ...collectGovernedSourcePaths(cwd, '.dql/traces'),
+            ...collectGovernedSourcePaths(cwd, '.dql/evaluations'),
+            ...collectGovernedSourcePaths(cwd, '.dql/reviews'),
+        ]),
     ]);
-    return { inRepo: true, trackingReady: domains.ignored === 0 && skills.ignored === 0, domains, skills };
+    const gitignorePath = join(cwd, '.gitignore');
+    const legacyBroadIgnore = existsSync(gitignorePath)
+        && readFileSync(gitignorePath, 'utf-8').split(/\r?\n/).some(isLegacyBroadDqlIgnore);
+    const groups = [domains, skills, artifacts, learning];
+    return {
+        inRepo: true,
+        trackingReady: !legacyBroadIgnore && groups.every((group) => group.ignored === 0),
+        legacyBroadIgnore,
+        domains,
+        skills,
+        artifacts,
+        learning,
+    };
 }
 /** Replace only the legacy broad `.dql/` ignore with cache/runtime-specific rules. */
 async function enableGitGovernedContextTracking(cwd) {
     const gitRoot = await resolveGitRoot(cwd);
     if (!gitRoot)
         return { ok: false, error: 'Not a git repository' };
-    const ignorePath = join(cwd, '.gitignore');
-    const existing = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf-8') : '';
-    const lines = existing.split(/\r?\n/);
-    const next = lines.filter((line) => !/^\s*\/?\.dql\/\s*$/.test(line));
-    for (const rule of LOCAL_RUNTIME_GITIGNORE_RULES) {
-        if (!next.some((line) => line.trim() === rule))
-            next.push(rule);
-    }
-    const rendered = `${next.join('\n').replace(/\n+$/, '')}\n`;
-    if (rendered !== existing)
-        writeFileSync(ignorePath, rendered, 'utf-8');
+    const gitignore = ensureDqlGitignore(cwd);
     const migration = migrateLegacySkills(cwd);
-    return { ok: true, changed: rendered !== existing || migration.moved.length > 0 };
+    return { ok: true, changed: gitignore.changed || migration.moved.length > 0 };
 }
 async function gitCreateBranch(cwd, name, checkout) {
     const gitRoot = await resolveGitRoot(cwd);