@duckcodeailabs/dql-cli 1.13.0 → 1.13.2

package/dist/local-runtime.js

@@ -2,7 +2,7 @@ import { execFileSync, execSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { gzip } from "node:zlib";
 import { createServer } from "node:http";
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync, } from "node:fs";
 import { mkdir as mkdirAsync, rename as renameAsync, rm as rmAsync, writeFile as writeFileAsync, } from 'node:fs/promises';
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
@@ -15,7 +15,7 @@ import { buildMixedSourceWarehouseFallbackSql, findMentionedNotebookDataset, pla
 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 { 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, previewModelingChanges, applyModelingChange, previewDbtSourcePatch, applyDbtSourcePatch, loadDomainPackageRegistry, loadDbtNodeAuthoringDetail, normalizeAnalyticalFailureV1, relationshipValidationProofFingerprint, renderSemanticBlockSource, discoverDbtDomains, collectDbtRelationshipTests, renderDomainDeclaration, ProjectSnapshotService, analyzeSqlReferences, semanticDimensionReference, modelAreaLocalId, DEFAULT_MODEL_AREA_ID, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
@@ -24,8 +24,8 @@ 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, 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, normalizeWarehouseSqlFailure, parseProposal, 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, internalRelationIdsInSql, 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, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
-import { addSqlResultFilter, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
+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, normalizeWarehouseSqlFailure, parseProposal, 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, internalRelationIdsInSql, defaultAgentRunStorePath, defaultAgentRunSqlitePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, configuredSkillsPath, skillsDir, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, previewSkillChange, buildContextAuthoringProposal, contextAuthoringDependencyClosure, FileContextAuthoringProposalStore, 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, isTrustedConversationTurn, resolveInternalRelationIds, analyticalError, tagAnalyticalError, withAnalyticalErrorOrigin, withAnalyticalErrorOriginSync, } from '@duckcodeailabs/dql-agent';
+import { addSqlResultFilter, dashboardFilterableResultColumns, filterableResultColumns, replaceBlockStudioSql } from './sql-result-filter.js';
 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';
@@ -87,7 +87,16 @@ function hasDbtSemanticArtifacts(projectRoot, dbtProjectDir, configuredManifestP
     }
     return false;
 }
-const AGENT_RUN_REQUESTED_MODES = new Set(['auto', 'ask', 'research', 'sql', 'block', 'app']);
+// Every member of `AgentRunRequestedMode`. The `Record` (rather than a bare
+// Set literal) is deliberate: a `Set<AgentRunRequestedMode>` happily accepts a
+// subset, which is how 'modeling' and 'skill' went missing here — the parser
+// dropped them to `undefined`, `selectRoute` never saw an explicit mode, and
+// Modeling AI silently ran the governed answer loop instead of proposing a
+// model. A Record makes an omission a compile error.
+const AGENT_RUN_REQUESTED_MODE_MEMBERS = {
+    auto: true, ask: true, research: true, sql: true, block: true, app: true, modeling: true, skill: true,
+};
+const AGENT_RUN_REQUESTED_MODES = new Set(Object.keys(AGENT_RUN_REQUESTED_MODE_MEMBERS));
 /** AGT-007 / AGT-022: App-specific context adapter into the uniform AgentRun. */
 export function buildAppCopilotResearchAgentRequest(input) {
     const memoOnly = input.mode === 'memo_only';
@@ -1503,59 +1512,6 @@ export async function startLocalServer(opts) {
         });
         return { domainContext, contextPack };
     };
-    const buildAgentPromptArtifact = async (request, target, repair) => {
-        try {
-            await reindexProject(projectRoot, { kgPath: defaultKgPath(projectRoot) });
-        }
-        catch {
-            // Best-effort: buildFromPrompt can still use any existing KG/cache state.
-        }
-        const skills = loadSkills(projectRoot).skills;
-        // On a repair re-run, target the prior failure and (for blocks) revise in place.
-        const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
-        const mode = target === 'block' && (isRepair || agentRunWorkspaceValue(request, 'mode') === 'edit')
-            ? 'edit'
-            : 'create';
-        const prompt = isRepair
-            ? `${request.question}\n\nFix the previous attempt: ${repair?.repairHint}`
-            : request.question;
-        const domain = target === 'block' ? agentRunWorkspaceValue(request, 'domain') : undefined;
-        const modelAreaId = agentRunWorkspaceValue(request, 'modelAreaId');
-        const purpose = agentRunWorkspaceValue(request, 'purpose');
-        const { domainContext, contextPack } = await buildDirectBuildContext({
-            question: prompt,
-            domain,
-            purpose,
-            modelAreaId,
-            surface: target === 'cell' ? 'notebook' : 'block',
-            selectedContext: { target, mode },
-        });
-        return buildFromPrompt({
-            projectRoot,
-            prompt,
-            context: {
-                cellSql: agentRunWorkspaceValue(request, 'cellSql'),
-                selection: agentRunWorkspaceValue(request, 'selection'),
-            },
-            target,
-            mode,
-            blockPath: target === 'block'
-                ? agentRunWorkspaceValue(request, 'blockPath')
-                    ?? (request.selectedObject?.kind === 'block' && request.selectedObject.path?.endsWith('.dql')
-                        ? request.selectedObject.path
-                        : undefined)
-                : undefined,
-            owner: agentRunWorkspaceValue(request, 'owner'),
-            domain,
-            modelAreaId,
-            contextPack,
-            domainContext,
-            userId: agentRunWorkspaceValue(request, 'userId'),
-            skills,
-            dbtManifestPath: resolveDbtManifestPath(projectRoot, projectConfig),
-            executionProbe: target === 'block' ? runBlockReflectionProbe : undefined,
-        });
-    };
     const agentRunEvaluation = (id, label, passed, severity, message, evidence) => ({ id, label, passed, severity, message, evidence });
     const agentRunArtifact = (kind, title, payload, ref, trustState = 'review_required') => ({
         id: `${kind}:${Date.now()}`,
@@ -2412,7 +2368,12 @@ export async function startLocalServer(opts) {
             : isTerminalFailure
                 ? terminalFailureActions
                 : isGroundingGap
-                    ? [{ id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' }]
+                    ? governedAnswer.refusalCode === 'modeling_gap'
+                        ? [
+                            { id: 'fix-modeling-gap', label: 'Fix with Modeling AI', route: 'modeling_draft', artifactKind: 'modeling_change_proposal' },
+                            { id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' },
+                        ]
+                        : [{ id: 'research-gap', label: 'Research missing metadata coverage', route: 'research', artifactKind: 'research_run' }]
                     : [
                         { id: 'create-block', label: governedAnswer.dqlArtifact ? 'Review DQL draft' : 'Create DQL draft', route: 'dql_block_draft', artifactKind: 'dql_block_draft' },
                         { id: 'research-gap', label: 'Research deeper', route: 'research' },
@@ -2585,11 +2546,399 @@ export async function startLocalServer(opts) {
             nextActions,
         };
     };
+    const contextProposalStore = new FileContextAuthoringProposalStore(projectRoot);
+    /**
+     * UI-019: authoring must never dead-end on a Domain/Area that does not exist
+     * yet. Every modeling operation still belongs to exactly one Domain and Area
+     * (`11-context-authoring-and-ai.md`); the difference is that DQL now creates
+     * the missing scope as part of the same reviewable proposal instead of
+     * blocking the author until they create it by hand. The synthesized
+     * operations are ordinary reviewable patches, so nothing is written until the
+     * proposal is explicitly committed.
+     */
+    const ensureAuthoringScopeOperations = (operations, manifest) => {
+        const modeling = manifest.modeling;
+        if (!modeling)
+            return operations;
+        const existingDomains = new Set(Object.keys(modeling.packages ?? {}));
+        const existingAreas = new Set(Object.values(modeling.areas ?? {}).flatMap((area) => [`${area.domain}::${area.localId}`, `${area.domain}::${area.qualifiedId}`]));
+        // A scope created earlier in this same batch counts as existing.
+        for (const operation of operations) {
+            if (operation.kind !== 'modeling_change')
+                continue;
+            if (operation.change.operation === 'upsert_domain')
+                existingDomains.add(operation.change.value.id);
+            if (operation.change.operation === 'upsert_area')
+                existingAreas.add(`${operation.change.value.domain}::${operation.change.value.id}`);
+        }
+        const created = [];
+        const domainOperationId = new Map();
+        const areaOperationId = new Map();
+        const defaultAreaName = manifest.dbtProvenance?.projectName
+            ? titleCaseAuthoring(manifest.dbtProvenance.projectName)
+            : 'Core models';
+        const withScope = operations.map((operation) => {
+            if (operation.kind !== 'modeling_change')
+                return operation;
+            const change = operation.change;
+            if (change.operation !== 'upsert_entity' && change.operation !== 'upsert_relationship')
+                return operation;
+            const domain = change.value.domain;
+            if (!domain)
+                return operation;
+            const dependsOn = [...(operation.dependsOn ?? [])];
+            if (!existingDomains.has(domain)) {
+                let id = domainOperationId.get(domain);
+                if (!id) {
+                    id = `scope:domain:${domain}`;
+                    domainOperationId.set(domain, id);
+                    created.push({
+                        id,
+                        kind: 'modeling_change',
+                        evidence: ['created automatically so the requested modeling scope exists'],
+                        change: { operation: 'upsert_domain', value: { id: domain, name: titleCaseAuthoring(domain) } },
+                    });
+                }
+                if (!dependsOn.includes(id))
+                    dependsOn.push(id);
+            }
+            const areaId = change.value.areaId;
+            if (areaId && !existingAreas.has(`${domain}::${areaId}`)) {
+                const key = `${domain}::${areaId}`;
+                let id = areaOperationId.get(key);
+                if (!id) {
+                    id = `scope:area:${domain}:${areaId}`;
+                    areaOperationId.set(key, id);
+                    created.push({
+                        id,
+                        kind: 'modeling_change',
+                        dependsOn: domainOperationId.has(domain) ? [domainOperationId.get(domain)] : [],
+                        evidence: ['created automatically so the requested modeling scope exists'],
+                        change: {
+                            operation: 'upsert_area',
+                            value: {
+                                id: areaId,
+                                domain,
+                                name: areaId === DEFAULT_MODEL_AREA_ID ? defaultAreaName : titleCaseAuthoring(areaId),
+                                description: 'Subject area created automatically when modeling started. Rename or split it at any time.',
+                            },
+                        },
+                    });
+                }
+                if (!dependsOn.includes(id))
+                    dependsOn.push(id);
+            }
+            return dependsOn.length ? { ...operation, dependsOn } : operation;
+        });
+        return created.length ? [...created, ...withScope] : withScope;
+    };
+    /**
+     * REL-004: when a batch binds dbt models, bring across the relationships dbt
+     * already declares in its `relationships` tests. dbt states the exact key
+     * pair and `dbt test` enforces it, so redrawing those edges by hand is pure
+     * duplicated work.
+     *
+     * REL-001 is unchanged: a dbt test is evidence, not join authorization. Every
+     * edge produced here is `status: 'draft'` with `fanout: 'unknown'` and no
+     * validation receipt, so it can never prove an automatic join.
+     */
+    const appendDbtDeclaredRelationships = (operations, manifest) => {
+        const manifestPath = manifest.dbtProvenance?.manifestPath;
+        if (!manifestPath || !existsSync(manifestPath))
+            return operations;
+        // Entities this batch creates, plus entities already bound in the project.
+        const bound = new Map();
+        for (const entity of Object.values(manifest.modeling?.entities ?? {})) {
+            bound.set(entity.dbtUniqueId, { id: entity.localId, domain: entity.domain, areaId: modelAreaLocalId(entity.areaId) });
+        }
+        let batchBindings = 0;
+        for (const operation of operations) {
+            if (operation.kind !== 'modeling_change' || operation.change.operation !== 'upsert_entity')
+                continue;
+            const value = operation.change.value;
+            bound.set(value.dbtModel, { id: value.id, domain: value.domain, areaId: value.areaId, operationId: operation.id });
+            batchBindings += 1;
+        }
+        if (batchBindings === 0 || bound.size < 2)
+            return operations;
+        let rawManifest;
+        try {
+            rawManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            return operations;
+        }
+        const existingRelationshipIds = new Set([
+            ...Object.values(manifest.modeling?.relationships ?? {}).map((relationship) => `${relationship.ownerDomain ?? ''}::${relationship.localId}`),
+            ...operations.flatMap((operation) => operation.kind === 'modeling_change' && operation.change.operation === 'upsert_relationship'
+                ? [`${operation.change.value.domain}::${operation.change.value.id}`]
+                : []),
+        ]);
+        const harvested = [];
+        for (const edge of collectDbtRelationshipTests(rawManifest, new Set(bound.keys()))) {
+            if (edge.fromColumn === 'unknown' || edge.toColumn === 'unknown')
+                continue;
+            const from = bound.get(edge.fromDbtUniqueId);
+            const to = bound.get(edge.toDbtUniqueId);
+            if (!from || !to || from.id === to.id)
+                continue;
+            // Only offer edges this batch actually introduces, and keep cross-domain
+            // links on the explicit export/import path.
+            if (!from.operationId && !to.operationId)
+                continue;
+            if (from.domain !== to.domain)
+                continue;
+            const id = `${from.id}_to_${to.id}`;
+            const key = `${from.domain}::${id}`;
+            if (existingRelationshipIds.has(key))
+                continue;
+            existingRelationshipIds.add(key);
+            harvested.push({
+                id: `dbt-test:${edge.testUniqueId}`,
+                kind: 'modeling_change',
+                dependsOn: [from.operationId, to.operationId].filter((value) => Boolean(value)),
+                evidence: [edge.testUniqueId, ...(edge.sourcePath ? [edge.sourcePath] : [])],
+                change: {
+                    operation: 'upsert_relationship',
+                    value: {
+                        id, domain: from.domain, areaId: from.areaId ?? to.areaId,
+                        from: from.id, to: to.id,
+                        keys: [{ from: edge.fromColumn, to: edge.toColumn }],
+                        cardinality: 'many_to_one', fanout: 'unknown', status: 'draft',
+                        rationale: `Declared by the dbt relationships test ${edge.testUniqueId}. Validate against the warehouse before certifying.`,
+                    },
+                },
+            });
+        }
+        return harvested.length ? [...operations, ...harvested] : operations;
+    };
+    const previewContextAuthoring = (input) => {
+        const snapshot = projectSnapshot();
+        if (input.expectedSnapshotId && input.expectedSnapshotId !== snapshot.snapshotId) {
+            throw Object.assign(new Error('Project sources changed before the authoring proposal was previewed.'), { code: 'PROPOSAL_STALE' });
+        }
+        if (input.operations.length === 0)
+            throw Object.assign(new Error('At least one authoring operation is required.'), { code: 'INVALID_REQUEST' });
+        const diagnostics = [...(input.diagnostics ?? [])];
+        const operations = input.operations.map((operation) => {
+            if (operation.kind === 'skill_change') {
+                const value = { ...operation.value };
+                value.status = 'draft';
+                if (value.sourceRefs?.some((reference) => !contextSourceReferenceExists(snapshot.manifest, reference))) {
+                    diagnostics.push({ code: 'UNKNOWN_GOVERNED_REFERENCE', severity: 'blocking', operationId: operation.id, message: 'The Skill proposal references a model or relationship that is not present in the current snapshot.' });
+                }
+                return { ...operation, value };
+            }
+            if (operation.kind !== 'modeling_change')
+                return operation;
+            if ((input.origin === 'ai' || input.origin === 'correction') && operation.change.operation.startsWith('remove_')) {
+                diagnostics.push({ code: 'AI_DELETE_FORBIDDEN', severity: 'blocking', operationId: operation.id, message: 'Modeling AI can create or update context, but it cannot delete governed source.' });
+            }
+            if (operation.change.operation === 'upsert_relationship') {
+                const current = operation.change.value;
+                if (current.crossDomain && (input.origin === 'ai' || input.origin === 'yaml_import')) {
+                    diagnostics.push({ code: 'CROSS_DOMAIN_IMPORT_FORBIDDEN', severity: 'blocking', operationId: operation.id, message: 'Cross-domain relationships require the explicit export, contract, and import workflow.' });
+                }
+                if (input.origin === 'ai' || input.origin === 'correction' || input.origin === 'yaml_import') {
+                    return {
+                        ...operation,
+                        change: {
+                            ...operation.change,
+                            value: {
+                                ...current,
+                                status: 'draft',
+                                fanout: current.fanout === 'unsafe' ? 'forbidden' : current.fanout,
+                                certifiedAgainst: undefined,
+                                validation: undefined,
+                            },
+                        },
+                    };
+                }
+            }
+            if (operation.change.operation === 'upsert_entity'
+                && (input.origin === 'ai' || input.origin === 'yaml_import' || input.origin === 'dbt_discovery')
+                && !operation.change.value.areaId) {
+                // Every model still belongs to exactly one Domain and subject area. An
+                // omitted area is filled with the default rather than blocking the
+                // author; `ensureAuthoringScopeOperations` creates it if it is new.
+                diagnostics.push({ code: 'MODEL_AREA_DEFAULTED', severity: 'info', operationId: operation.id, message: `No subject area was selected, so these models were placed in "${DEFAULT_MODEL_AREA_ID}". You can rename or move them later.` });
+                return { ...operation, change: { ...operation.change, value: { ...operation.change.value, areaId: DEFAULT_MODEL_AREA_ID } } };
+            }
+            return operation;
+        });
+        // dbt discovery and Modeling AI bind models; give them the edges dbt already
+        // declares. Manual authoring and YAML import bring their own relationships.
+        const withDeclaredEdges = input.origin === 'dbt_discovery' || input.origin === 'ai'
+            ? appendDbtDeclaredRelationships(operations, snapshot.manifest)
+            : operations;
+        const scopedOperations = ensureAuthoringScopeOperations(withDeclaredEdges, snapshot.manifest);
+        const operationIds = new Set(scopedOperations.map((operation) => operation.id));
+        for (const operation of scopedOperations) {
+            for (const dependency of operation.dependsOn ?? []) {
+                if (!operationIds.has(dependency))
+                    diagnostics.push({ code: 'DEPENDENCY_CONFLICT', severity: 'blocking', operationId: operation.id, message: `Required proposal operation is missing: ${dependency}` });
+            }
+        }
+        const patches = [];
+        const modelingOperations = scopedOperations.filter((operation) => operation.kind === 'modeling_change');
+        if (modelingOperations.length > 0) {
+            const batch = previewModelingChanges(projectRoot, modelingOperations.map((operation) => operation.change));
+            // The batch attributes each path while composing its shadow, so a change
+            // that depends on an earlier one (an entity in a Domain this same batch
+            // creates) is attributed correctly and without re-previewing per patch.
+            const ownerByPath = new Map();
+            batch.patchPathsByChange.forEach((paths, index) => {
+                const operationId = modelingOperations[index]?.id;
+                if (!operationId)
+                    return;
+                for (const path of paths)
+                    if (!ownerByPath.has(path))
+                        ownerByPath.set(path, operationId);
+            });
+            for (const patch of batch.patches) {
+                patches.push({ ...patch, owner: 'dql', operationId: ownerByPath.get(patch.path) ?? modelingOperations[0].id });
+            }
+        }
+        for (const operation of scopedOperations) {
+            if (operation.kind === 'skill_change') {
+                const preview = previewSkillChange(projectRoot, operation.value, operation.targetQualifiedId, operation.expectedSourceHash);
+                for (const patch of preview.patches) {
+                    patches.push({
+                        path: relative(projectRoot, patch.path).replace(/\\/g, '/'),
+                        before: patch.before,
+                        after: patch.after,
+                        changed: patch.changed,
+                        owner: 'dql',
+                        operationId: operation.id,
+                    });
+                }
+            }
+            else if (operation.kind === 'dbt_source_change') {
+                const { dbtProjectDir, manifestPath } = onboardingDbtPaths({});
+                const preview = previewDbtSourcePatch(dbtProjectDir, manifestPath, operation.change);
+                patches.push({
+                    path: relative(projectRoot, resolve(dbtProjectDir, preview.patch.path)).replace(/\\/g, '/'),
+                    before: preview.patch.before,
+                    after: preview.patch.after,
+                    changed: preview.patch.changed,
+                    owner: 'dbt',
+                    operationId: operation.id,
+                });
+            }
+        }
+        const duplicatePaths = patches.map((patch) => patch.path).filter((path, index, values) => values.indexOf(path) !== index);
+        for (const path of [...new Set(duplicatePaths)])
+            diagnostics.push({ code: 'OWNERSHIP_CONFLICT', severity: 'blocking', message: `More than one proposal operation owns ${path}. Repreview after resolving the conflict.` });
+        const dependencyFingerprints = Object.fromEntries(patches.map((patch) => [
+            patch.path,
+            createHash('sha256').update(patch.before).digest('hex'),
+        ]));
+        const proposal = buildContextAuthoringProposal({
+            origin: input.origin,
+            baseSnapshotId: snapshot.snapshotId,
+            dependencyFingerprints,
+            operations: scopedOperations,
+            patches,
+            diagnostics,
+            sourceRunId: input.sourceRunId,
+            sourceArtifactId: input.sourceArtifactId,
+            revision: input.revision,
+        });
+        contextProposalStore.save(proposal);
+        return proposal;
+    };
+    const modelingAuthoringRunExecutor = async ({ runId, request }) => {
+        const snapshot = projectSnapshot();
+        // AGT-024: a configured provider designs the model; the deterministic
+        // matcher is the documented provider-unavailable fallback, and the answer
+        // says which one ran so an evidence-only suggestion is never mistaken for
+        // an AI proposal.
+        const provider = await createBlockStudioAssistProvider(projectRoot);
+        let usedProvider = Boolean(provider);
+        let operations;
+        if (provider) {
+            try {
+                operations = await buildAiModelingOperations(projectRoot, snapshot.manifest, request, provider);
+            }
+            catch (error) {
+                // Fall back only when the provider itself is unusable. A rejected
+                // proposal (invented identifiers, nothing to propose) is a real result
+                // and must surface, not be papered over by the template matcher.
+                if (!/could not complete this modeling request/.test(error instanceof Error ? error.message : String(error)))
+                    throw error;
+                usedProvider = false;
+                operations = buildDeterministicModelingOperations(projectRoot, snapshot.manifest, request);
+            }
+        }
+        else {
+            operations = buildDeterministicModelingOperations(projectRoot, snapshot.manifest, request);
+        }
+        const proposal = previewContextAuthoring({
+            origin: request.workspaceContext?.correction === true ? 'correction' : 'ai',
+            operations,
+            // Base the draft on the snapshot it was just built from, not on the id the
+            // client captured at page load. Gating construction on the client's id
+            // rejected a proposal assembled from `snapshot.manifest` moments earlier,
+            // so any unrelated project write (a block edit, a dbt reapply) made every
+            // Modeling AI request fail with PROPOSAL_STALE until a manual refresh.
+            // Drift is still caught where it matters: applying the proposal re-checks
+            // its `baseSnapshotId` and `dependencyFingerprints` and fails SOURCE_CHANGED.
+            expectedSnapshotId: snapshot.snapshotId,
+            sourceRunId: runId,
+            revision: Number(request.workspaceContext?.revision ?? 1),
+        });
+        const blocked = proposal.diagnostics.some((item) => item.severity === 'blocking');
+        return {
+            summary: `Prepared ${proposal.impact.modelingChanges} modeling change${proposal.impact.modelingChanges === 1 ? '' : 's'} for review.`,
+            answer: blocked
+                ? 'I prepared a modeling proposal, but the blocking items must be resolved before it can be saved.'
+                : usedProvider
+                    ? 'I designed a modeling proposal from your dbt metadata. Every model and column was checked against the current snapshot. Review the exact source diff before saving it as a draft.'
+                    : 'No AI provider is configured, so these are evidence-only suggestions matched from dbt metadata rather than an AI proposal. Review the exact source diff before saving it as a draft.',
+            status: 'needs_review',
+            trustState: 'review_required',
+            stopReason: 'human_review_required',
+            artifacts: [{ id: `${runId}:modeling-proposal`, kind: 'modeling_change_proposal', title: usedProvider ? 'Modeling change proposal' : 'Evidence-only modeling suggestions', trustState: 'review_required', ref: proposal.id, payload: proposal }],
+            evaluations: proposal.diagnostics.map((diagnostic) => ({ id: `${proposal.id}:${diagnostic.code}`, label: diagnostic.code, passed: diagnostic.severity !== 'blocking', severity: diagnostic.severity, message: diagnostic.message })),
+            nextActions: [{ id: 'review-modeling-proposal', label: 'Review in Modeling', artifactKind: 'modeling_change_proposal' }],
+        };
+    };
+    const skillAuthoringRunExecutor = async ({ runId, request }) => {
+        const snapshot = projectSnapshot();
+        // SKILL-006: same contract as Modeling AI — a provider drafts the skill
+        // body and vocabulary; the template is the labelled fallback.
+        const provider = await createBlockStudioAssistProvider(projectRoot);
+        const operations = provider
+            ? await buildAiSkillOperations(projectRoot, snapshot.manifest, request, provider)
+                .catch(() => buildMetadataBoundSkillOperations(projectRoot, snapshot.manifest, request))
+            : buildMetadataBoundSkillOperations(projectRoot, snapshot.manifest, request);
+        const proposal = previewContextAuthoring({
+            origin: request.workspaceContext?.correction === true ? 'correction' : 'ai',
+            operations,
+            // Same reasoning as the modeling executor above: base the draft on the
+            // snapshot it was built from; apply-time re-validation catches real drift.
+            expectedSnapshotId: snapshot.snapshotId,
+            sourceRunId: runId,
+            revision: Number(request.workspaceContext?.revision ?? 1),
+        });
+        return {
+            summary: `Prepared ${proposal.impact.skillChanges} metadata-bound Skill change${proposal.impact.skillChanges === 1 ? '' : 's'} for review.`,
+            answer: 'I prepared a scope-qualified Skill draft. It will not guide an agent unless you save it and later activate it explicitly.',
+            status: 'needs_review',
+            trustState: 'review_required',
+            stopReason: 'human_review_required',
+            artifacts: [{ id: `${runId}:skill-proposal`, kind: 'skill_change_proposal', title: 'Skill change proposal', trustState: 'review_required', ref: proposal.id, payload: proposal }],
+            evaluations: proposal.diagnostics.map((diagnostic) => ({ id: `${proposal.id}:${diagnostic.code}`, label: diagnostic.code, passed: diagnostic.severity !== 'blocking', severity: diagnostic.severity, message: diagnostic.message })),
+            nextActions: [{ id: 'review-skill-proposal', label: 'Review Skill draft', artifactKind: 'skill_change_proposal' }],
+        };
+    };
     const agentRunExecutors = {
         conversation: conversationRunExecutor,
         certified_answer: answerRunExecutor,
         semantic_answer: answerRunExecutor,
         generated_answer: answerRunExecutor,
+        modeling_draft: modelingAuthoringRunExecutor,
+        skill_draft: skillAuthoringRunExecutor,
         research: async (researchContext) => {
             const { runId, request, routeDecision, emit } = researchContext;
             const metrics = loadSemanticMetrics(projectRoot);
@@ -4004,6 +4353,48 @@ export async function startLocalServer(opts) {
             return [];
         }
     };
+    /**
+     * CTX-008: the project's authored relationships, as plain join facts for the
+     * relations a bounded repair can actually see.
+     *
+     * A repair prompt previously carried only the failure, the failed SQL, and a
+     * bare relation list, so a repair could silently replace a correct governed
+     * join with a shared-column guess. This is grounding only — it never widens
+     * the relation scope and never authorizes a join (`REL-002` still governs
+     * execution); trust is labelled so a draft edge reads as a draft.
+     */
+    const governedJoinFactsForRelations = (relations) => {
+        const modeling = (() => {
+            try {
+                return projectSnapshot().manifest.modeling;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (!modeling)
+            return [];
+        const manifest = projectSnapshot().manifest;
+        const normalize = (value) => value.toLowerCase().replace(/"/g, '').split('.').at(-1) ?? value.toLowerCase();
+        const visible = new Set(relations.map(normalize));
+        const relationFor = (entityKey) => {
+            const entity = modeling.entities[entityKey];
+            if (!entity)
+                return undefined;
+            const node = manifest.dbtProvenance?.nodes[entity.dbtUniqueId];
+            return node?.relation ?? node?.name;
+        };
+        return Object.values(modeling.relationships).flatMap((relationship) => {
+            const from = relationFor(relationship.from);
+            const to = relationFor(relationship.to);
+            if (!from || !to || !visible.has(normalize(from)) || !visible.has(normalize(to)))
+                return [];
+            const keys = relationship.keys.map((key) => `${from}.${key.from} = ${to}.${key.to}`).join(' AND ');
+            const trust = relationship.automaticJoinAllowed ? 'certified' : `${relationship.status} (review required)`;
+            const meaning = [relationship.verb, relationship.description].filter(Boolean).join(' — ');
+            return [`${keys} (${relationship.cardinality}, fanout ${relationship.fanout}, ${trust}${meaning ? `; ${meaning}` : ''})`];
+        }).slice(0, 12);
+    };
     const boundedRepairError = (message, status, warehouseFailure) => Object.assign(new Error(message), { status, ...(warehouseFailure ? { warehouseFailure } : {}) });
     /**
      * Shared one-attempt SQL repair for Ask and Notebook. It never creates a
@@ -4040,6 +4431,9 @@ export async function startLocalServer(opts) {
                 relation: table.relation,
                 columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
             }));
+            // CTX-008: a repair that re-derives joins from column names can undo a
+            // join the original query got right. Give it the authored key pairs.
+            const governedJoins = governedJoinFactsForRelations(schemaContext.slice(0, 16).map((table) => table.relation));
             let raw;
             try {
                 raw = await provider.generate([
@@ -4053,6 +4447,7 @@ export async function startLocalServer(opts) {
                                 ? 'Preserve every positional parameter placeholder exactly; do not add, remove, or renumber placeholders.'
                                 : '',
                             'Use only relations and columns present in the supplied schema context.',
+                            'When governedJoins is present, join on those exact key pairs rather than inferring a join from column names.',
                             'Never emit internal DQL relation identities such as source::, model::, seed::, or snapshot::.',
                             'Do not add writes, DDL, multiple statements, or commentary outside the JSON fence.',
                         ].join(' '),
@@ -4069,6 +4464,7 @@ export async function startLocalServer(opts) {
                                 placeholder: `$${parameter.position}`,
                             })),
                             schema: boundedSchema,
+                            ...(governedJoins.length ? { governedJoins } : {}),
                         }),
                     },
                 ], { maxTokens: 1200, temperature: 0 });
@@ -4122,7 +4518,7 @@ export async function startLocalServer(opts) {
     const executeBoundedDqlRepair = async (input) => {
         const provider = await createBlockStudioAssistProvider(projectRoot);
         if (!provider) {
-            throw boundedRepairError('Configure an available AI provider in Settings to repair this DQL cell.', 409);
+            throw boundedRepairError('Configure an available AI provider in Settings to repair this DQL draft.', 409);
         }
         let schemaContext;
         try {
@@ -4138,6 +4534,8 @@ export async function startLocalServer(opts) {
             relation: table.relation,
             columns: table.columns.slice(0, 40).map((column) => ({ name: column.name, type: column.type })),
         }));
+        // CTX-008: same as the SQL repair — keep authored joins out of the guesser.
+        const governedJoins = governedJoinFactsForRelations(schemaContext.slice(0, 16).map((table) => table.relation));
         let raw;
         try {
             raw = await provider.generate([
@@ -4150,6 +4548,7 @@ export async function startLocalServer(opts) {
                         'Preserve the block name, business fields, visualization, tests, requested grain, filters, output columns, and aggregation semantics.',
                         'Preserve every declared parameter and every ${parameter} interpolation exactly. Do not add or remove parameters.',
                         'Use only relations and columns present in the supplied schema context.',
+                        'When governedJoins is present, join on those exact key pairs rather than inferring a join from column names.',
                         'Never emit internal relation identities such as source::, model::, seed::, or snapshot::.',
                         'Return exactly one custom block. Never certify it, bind a saved block, add writes, DDL, or multiple SQL statements.',
                     ].join(' '),
@@ -4163,6 +4562,7 @@ export async function startLocalServer(opts) {
                         dql: input.source.slice(0, 40_000),
                         parameters: input.parameters ?? {},
                         schema: boundedSchema,
+                        ...(governedJoins.length ? { governedJoins } : {}),
                     }),
                 },
             ], { maxTokens: 2400, temperature: 0 });
@@ -4185,7 +4585,7 @@ export async function startLocalServer(opts) {
             throw boundedRepairError('The AI repair did not return a complete DQL block.', 422);
         }
         if (repairedSource.length > 50_000) {
-            throw boundedRepairError('The repaired DQL exceeded the safe editable-cell size limit.', 422);
+            throw boundedRepairError('The repaired DQL exceeded the safe editable-draft size limit.', 422);
         }
         if (/^\s*@block\(/i.test(repairedSource) || /\btype\s*=\s*"semantic"/i.test(repairedSource)) {
             throw boundedRepairError('The repair changed this editable custom block into a governed reference or semantic block.', 422);
@@ -5133,6 +5533,33 @@ export async function startLocalServer(opts) {
             }
             catch { /* dir not watchable */ }
         }
+        // A dbt repository commonly keeps its shared Skills folder beside the DQL
+        // project (`../skills`). It is Git-owned context too, so watch the resolved
+        // configured root even when it is not the default projectRoot/skills path.
+        const configuredSkillsRoot = skillsDir(projectRoot);
+        const defaultSkillsRoot = join(projectRoot, 'skills');
+        if (existsSync(configuredSkillsRoot) && resolve(configuredSkillsRoot) !== resolve(defaultSkillsRoot)) {
+            try {
+                const watcher = watch(configuredSkillsRoot, { persistent: false, recursive: true }, (eventType, filename) => {
+                    if (runtimeClosing || !filename)
+                        return;
+                    const path = relative(projectRoot, join(configuredSkillsRoot, String(filename))).replace(/\\/g, '/');
+                    invalidateAgentProjectState(projectRoot);
+                    scheduleProjectRefresh(`skills:${path}`);
+                    const payload = JSON.stringify({ type: eventType === 'rename' ? 'file-added' : 'file-changed', path });
+                    for (const client of sseClients) {
+                        try {
+                            client.write(`event: change\ndata: ${payload}\n\n`);
+                        }
+                        catch {
+                            sseClients.delete(client);
+                        }
+                    }
+                });
+                projectWatchers.push(watcher);
+            }
+            catch { /* configured Skills folder is not watchable */ }
+        }
         const configuredDbtManifest = resolveDbtManifestPath(projectRoot, projectConfig);
         if (configuredDbtManifest && existsSync(dirname(configuredDbtManifest))) {
             try {
@@ -6385,6 +6812,227 @@ export async function startLocalServer(opts) {
                 }));
                 return;
             }
+            if (req.method === 'POST' && path === '/api/modeling/dbt-first/imports') {
+                const requestId = apiRequestId('modeling-import');
+                try {
+                    const body = await readJSON(req);
+                    const source = body.source && typeof body.source === 'object' ? body.source : body;
+                    const session = createModelingImportSession(projectRoot, gitRoot, loopback, source);
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, session: publicModelingImportSession(session) }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'MODELING_IMPORT_INVALID');
+                    res.writeHead(code === 'PATH_ACCESS_FORBIDDEN' ? 403 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Choose DQL or dbt YAML from the current Git workspace, or paste/upload the YAML.'] })));
+                }
+                return;
+            }
+            const modelingImportMatch = path.match(/^\/api\/modeling\/dbt-first\/imports\/([^/]+)$/);
+            if (req.method === 'GET' && modelingImportMatch) {
+                const session = readModelingImportSession(projectRoot, decodeURIComponent(modelingImportMatch[1]));
+                if (!session) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Modeling import session not found.', code: 'MODELING_IMPORT_NOT_FOUND' }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ session: publicModelingImportSession(session) }));
+                return;
+            }
+            const modelingImportPreviewMatch = path.match(/^\/api\/modeling\/dbt-first\/imports\/([^/]+)\/preview$/);
+            if (req.method === 'POST' && modelingImportPreviewMatch) {
+                const requestId = apiRequestId('modeling-import-preview');
+                try {
+                    const session = readModelingImportSession(projectRoot, decodeURIComponent(modelingImportPreviewMatch[1]));
+                    if (!session)
+                        throw Object.assign(new Error('Modeling import session not found.'), { code: 'MODELING_IMPORT_NOT_FOUND' });
+                    const body = await readJSON(req);
+                    const snapshot = projectSnapshot();
+                    const selectedCandidateIds = Array.isArray(body.selectedCandidateIds)
+                        ? body.selectedCandidateIds.filter((value) => typeof value === 'string')
+                        : session.candidates.filter((candidate) => candidate.dialect !== 'unsupported' && candidate.action !== 'open_existing').map((candidate) => candidate.id);
+                    // An unspecified scope is defaulted, not rejected: the proposal carries
+                    // the `upsert_domain`/`upsert_area` patches so the author reviews the
+                    // scope alongside the models it will hold.
+                    const domain = typeof body.domain === 'string' && body.domain.trim()
+                        ? body.domain.trim()
+                        : defaultAuthoringDomainId(snapshot.manifest);
+                    const areaId = typeof body.areaId === 'string' && body.areaId.trim() ? body.areaId.trim() : DEFAULT_MODEL_AREA_ID;
+                    const planned = modelingImportOperations(session, selectedCandidateIds, domain, areaId, snapshot.manifest);
+                    const proposal = previewContextAuthoring({
+                        origin: 'yaml_import',
+                        operations: planned.operations,
+                        expectedSnapshotId: typeof body.expectedSnapshotId === 'string' ? body.expectedSnapshotId : snapshot.snapshotId,
+                        diagnostics: planned.diagnostics,
+                    });
+                    const updated = { ...session, proposalId: proposal.id, updatedAt: new Date().toISOString() };
+                    writeModelingImportSession(projectRoot, updated);
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, session: publicModelingImportSession(updated), proposal }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'MODELING_IMPORT_PREVIEW_FAILED');
+                    res.writeHead(code === 'MODELING_IMPORT_NOT_FOUND' ? 404 : code === 'PROPOSAL_STALE' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Resolve unmatched models or choose another Domain and Area, then preview again.'] })));
+                }
+                return;
+            }
+            if (req.method === 'POST' && path === '/api/context-proposals') {
+                const requestId = apiRequestId('context-proposal');
+                try {
+                    const body = await readJSON(req);
+                    const origin = parseContextAuthoringOrigin(body.origin);
+                    const operations = parseContextAuthoringOperations(body.operations);
+                    const proposal = previewContextAuthoring({
+                        origin,
+                        operations,
+                        expectedSnapshotId: typeof body.expectedSnapshotId === 'string' ? body.expectedSnapshotId : undefined,
+                        sourceRunId: typeof body.sourceRunId === 'string' ? body.sourceRunId : undefined,
+                        sourceArtifactId: typeof body.sourceArtifactId === 'string' ? body.sourceArtifactId : undefined,
+                        revision: typeof body.revision === 'number' ? body.revision : undefined,
+                    });
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, proposal }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'PROPOSAL_INVALID');
+                    res.writeHead(code === 'PROPOSAL_STALE' ? 409 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Refresh Modeling and preview the proposal again.'] })));
+                }
+                return;
+            }
+            const contextProposalMatch = path.match(/^\/api\/context-proposals\/([^/]+)$/);
+            if (req.method === 'GET' && contextProposalMatch) {
+                const id = decodeURIComponent(contextProposalMatch[1]);
+                const proposal = contextProposalStore.get(id);
+                if (!proposal) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Context proposal not found.', code: 'PROPOSAL_NOT_FOUND' }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ proposal }));
+                return;
+            }
+            const contextRepreviewMatch = path.match(/^\/api\/context-proposals\/([^/]+)\/repreview$/);
+            if (req.method === 'POST' && contextRepreviewMatch) {
+                const requestId = apiRequestId('context-repreview');
+                try {
+                    const current = contextProposalStore.get(decodeURIComponent(contextRepreviewMatch[1]));
+                    if (!current)
+                        throw Object.assign(new Error('Context proposal not found.'), { code: 'PROPOSAL_NOT_FOUND' });
+                    const body = await readJSON(req);
+                    const selected = Array.isArray(body.selectedOperationIds)
+                        ? body.selectedOperationIds.filter((value) => typeof value === 'string')
+                        : current.operations.map((operation) => operation.id);
+                    const operations = contextAuthoringDependencyClosure(current.operations, selected);
+                    const proposal = previewContextAuthoring({
+                        origin: current.origin,
+                        operations,
+                        expectedSnapshotId: body.rebase === true ? projectSnapshot().snapshotId : current.baseSnapshotId,
+                        sourceRunId: current.sourceRunId,
+                        sourceArtifactId: current.sourceArtifactId,
+                        revision: (current.revision ?? 1) + 1,
+                    });
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ requestId, proposal }));
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, 'PROPOSAL_INVALID');
+                    res.writeHead(code === 'PROPOSAL_STALE' ? 409 : code === 'PROPOSAL_NOT_FOUND' ? 404 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Refresh the proposal against the latest project snapshot.'] })));
+                }
+                return;
+            }
+            const contextCommitMatch = path.match(/^\/api\/context-proposals\/([^/]+)\/commit$/);
+            if (req.method === 'POST' && contextCommitMatch) {
+                const requestId = apiRequestId('context-commit');
+                const proposalId = decodeURIComponent(contextCommitMatch[1]);
+                try {
+                    const proposal = contextProposalStore.get(proposalId);
+                    if (!proposal)
+                        throw Object.assign(new Error('Context proposal not found.'), { code: 'PROPOSAL_NOT_FOUND' });
+                    const body = await readJSON(req);
+                    const unexpected = Object.keys(body).filter((key) => key !== 'expectedProposalHash' && key !== 'idempotencyKey');
+                    if (unexpected.length)
+                        throw Object.assign(new Error('Commit accepts only expectedProposalHash and idempotencyKey.'), { code: 'INVALID_REQUEST' });
+                    const expectedProposalHash = typeof body.expectedProposalHash === 'string' ? body.expectedProposalHash : '';
+                    const idempotencyKey = typeof body.idempotencyKey === 'string' ? body.idempotencyKey.trim() : '';
+                    if (!expectedProposalHash || !idempotencyKey)
+                        throw Object.assign(new Error('The reviewed proposal hash and idempotency key are required.'), { code: 'INVALID_REQUEST' });
+                    const receipt = contextProposalStore.getCommitReceipt(idempotencyKey);
+                    if (receipt) {
+                        if (receipt.proposalId !== proposal.id || receipt.proposalHash !== expectedProposalHash)
+                            throw Object.assign(new Error('The idempotency key belongs to another reviewed proposal request.'), { code: 'IDEMPOTENCY_CONFLICT' });
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ requestId, proposal: contextProposalStore.get(proposal.id), snapshotId: receipt.snapshotId, idempotent: true }));
+                        return;
+                    }
+                    if (proposal.status !== 'proposed')
+                        throw Object.assign(new Error('Only a proposed change can be committed.'), { code: 'PROPOSAL_STALE' });
+                    if (proposal.proposalHash !== expectedProposalHash)
+                        throw Object.assign(new Error('The proposal changed after review.'), { code: 'PROPOSAL_STALE' });
+                    if (proposal.diagnostics.some((diagnostic) => diagnostic.severity === 'blocking'))
+                        throw Object.assign(new Error('Resolve all blocking proposal diagnostics before saving.'), { code: 'PROPOSAL_BLOCKED' });
+                    const beforeSnapshot = projectSnapshot();
+                    if (beforeSnapshot.snapshotId !== proposal.baseSnapshotId)
+                        throw Object.assign(new Error('Project sources changed after this proposal was reviewed.'), { code: 'PROPOSAL_STALE' });
+                    const resolvedPatches = proposal.patches.map((patch) => ({ patch, absolute: resolveContextPatchPath(projectRoot, gitRoot, patch.path) }));
+                    for (const { patch, absolute } of resolvedPatches) {
+                        const current = existsSync(absolute) ? readFileSync(absolute, 'utf8') : '';
+                        if (current !== patch.before)
+                            throw Object.assign(new Error(`Source changed after preview: ${patch.path}`), { code: 'SOURCE_CHANGED' });
+                    }
+                    const written = [];
+                    try {
+                        for (const item of resolvedPatches) {
+                            if (!item.patch.changed)
+                                continue;
+                            if (!item.patch.after)
+                                rmSync(item.absolute, { force: true });
+                            else {
+                                mkdirSync(dirname(item.absolute), { recursive: true });
+                                writeFileSync(item.absolute, item.patch.after, 'utf8');
+                            }
+                            written.push(item);
+                        }
+                        projectSnapshots.invalidate();
+                        invalidateAgentProjectState(projectRoot);
+                        const nextSnapshot = projectSnapshot();
+                        if (nextSnapshot.error)
+                            throw Object.assign(new Error(nextSnapshot.error), { code: 'COMPILE_FAILED' });
+                        await refreshUnifiedProjectIndexes(projectRoot);
+                        const committed = { ...proposal, status: 'committed', committedAt: new Date().toISOString(), committedSnapshotId: nextSnapshot.snapshotId };
+                        contextProposalStore.save(committed);
+                        contextProposalStore.saveCommitReceipt(idempotencyKey, { proposalId: proposal.id, proposalHash: proposal.proposalHash, snapshotId: nextSnapshot.snapshotId });
+                        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({ requestId, proposal: committed, snapshotId: nextSnapshot.snapshotId, modeling: nextSnapshot.manifest.modeling }));
+                    }
+                    catch (error) {
+                        for (const { patch, absolute } of written.reverse()) {
+                            if (!patch.before)
+                                rmSync(absolute, { force: true });
+                            else {
+                                mkdirSync(dirname(absolute), { recursive: true });
+                                writeFileSync(absolute, patch.before, 'utf8');
+                            }
+                        }
+                        projectSnapshots.invalidate();
+                        invalidateAgentProjectState(projectRoot);
+                        contextProposalStore.save(proposal);
+                        contextProposalStore.deleteCommitReceipt(idempotencyKey);
+                        throw error;
+                    }
+                }
+                catch (error) {
+                    const code = apiErrorCode(error, /changed after/i.test(apiErrorMessage(error)) ? 'SOURCE_CHANGED' : 'PROPOSAL_COMMIT_FAILED');
+                    const status = code === 'PROPOSAL_NOT_FOUND' ? 404 : ['PROPOSAL_STALE', 'SOURCE_CHANGED', 'IDEMPOTENCY_CONFLICT', 'OWNERSHIP_CONFLICT', 'DEPENDENCY_CONFLICT'].includes(code) ? 409 : code === 'PROPOSAL_BLOCKED' ? 422 : 400;
+                    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON(apiErrorEnvelope({ requestId, code, message: apiErrorMessage(error), nextActions: ['Rebase or repreview the proposal before saving.'] })));
+                }
+                return;
+            }
             if (req.method === 'POST' && path === '/api/modeling/dbt-first/dbt-source/preview') {
                 const requestId = apiRequestId('modeling-dbt-source-preview');
                 const snapshot = projectSnapshot();
@@ -7419,14 +8067,22 @@ export async function startLocalServer(opts) {
                     const metrics = semanticLayer
                         ? semanticLayer.listMetrics(undefined, { includeMeasures: false }).map((m) => m.name).filter(matches).sort().slice(0, limit)
                         : [];
-                    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+                    const manifest = buildManifest({
+                        projectRoot,
+                        dqlVersion: 'notebook',
+                        dbtManifestPath: resolveDbtManifestPath(projectRoot) ?? undefined,
+                    });
                     const blocks = Object.values(manifest.blocks)
                         .filter((b) => b.status === 'certified')
                         .map((b) => b.name)
                         .filter(matches)
                         .sort();
+                    const modelingRefs = [
+                        ...Object.values(manifest.modeling?.entities ?? {}).map((entity) => entity.qualifiedId),
+                        ...Object.values(manifest.modeling?.relationships ?? {}).map((relationship) => relationship.qualifiedId),
+                    ].filter(matches).sort();
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                    res.end(serializeJSON({ metrics, blocks: blocks.slice(0, limit) }));
+                    res.end(serializeJSON({ metrics, blocks: blocks.slice(0, limit), modelingRefs: modelingRefs.slice(0, limit) }));
                 }
                 catch (error) {
                     res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -7444,6 +8100,9 @@ export async function startLocalServer(opts) {
                         return;
                     }
                     const skill = writeSkill(projectRoot, input);
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    await refreshUnifiedProjectIndexes(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ skill: serializeSkill(skill) }));
                 }
@@ -7463,7 +8122,10 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Provide { skill } with scope and body.' }));
                         return;
                     }
-                    const skill = writeSkill(projectRoot, input);
+                    const skill = writeSkill(projectRoot, { ...input, qualifiedId: id });
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    await refreshUnifiedProjectIndexes(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ skill: serializeSkill(skill) }));
                 }
@@ -7477,6 +8139,9 @@ export async function startLocalServer(opts) {
                 try {
                     const id = decodeURIComponent(path.slice('/api/skills/'.length));
                     deleteSkill(projectRoot, id);
+                    projectSnapshots.invalidate();
+                    invalidateAgentProjectState(projectRoot);
+                    await refreshUnifiedProjectIndexes(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ ok: true }));
                 }
@@ -8577,20 +9242,23 @@ export async function startLocalServer(opts) {
                 }));
                 return;
             }
-            const appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
+            const appDashRun = path.match(/^\/api\/(apps|app-builds)\/([^/]+)\/dashboards\/([^/]+)\/run$/);
             if (req.method === 'POST' && appDashRun) {
                 try {
-                    const appId = decodeURIComponent(appDashRun[1]);
-                    const dashboardId = decodeURIComponent(appDashRun[2]);
+                    const runSurface = appDashRun[1];
+                    const appId = decodeURIComponent(appDashRun[2]);
+                    const dashboardId = decodeURIComponent(appDashRun[3]);
                     const body = await readJSON(req).catch(() => ({}));
-                    const loaded = loadAppDashboard(projectRoot, appId, dashboardId);
+                    const loaded = runSurface === 'app-builds'
+                        ? loadAppBuildDraftDashboard(projectRoot, appId, dashboardId)
+                        : loadAppDashboard(projectRoot, appId, dashboardId);
                     if (!loaded) {
                         res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
-                        res.end(serializeJSON({ error: `Dashboard "${dashboardId}" not found in app "${appId}"` }));
+                        res.end(serializeJSON({ error: `Dashboard "${dashboardId}" not found in ${runSurface === 'app-builds' ? 'local App draft' : 'App'} "${appId}"` }));
                         return;
                     }
                     const activeApp = activePersonaAppId();
-                    if (activeApp && activeApp !== appId) {
+                    if (runSurface === 'apps' && activeApp && activeApp !== appId) {
                         res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
                         res.end(serializeJSON({ error: `The active persona belongs to App "${activeApp}", not "${appId}".` }));
                         return;
@@ -8721,8 +9389,14 @@ export async function startLocalServer(opts) {
                             let draftTargetConnection;
                             let draftRepairPlan;
                             try {
-                                const draftPath = join(loaded.appDir, item.draftAnalysis.ref);
-                                draftAppRelativePath = relative(loaded.appDir, draftPath);
+                                const localDraftPath = loaded.draftArtifactsDir
+                                    ? join(loaded.draftArtifactsDir, item.draftAnalysis.ref)
+                                    : undefined;
+                                const draftRoot = localDraftPath && existsSync(localDraftPath)
+                                    ? loaded.draftArtifactsDir
+                                    : loaded.appDir;
+                                const draftPath = join(draftRoot, item.draftAnalysis.ref);
+                                draftAppRelativePath = relative(draftRoot, draftPath);
                                 if (draftAppRelativePath.startsWith('..') || draftAppRelativePath.startsWith('/')) {
                                     throw new Error('App-scoped analysis reference escapes the App directory.');
                                 }
@@ -8897,9 +9571,7 @@ export async function startLocalServer(opts) {
                                     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, 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)] }));
+                                const activeFilters = dashboardSemanticFiltersForTile(loaded.dashboard, item, dashboardVariables);
                                 const staticFilters = (item.semantic.filters ?? []).map((filter) => ({
                                     dimension: filter.field,
                                     operator: filter.operator,
@@ -9085,6 +9757,8 @@ export async function startLocalServer(opts) {
                                 variables: { ...(blockPlan?.variables ?? {}), ...dashboardVariables },
                                 block,
                                 dashboard: loaded.dashboard,
+                                tileId: item.i,
+                                tileFilterBindings: item.filterBindings,
                             });
                             const prepared = prepareLocalExecution(blockFilterApplication.sql, blockTargetConnection, projectRoot, projectConfig);
                             const result = await executor.executeQuery(prepared.sql, blockFilterApplication.sqlParams, runtimeVariables({ ...blockFilterApplication.variables, ...blockInvocation.values }), prepared.connection);
@@ -9225,6 +9899,36 @@ export async function startLocalServer(opts) {
                         }
                     }
                     localApps?.close();
+                    // Which of each tile's result columns a viewer may safely filter on.
+                    // Decided here, from a real dialect parse of the SQL that actually ran,
+                    // for the same reason Ask does it server-side: an aggregate output needs
+                    // HAVING, and picking such a column off the table would quietly change
+                    // the measure. The browser must never re-derive this.
+                    const runDialect = (() => {
+                        try {
+                            return requireActiveConnection().driver || 'duckdb';
+                        }
+                        catch {
+                            return 'duckdb';
+                        }
+                    })();
+                    const tilesWithFilters = tiles.map((tile) => {
+                        const executedSql = tile.artifact?.sql;
+                        const columns = tile.result?.columns ?? [];
+                        if (typeof executedSql !== 'string' || columns.length === 0)
+                            return tile;
+                        try {
+                            const dashboardItem = loaded.dashboard.layout.items.find((item) => item.i === tile.tileId);
+                            const block = dashboardItem ? resolveDashboardItemBlock(dashboardItem, manifest) : null;
+                            const declaredDimensions = block?.status === 'certified' ? block.dimensions ?? [] : [];
+                            const filterable = dashboardFilterableResultColumns(executedSql, columns, declaredDimensions, runDialect);
+                            return filterable.length > 0 ? { ...tile, filterableColumns: filterable } : tile;
+                        }
+                        catch {
+                            return tile; // Unparseable SQL simply offers no filter candidates.
+                        }
+                    });
+                    const filterOptions = collectDashboardFilterOptions(loaded.dashboard, tilesWithFilters);
                     const snapshot = projectSnapshot();
                     const filterFingerprint = createHash('sha256').update(JSON.stringify(dashboardVariables)).digest('hex');
                     const resultFingerprint = createHash('sha256').update(JSON.stringify(tiles.map((tile) => ({ tileId: tile.tileId, status: tile.status, result: tile.result })))).digest('hex');
@@ -9275,7 +9979,8 @@ export async function startLocalServer(opts) {
                         filterFingerprint,
                         resultFingerprint,
                         personaFingerprint,
-                        tiles,
+                        filterOptions,
+                        tiles: tilesWithFilters,
                         facts: storyResult.facts,
                         story: storyResult.story,
                     }));
@@ -9287,7 +9992,11 @@ export async function startLocalServer(opts) {
                 return;
             }
             // Apps, dashboards, persona — see apps-api.ts. Returns true if handled.
-            if (path.startsWith('/api/apps') || path.startsWith('/api/visualizations') || path === '/api/persona') {
+            if (path.startsWith('/api/apps')
+                || path.startsWith('/api/app-builds')
+                || path.startsWith('/api/app-recoveries')
+                || path.startsWith('/api/visualizations')
+                || path === '/api/persona') {
                 try {
                     const handled = await handleAppsApi({
                         req,
@@ -9333,6 +10042,18 @@ export async function startLocalServer(opts) {
                             }
                             return { ok: true, snapshotId: evidence.snapshotId, resultFingerprint: evidence.resultFingerprint };
                         },
+                        verifyAppBuildPreview: ({ runId, draftId, dashboardId, tileIds }) => {
+                            const evidence = dashboardRunEvidence.get(runId);
+                            if (!evidence || evidence.expiresAt < Date.now())
+                                return { ok: false, error: 'The App preview receipt expired. Run the local draft again.' };
+                            if (evidence.appId !== draftId || evidence.dashboardId !== dashboardId)
+                                return { ok: false, error: 'The App preview receipt does not match this local draft page.' };
+                            const successful = new Set(evidence.successfulTileIds);
+                            const failed = tileIds.filter((tileId) => !successful.has(tileId));
+                            if (failed.length > 0)
+                                return { ok: false, error: `These App components did not complete successfully: ${failed.join(', ')}` };
+                            return { ok: true, snapshotId: evidence.snapshotId, resultFingerprint: evidence.resultFingerprint };
+                        },
                         // Story narration for commit — LLM-backed with deterministic fallback.
                         narrate: narrateForAgentRun,
                     });
@@ -11906,6 +12627,20 @@ export async function startLocalServer(opts) {
                         res.end(serializeJSON({ error: 'Block name is required.' }));
                         return;
                     }
+                    const validation = validateBlockStudioSource(source, semanticLayer);
+                    if (!blockStudioValidationAllowsDraftSave(validation)) {
+                        const errors = validation.diagnostics.filter((diagnostic) => diagnostic.severity === 'error'
+                            && !BLOCK_STUDIO_DRAFT_RUNTIME_DIAGNOSTICS.has(diagnostic.code ?? ''));
+                        res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                        res.end(serializeJSON({
+                            error: errors[0]?.message ?? 'Fix the block errors before saving.',
+                            code: 'BLOCK_VALIDATION_FAILED',
+                            recoverable: true,
+                            details: { validation: { ...validation, saveable: false } },
+                            nextActions: ['Edit the DQL source', 'Fix with AI and run'],
+                        }));
+                        return;
+                    }
                     const currentPath = typeof body.path === 'string' ? body.path : undefined;
                     const saveOptions = {
                         currentPath,
@@ -13561,11 +14296,12 @@ export async function startLocalServer(opts) {
                 return;
             }
             /**
-             * Repair an editable notebook cell without starting Notebook AI research.
-             * The returned source is applied only to the in-memory notebook cell by the
-             * client; this endpoint never writes a block/domain/dbt source file.
+             * Repair an editable notebook cell or Block Studio draft without starting
+             * an AI conversation. The returned source is applied only to the in-memory
+             * editor by the client; this endpoint never writes governed source files.
              */
-            if (req.method === 'POST' && path === '/api/notebook/repair-execution') {
+            if (req.method === 'POST' && (path === '/api/notebook/repair-execution'
+                || path === '/api/block-studio/repair-and-run')) {
                 let body = {};
                 let execContext = null;
                 const start = Date.now();
@@ -15442,6 +16178,61 @@ function loadAppDashboard(projectRoot, appId, dashboardId) {
     }
     return null;
 }
+/**
+ * Resolves an App Studio draft directly from local SQLite for read-only preview.
+ * The draft is never copied into the Git-owned `apps/` tree. This gives manual
+ * and AI authoring the same execution path and the same filter/story receipts
+ * as a published App while keeping publication explicit.
+ */
+function loadAppBuildDraftDashboard(projectRoot, draftId, dashboardId) {
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        const draft = storage.getAppBuildDraft(draftId);
+        if (!draft)
+            return null;
+        const dashboard = draft.pages.find((page) => page.id === dashboardId);
+        if (!dashboard)
+            return null;
+        const base = draft.baseApp ? findAppById(projectRoot, draft.baseApp.appId) : null;
+        const app = base?.app ?? {
+            version: 1,
+            id: draft.appId,
+            name: draft.name,
+            description: draft.frame.goal,
+            visibility: 'private',
+            publicationIntent: 'personal',
+            domain: dashboard.metadata.domain ?? 'general',
+            usesDomains: [],
+            requiredExports: [],
+            audience: draft.frame.audience || 'stakeholders',
+            lifecycle: 'draft',
+            owners: ['local-author'],
+            tags: ['app-studio', 'local-draft'],
+            members: [],
+            roles: [],
+            policies: [],
+            homepage: { type: 'dashboard', id: dashboard.id },
+        };
+        return {
+            app: { ...app, id: draft.appId, name: draft.name, visibility: 'private', lifecycle: 'draft' },
+            dashboard,
+            appDir: base?.appDir ?? join(projectRoot, '.dql', 'local', 'app-builds', draft.id),
+            draftArtifactsDir: join(projectRoot, '.dql', 'local', 'app-builds', draft.id),
+        };
+    }
+    finally {
+        storage.close();
+    }
+}
+function findAppById(projectRoot, appId) {
+    for (const path of findAppDocuments(projectRoot)) {
+        const { document: app } = loadAppDocument(path);
+        if (app?.id !== appId)
+            continue;
+        return { app, appDir: path.slice(0, -'/dql.app.json'.length) };
+    }
+    return null;
+}
 function resolveDashboardItemBlock(item, manifest) {
     if (!item.block)
         return null;
@@ -15542,6 +16333,7 @@ function serializeSkill(skill) {
         clarifyWhen: skill.clarifyWhen,
         examples: skill.examples,
         sourceRefs: skill.sourceRefs,
+        analyticalPolicy: skill.analyticalPolicy,
         vocabulary: skill.vocabulary,
         sourcePath: skill.sourcePath,
         isStarter: skill.isStarter,
@@ -15597,9 +16389,27 @@ function parseSkillInput(raw, fallbackId) {
         examples: asStrings(skill.examples),
         sourceRefs: asStrings(skill.sourceRefs),
         vocabulary: asMap(skill.vocabulary),
+        analyticalPolicy: parseSkillAnalyticalPolicyInput(skill.analyticalPolicy),
         isStarter: skill.isStarter === true ? true : undefined,
     };
 }
+function parseSkillAnalyticalPolicyInput(value) {
+    const policy = contextRecord(value);
+    if (!Object.keys(policy).length)
+        return undefined;
+    const strings = (input) => Array.isArray(input) ? input.filter((item) => typeof item === 'string') : [];
+    const pick = (input) => typeof input === 'string' && input.trim() ? input.trim() : undefined;
+    return {
+        metricIds: strings(policy.metricIds ?? policy.metric_ids),
+        timeRole: pick(policy.timeRole ?? policy.time_role),
+        calendarId: pick(policy.calendarId ?? policy.calendar_id),
+        timezone: pick(policy.timezone),
+        completenessPolicy: ['partial_current', 'latest_complete', 'closed_period'].includes(String(policy.completenessPolicy ?? policy.completeness_policy)) ? String(policy.completenessPolicy ?? policy.completeness_policy) : undefined,
+        comparisonAlignment: ['elapsed_period', 'calendar_period', 'fiscal_period'].includes(String(policy.comparisonAlignment ?? policy.comparison_alignment)) ? String(policy.comparisonAlignment ?? policy.comparison_alignment) : undefined,
+        defaultRankingPeriod: ['current', 'comparison'].includes(String(policy.defaultRankingPeriod ?? policy.default_ranking_period)) ? String(policy.defaultRankingPeriod ?? policy.default_ranking_period) : undefined,
+        narrativeGuidance: strings(policy.narrativeGuidance ?? policy.narrative_guidance),
+    };
+}
 /** Loose, case/slug-insensitive domain key for counting membership. */
 function domainKey(value) {
     if (!value)
@@ -15759,7 +16569,947 @@ export function parseDomainInput(raw, fallbackId) {
         sourcePath: typeof domain.sourcePath === 'string' ? domain.sourcePath : undefined,
     };
 }
-function contextBootstrapDir(projectRoot) {
+/** Bounded discovery: an import scan reads at most this many YAML files. */
+const MODELING_IMPORT_FILE_LIMIT = 100;
+function modelingImportDirectory(projectRoot) {
+    return join(projectRoot, '.dql', 'local', 'modeling-imports');
+}
+function modelingImportSessionPath(projectRoot, id) {
+    const safe = id.replace(/[^a-zA-Z0-9_-]/g, '');
+    if (!safe || safe !== id)
+        throw new Error('Invalid modeling import id.');
+    return join(modelingImportDirectory(projectRoot), `${safe}.json`);
+}
+function writeModelingImportSession(projectRoot, session) {
+    mkdirSync(modelingImportDirectory(projectRoot), { recursive: true });
+    writeFileSync(modelingImportSessionPath(projectRoot, session.id), `${JSON.stringify(session, null, 2)}\n`, 'utf8');
+}
+function readModelingImportSession(projectRoot, id) {
+    const path = modelingImportSessionPath(projectRoot, id);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed.version === 1 && parsed.id === id ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function publicModelingImportSession(session) {
+    return {
+        ...session,
+        candidates: session.candidates.map(({ document: _document, ...candidate }) => candidate),
+    };
+}
+function createModelingImportSession(projectRoot, gitRoot, loopback, source) {
+    const mode = source.mode;
+    if (mode !== 'current_project' && mode !== 'path' && mode !== 'upload' && mode !== 'paste')
+        throw Object.assign(new Error('Choose current_project, path, upload, or paste.'), { code: 'INVALID_REQUEST' });
+    const files = [];
+    const truncationWarnings = [];
+    if (mode === 'paste' || mode === 'upload') {
+        const content = typeof source.content === 'string' ? source.content : '';
+        if (!content.trim() || Buffer.byteLength(content) > 1_000_000)
+            throw Object.assign(new Error('YAML content is required and must be 1 MB or smaller.'), { code: 'MODELING_IMPORT_LIMIT' });
+        files.push({ name: typeof source.filename === 'string' ? source.filename : mode === 'paste' ? 'pasted-modeling.yaml' : 'uploaded-modeling.yaml', content, inProject: false });
+    }
+    else {
+        if (mode === 'path' && !loopback)
+            throw Object.assign(new Error('Local path import is available only on the loopback Notebook runtime.'), { code: 'PATH_ACCESS_FORBIDDEN' });
+        const allowedRoot = realpathSync(resolve(gitRoot ?? projectRoot));
+        const requestedInput = mode === 'current_project'
+            ? resolve(projectRoot)
+            : resolve(projectRoot, typeof source.path === 'string' ? source.path : '');
+        if (!existsSync(requestedInput))
+            throw Object.assign(new Error('The selected YAML path does not exist.'), { code: 'MODELING_IMPORT_NOT_FOUND' });
+        const requested = realpathSync(requestedInput);
+        if (requested !== allowedRoot && !requested.startsWith(`${allowedRoot}${sep}`))
+            throw Object.assign(new Error('Import path must stay inside the current Git workspace.'), { code: 'PATH_ACCESS_FORBIDDEN' });
+        const paths = collectModelingYamlPaths(requested, MODELING_IMPORT_FILE_LIMIT);
+        // Truncation used to be silent, which reads as "DQL did not find my file".
+        if (paths.length >= MODELING_IMPORT_FILE_LIMIT) {
+            truncationWarnings.push(`Only the first ${MODELING_IMPORT_FILE_LIMIT} YAML files in this location were scanned. Point the import at a narrower folder to see the rest.`);
+        }
+        for (const path of paths) {
+            const size = statSync(path).size;
+            if (size > 1_000_000) {
+                truncationWarnings.push(`Skipped ${relative(requested, path).replace(/\\/g, '/')}: larger than the 1 MB import limit.`);
+                continue;
+            }
+            const resolvedPath = realpathSync(path);
+            if (resolvedPath !== allowedRoot && !resolvedPath.startsWith(`${allowedRoot}${sep}`))
+                continue;
+            const resolvedProject = realpathSync(projectRoot);
+            files.push({ name: relative(requested, resolvedPath).replace(/\\/g, '/') || resolvedPath.split(sep).at(-1), path: relative(resolvedProject, resolvedPath).replace(/\\/g, '/'), content: readFileSync(resolvedPath, 'utf8'), inProject: resolvedPath === resolvedProject || resolvedPath.startsWith(`${resolvedProject}${sep}`) });
+        }
+    }
+    if (files.length === 0)
+        throw Object.assign(new Error('No YAML files were found in the selected source.'), { code: 'MODELING_IMPORT_EMPTY' });
+    const candidates = files.map((file, index) => classifyModelingYamlCandidate(file, index));
+    const now = new Date().toISOString();
+    const session = {
+        version: 1,
+        id: apiRequestId('import'),
+        createdAt: now,
+        updatedAt: now,
+        source: { mode, label: mode === 'path' ? String(source.path ?? '') : mode === 'current_project' ? 'Current project' : files[0].name },
+        candidates,
+        ...(truncationWarnings.length ? { warnings: truncationWarnings } : {}),
+    };
+    writeModelingImportSession(projectRoot, session);
+    return session;
+}
+function collectModelingYamlPaths(start, limit) {
+    if (!existsSync(start))
+        throw Object.assign(new Error('The selected YAML path does not exist.'), { code: 'MODELING_IMPORT_NOT_FOUND' });
+    if (statSync(start).isFile())
+        return /\.ya?ml$/i.test(start) ? [start] : [];
+    const output = [];
+    const visit = (directory) => {
+        if (output.length >= limit)
+            return;
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (output.length >= limit)
+                return;
+            if (entry.name.startsWith('.') || ['node_modules', 'target', 'dist', 'build'].includes(entry.name))
+                continue;
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (entry.isFile() && /\.ya?ml$/i.test(entry.name))
+                output.push(path);
+        }
+    };
+    visit(start);
+    return output.sort();
+}
+function classifyModelingYamlCandidate(file, index) {
+    let document = {};
+    try {
+        const parsed = loadYaml(file.content);
+        document = contextRecord(parsed);
+    }
+    catch (error) {
+        return { id: `file-${index + 1}`, name: file.name, path: file.path, dialect: 'unsupported', action: 'unsupported', summary: 'Malformed YAML', warnings: [error instanceof Error ? error.message : String(error)] };
+    }
+    const keys = new Set(Object.keys(document));
+    const dialect = keys.has('entities') || keys.has('relationships') || keys.has('area') || keys.has('domain')
+        ? 'dql_modeling'
+        : keys.has('semantic_models') || keys.has('metrics')
+            ? 'dbt_semantic'
+            : keys.has('models') || keys.has('sources')
+                ? 'dbt_resource'
+                : 'unsupported';
+    const objectCount = ['entities', 'relationships', 'models', 'sources', 'semantic_models', 'metrics']
+        .reduce((total, key) => total + (Array.isArray(document[key]) ? document[key].length : 0), 0);
+    const openExisting = file.inProject && dialect === 'dql_modeling' && Boolean(file.path?.startsWith('domains/'));
+    return {
+        id: `file-${index + 1}`,
+        name: file.name,
+        path: file.path,
+        dialect,
+        action: dialect === 'unsupported' ? 'unsupported' : openExisting ? 'open_existing' : 'import',
+        summary: dialect === 'unsupported' ? 'Unsupported generic YAML' : `${objectCount || 1} ${dialect.replace('_', ' ')} candidate${objectCount === 1 ? '' : 's'}`,
+        warnings: dialect === 'unsupported' ? ['v1 supports DQL modeling, dbt resource, and dbt semantic YAML only.'] : openExisting ? ['This is already governed by the current project and should be opened in place.'] : [],
+        document,
+    };
+}
+function modelingImportOperations(session, selectedIds, domain, areaId, manifest) {
+    const diagnostics = [];
+    const operations = [];
+    const selected = session.candidates.filter((candidate) => selectedIds.includes(candidate.id));
+    if (!selected.length)
+        throw Object.assign(new Error('Select at least one supported YAML candidate.'), { code: 'MODELING_IMPORT_EMPTY' });
+    const packageExists = Boolean(manifest.modeling?.packages?.[domain]);
+    const area = Object.values(manifest.modeling?.areas ?? {}).find((item) => item.domain === domain && (item.localId === areaId || item.qualifiedId === areaId));
+    // A missing Domain/subject area is created by `ensureAuthoringScopeOperations`
+    // as part of this same proposal, so it is reported, not blocked.
+    if (!packageExists)
+        diagnostics.push({ code: 'DOMAIN_CREATED', severity: 'info', message: `Domain "${domain}" does not exist yet and will be created with these models.` });
+    if (!area)
+        diagnostics.push({ code: 'MODEL_AREA_CREATED', severity: 'info', message: `Subject area "${areaId}" does not exist yet in ${domain} and will be created with these models.` });
+    const nodes = Object.values(manifest.dbtProvenance?.nodes ?? {});
+    const resolveDbt = (reference, operationId) => {
+        const cleaned = reference.replace(/^ref\(['"]|['"]\)$/g, '').replace(/^model\./, '');
+        const matches = nodes.filter((node) => node.uniqueId === reference || node.name === reference || node.name === cleaned || node.uniqueId.endsWith(`.${cleaned}`));
+        if (matches.length !== 1)
+            diagnostics.push({ code: matches.length ? 'AMBIGUOUS_DBT_MODEL' : 'DBT_MODEL_NOT_FOUND', severity: 'blocking', operationId, message: `${reference} ${matches.length ? 'matches multiple dbt models' : 'was not found in the active dbt manifest'}.` });
+        return matches.length === 1 ? matches[0].uniqueId : undefined;
+    };
+    const used = new Set(Object.values(manifest.modeling?.entities ?? {}).filter((entity) => entity.domain === domain).map((entity) => entity.localId));
+    /**
+     * REL-004: dbt already declares its relationships. Every model this import
+     * binds is recorded here so the dbt `relationships` tests and MetricFlow
+     * `entities:` blocks covering those models become draft edges instead of
+     * leaving the author to redraw connections they already wrote down.
+     */
+    const boundEntityByDbtId = new Map();
+    const semanticPrimaryByName = new Map();
+    const semanticForeignRefs = [];
+    const allocate = (value) => {
+        const base = authoringSlug(value).replace(/-/g, '_') || 'model';
+        let id = base;
+        let suffix = 2;
+        while (used.has(id))
+            id = `${base}_${suffix++}`;
+        used.add(id);
+        return id;
+    };
+    for (const candidate of selected) {
+        if (candidate.action === 'open_existing') {
+            diagnostics.push({ code: 'OPEN_EXISTING_SOURCE', severity: 'info', message: `${candidate.path ?? candidate.name} is already in the current Domain Package and was not copied.` });
+            continue;
+        }
+        if (candidate.dialect === 'unsupported' || !candidate.document) {
+            diagnostics.push({ code: 'UNSUPPORTED_YAML', severity: 'blocking', message: `${candidate.name} is not DQL or dbt modeling YAML.` });
+            continue;
+        }
+        const document = candidate.document;
+        if (candidate.dialect === 'dql_modeling') {
+            const importedEntities = new Map();
+            for (const [index, raw] of contextArray(document.entities).entries()) {
+                const entity = contextRecord(raw);
+                const operationId = `${candidate.id}:entity:${index + 1}`;
+                const dbtModel = resolveDbt(String(entity.dbt_model ?? entity.dbtModel ?? ''), operationId);
+                if (!dbtModel)
+                    continue;
+                const sourceId = String(entity.id ?? nodes.find((node) => node.uniqueId === dbtModel)?.name ?? `model_${index + 1}`);
+                const id = allocate(sourceId);
+                boundEntityByDbtId.set(dbtModel, { id, operationId });
+                importedEntities.set(sourceId, { id, operationId });
+                importedEntities.set(String(entity.qualified_id ?? entity.qualifiedId ?? ''), { id, operationId });
+                importedEntities.set(dbtModel, { id, operationId });
+                operations.push({ id: operationId, kind: 'modeling_change', evidence: [candidate.path ?? candidate.name, dbtModel], change: { operation: 'upsert_entity', value: { id, domain, areaId: area?.localId ?? areaId, dbtModel, businessName: typeof entity.business_name === 'string' ? entity.business_name : undefined, businessContext: typeof entity.business_context === 'string' ? entity.business_context : undefined, conceptRefs: contextStrings(entity.concept_refs), analyticalRole: parseImportedAnalyticalRole(entity.analytical_role), status: 'draft', owner: typeof entity.owner === 'string' ? entity.owner : undefined, grain: typeof entity.grain === 'string' ? entity.grain : undefined, keys: contextStrings(entity.keys) } } });
+            }
+            for (const [index, raw] of contextArray(document.relationships).entries()) {
+                const relationship = contextRecord(raw);
+                const operationId = `${candidate.id}:relationship:${index + 1}`;
+                const keys = contextArray(relationship.keys).flatMap((value) => {
+                    const key = contextRecord(value);
+                    return typeof key.from === 'string' && typeof key.to === 'string' ? [{ from: key.from, to: key.to }] : [];
+                });
+                if (!relationship.from || !relationship.to || !keys.length) {
+                    diagnostics.push({ code: 'RELATIONSHIP_INCOMPLETE', severity: 'blocking', operationId, message: 'Imported relationship requires from, to, and at least one key pair.' });
+                    continue;
+                }
+                const resolveEndpoint = (rawRef) => {
+                    const ref = String(rawRef);
+                    const imported = importedEntities.get(ref);
+                    if (imported)
+                        return { id: imported.id, dependency: imported.operationId };
+                    const matches = Object.values(manifest.modeling?.entities ?? {}).filter((entity) => entity.domain === domain && (entity.localId === ref || entity.id === ref || entity.qualifiedId === ref));
+                    return matches.length === 1 ? { id: matches[0].localId } : {};
+                };
+                const from = resolveEndpoint(relationship.from);
+                const to = resolveEndpoint(relationship.to);
+                if (!from.id || !to.id) {
+                    diagnostics.push({ code: 'RELATIONSHIP_REFERENCE_UNRESOLVED', severity: 'blocking', operationId, message: `Relationship endpoints must resolve inside ${domain}; simple import cannot create cross-domain relationships.` });
+                    continue;
+                }
+                operations.push({ id: operationId, kind: 'modeling_change', dependsOn: [...new Set([from.dependency, to.dependency].filter((value) => Boolean(value)))], evidence: [candidate.path ?? candidate.name], change: { operation: 'upsert_relationship', value: { id: String(relationship.id ?? `${relationship.from}_to_${relationship.to}`), domain, areaId: area?.localId ?? areaId, from: from.id, to: to.id, keys, cardinality: parseImportedCardinality(relationship.cardinality), fanout: parseImportedFanout(relationship.fanout), status: 'draft', description: typeof relationship.description === 'string' ? relationship.description : undefined, rationale: 'Imported as a draft; certification and warehouse proof were intentionally removed.' } } });
+            }
+        }
+        else {
+            const modelRecords = candidate.dialect === 'dbt_resource'
+                ? contextArray(document.models)
+                : contextArray(document.semantic_models);
+            for (const [index, raw] of modelRecords.entries()) {
+                const model = contextRecord(raw);
+                const operationId = `${candidate.id}:model:${index + 1}`;
+                const reference = String(model.model ?? model.name ?? '');
+                const dbtModel = resolveDbt(reference, operationId);
+                if (!dbtModel)
+                    continue;
+                const existing = Object.values(manifest.modeling?.entities ?? {}).find((entity) => entity.dbtUniqueId === dbtModel);
+                if (existing && existing.domain !== domain) {
+                    diagnostics.push({ code: 'OWNERSHIP_CONFLICT', severity: 'blocking', operationId, message: `${dbtModel} is already owned by ${existing.domain}; import cannot move it implicitly.` });
+                    continue;
+                }
+                const id = existing?.localId ?? allocate(String(model.name ?? nodes.find((node) => node.uniqueId === dbtModel)?.name ?? `model_${index + 1}`));
+                boundEntityByDbtId.set(dbtModel, { id, operationId });
+                // MetricFlow states its own join graph in `entities:`; keep the primary
+                // key so the semantic branch can pair it with foreign references below.
+                const semanticEntities = contextArray(model.entities).map(contextRecord);
+                const primary = semanticEntities.find((entry) => entry.type === 'primary');
+                if (primary?.name)
+                    semanticPrimaryByName.set(String(primary.name), { dbtModel, column: String(primary.expr ?? primary.name) });
+                for (const entry of semanticEntities) {
+                    if (entry.type !== 'foreign' || !entry.name)
+                        continue;
+                    semanticForeignRefs.push({ name: String(entry.name), column: String(entry.expr ?? entry.name), dbtModel, operationId });
+                }
+                const aggTimeDimension = contextRecord(model.defaults).agg_time_dimension;
+                operations.push({ id: operationId, kind: 'modeling_change', evidence: [candidate.path ?? candidate.name, dbtModel], change: { operation: 'upsert_entity', value: { id, domain, areaId: area?.localId ?? areaId, dbtModel, businessName: typeof model.name === 'string' ? titleCaseAuthoring(model.name) : undefined, businessContext: typeof model.description === 'string' ? model.description : undefined, status: 'draft', analyticalRole: 'unknown', ...(typeof aggTimeDimension === 'string' ? { grain: aggTimeDimension } : {}), ...(primary?.name ? { keys: [String(primary.expr ?? primary.name)] } : {}) } } });
+            }
+        }
+    }
+    // REL-004: pair MetricFlow foreign references against the primary entity of
+    // the same name. This is dbt's own declared join graph, so it needs no
+    // guessing — but it is still only a draft candidate (REL-001).
+    for (const reference of semanticForeignRefs) {
+        const primary = semanticPrimaryByName.get(reference.name);
+        if (!primary || primary.dbtModel === reference.dbtModel)
+            continue;
+        const from = boundEntityByDbtId.get(reference.dbtModel);
+        const to = boundEntityByDbtId.get(primary.dbtModel);
+        if (!from || !to)
+            continue;
+        operations.push({
+            id: `semantic-entity:${from.id}:${to.id}:${reference.name}`,
+            kind: 'modeling_change',
+            dependsOn: [...new Set([from.operationId, to.operationId])],
+            evidence: [`MetricFlow entity "${reference.name}" declared foreign in ${reference.dbtModel} and primary in ${primary.dbtModel}`],
+            change: {
+                operation: 'upsert_relationship',
+                value: {
+                    id: `${from.id}_to_${to.id}`, domain, areaId: area?.localId ?? areaId,
+                    from: from.id, to: to.id,
+                    keys: [{ from: reference.column, to: primary.column }],
+                    cardinality: 'many_to_one', fanout: 'unknown', status: 'draft',
+                    verb: reference.name,
+                    rationale: 'Declared by the MetricFlow semantic entity graph. Validate against the warehouse before certifying.',
+                },
+            },
+        });
+    }
+    // REL-004: dbt `relationships` tests state an exact key pair and are already
+    // enforced by `dbt test`, which makes them the strongest available candidate.
+    // They remain drafts: a dbt test is evidence, never join authorization.
+    const manifestPath = manifest.dbtProvenance?.manifestPath;
+    if (manifestPath && boundEntityByDbtId.size > 1) {
+        let rawManifest;
+        try {
+            rawManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            rawManifest = undefined;
+        }
+        if (rawManifest) {
+            for (const edge of collectDbtRelationshipTests(rawManifest, new Set(boundEntityByDbtId.keys()))) {
+                if (edge.fromColumn === 'unknown' || edge.toColumn === 'unknown')
+                    continue;
+                const from = boundEntityByDbtId.get(edge.fromDbtUniqueId);
+                const to = boundEntityByDbtId.get(edge.toDbtUniqueId);
+                if (!from || !to || from.id === to.id)
+                    continue;
+                const id = `${from.id}_to_${to.id}`;
+                if (operations.some((operation) => operation.kind === 'modeling_change' && operation.change.operation === 'upsert_relationship' && operation.change.value.id === id))
+                    continue;
+                operations.push({
+                    id: `dbt-test:${edge.testUniqueId}`,
+                    kind: 'modeling_change',
+                    dependsOn: [...new Set([from.operationId, to.operationId])],
+                    evidence: [edge.testUniqueId, ...(edge.sourcePath ? [edge.sourcePath] : [])],
+                    change: {
+                        operation: 'upsert_relationship',
+                        value: {
+                            id, domain, areaId: area?.localId ?? areaId,
+                            from: from.id, to: to.id,
+                            keys: [{ from: edge.fromColumn, to: edge.toColumn }],
+                            cardinality: 'many_to_one', fanout: 'unknown', status: 'draft',
+                            rationale: `Declared by the dbt relationships test ${edge.testUniqueId}. Validate against the warehouse before certifying.`,
+                        },
+                    },
+                });
+            }
+        }
+    }
+    if (!operations.length)
+        throw Object.assign(new Error('The selected YAML did not produce any resolvable modeling changes.'), { code: 'MODELING_IMPORT_EMPTY', diagnostics });
+    return { operations, diagnostics };
+}
+function contextRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function contextArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function contextStrings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function parseImportedAnalyticalRole(value) {
+    return value === 'event' || value === 'dimension' || value === 'snapshot' || value === 'bridge' ? value : 'unknown';
+}
+function parseImportedCardinality(value) {
+    return value === 'one_to_one' || value === 'one_to_many' || value === 'many_to_one' || value === 'many_to_many' ? value : 'unknown';
+}
+function parseImportedFanout(value) {
+    if (value === 'unsafe' || value === 'forbidden')
+        return 'forbidden';
+    return value === 'safe' || value === 'dedupe_required' || value === 'attribution_required' ? value : 'unknown';
+}
+function contextSourceReferenceExists(manifest, reference) {
+    if (!reference.includes('::entity::') && !reference.includes('::relationship::'))
+        return true;
+    return Object.values(manifest.modeling?.entities ?? {}).some((entity) => entity.qualifiedId === reference)
+        || Object.values(manifest.modeling?.relationships ?? {}).some((relationship) => relationship.qualifiedId === reference);
+}
+function parseContextAuthoringOrigin(value) {
+    if (value === 'manual' || value === 'yaml_import' || value === 'dbt_discovery' || value === 'ai' || value === 'correction')
+        return value;
+    throw Object.assign(new Error('A valid context proposal origin is required.'), { code: 'INVALID_REQUEST' });
+}
+function parseContextAuthoringOperations(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > 100)
+        throw Object.assign(new Error('Provide 1-100 authoring operations.'), { code: 'INVALID_REQUEST' });
+    const ids = new Set();
+    return value.map((raw, index) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw Object.assign(new Error(`Operation ${index + 1} is invalid.`), { code: 'INVALID_REQUEST' });
+        const operation = raw;
+        const id = typeof operation.id === 'string' ? operation.id.trim() : '';
+        if (!id || ids.has(id))
+            throw Object.assign(new Error(`Operation ${index + 1} requires a unique id.`), { code: 'INVALID_REQUEST' });
+        ids.add(id);
+        const dependsOn = Array.isArray(operation.dependsOn) ? operation.dependsOn.filter((item) => typeof item === 'string') : undefined;
+        const evidence = Array.isArray(operation.evidence) ? operation.evidence.filter((item) => typeof item === 'string').slice(0, 32) : undefined;
+        if (operation.kind === 'modeling_change') {
+            const change = operation.change;
+            const allowed = new Set(['upsert_domain', 'upsert_area', 'upsert_entity', 'upsert_relationship', 'upsert_contract', 'upsert_export', 'upsert_import', 'remove_entity', 'remove_relationship', 'remove_area', 'remove_contract', 'remove_export', 'remove_import']);
+            if (!change || typeof change !== 'object' || !allowed.has(change.operation) || !('value' in change) || !change.value || typeof change.value !== 'object')
+                throw Object.assign(new Error(`Modeling operation ${id} is invalid.`), { code: 'INVALID_REQUEST' });
+            return { id, kind: 'modeling_change', change, dependsOn, evidence };
+        }
+        if (operation.kind === 'skill_change') {
+            const skillOperation = operation.operation;
+            const skill = operation.value;
+            if ((skillOperation !== 'create' && skillOperation !== 'update' && skillOperation !== 'move') || !skill || typeof skill.id !== 'string' || !skill.id.trim() || typeof skill.body !== 'string')
+                throw Object.assign(new Error(`Skill operation ${id} is invalid.`), { code: 'INVALID_REQUEST' });
+            return {
+                id,
+                kind: 'skill_change',
+                operation: skillOperation,
+                value: { ...skill, scope: 'project', status: 'draft' },
+                targetQualifiedId: typeof operation.targetQualifiedId === 'string' ? operation.targetQualifiedId : undefined,
+                expectedSourceHash: typeof operation.expectedSourceHash === 'string' ? operation.expectedSourceHash : undefined,
+                dependsOn,
+                evidence,
+            };
+        }
+        if (operation.kind === 'dbt_source_change') {
+            const change = operation.change;
+            if (!change || typeof change.uniqueId !== 'string' || !change.uniqueId.trim())
+                throw Object.assign(new Error(`dbt source operation ${id} is invalid.`), { code: 'INVALID_REQUEST' });
+            return { id, kind: 'dbt_source_change', change, dependsOn, evidence };
+        }
+        throw Object.assign(new Error(`Unsupported context operation kind for ${id}.`), { code: 'INVALID_REQUEST' });
+    });
+}
+function resolveContextPatchPath(projectRoot, gitRoot, relativePath) {
+    const allowedRoot = resolve(gitRoot ?? projectRoot);
+    const absolute = resolve(projectRoot, relativePath);
+    if (absolute !== allowedRoot && !absolute.startsWith(`${allowedRoot}${sep}`)) {
+        throw Object.assign(new Error(`Proposal path escapes the Git workspace: ${relativePath}`), { code: 'OWNERSHIP_CONFLICT' });
+    }
+    return absolute;
+}
+/**
+ * Modeling AI: propose modeling changes from repository metadata.
+ *
+ * `AGT-024` — the model receives manifest identifiers, columns, lineage, tests,
+ * current modeling, and source locations, and never query rows. It proposes;
+ * this function then validates every identifier against the live snapshot and
+ * drops anything invented, so a hallucinated model or column cannot enter a
+ * proposal. `previewContextAuthoring` independently forces `status: 'draft'`,
+ * strips certification and validation, and blocks deletes and cross-domain
+ * relationships, so nothing here can certify or authorize a join.
+ */
+async function buildAiModelingOperations(projectRoot, manifest, request, provider) {
+    const modeling = manifest.modeling;
+    if (!modeling || !manifest.dbtProvenance)
+        throw new Error('Modeling AI requires a compiled dbt-first project snapshot.');
+    const context = request.workspaceContext ?? {};
+    const requestedDomain = typeof context.domain === 'string'
+        ? context.domain
+        : request.selectedObject?.kind === 'domain' ? request.selectedObject.id : undefined;
+    const domain = requestedDomain ?? Object.keys(modeling.packages)[0] ?? defaultAuthoringDomainId(manifest);
+    const requestedArea = typeof context.modelAreaId === 'string' ? context.modelAreaId : typeof context.areaId === 'string' ? context.areaId : undefined;
+    const area = Object.values(modeling.areas).find((candidate) => candidate.domain === domain
+        && (!requestedArea || candidate.qualifiedId === requestedArea || candidate.localId === requestedArea));
+    const areaId = area?.localId ?? modelAreaLocalId(requestedArea) ?? DEFAULT_MODEL_AREA_ID;
+    const bound = new Set(Object.values(modeling.entities).map((entity) => entity.dbtUniqueId));
+    const manifestPath = resolveDbtManifestPath(projectRoot);
+    const describe = (uniqueId) => {
+        const detail = manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, uniqueId) : undefined;
+        return {
+            dbtUniqueId: uniqueId,
+            name: manifest.dbtProvenance.nodes[uniqueId]?.name,
+            relation: manifest.dbtProvenance.nodes[uniqueId]?.relation,
+            description: detail?.description,
+            columns: (detail?.columns ?? []).slice(0, 60).map((column) => ({ name: column.name, type: column.type, description: column.description })),
+            tests: (detail?.tests ?? []).slice(0, 40),
+        };
+    };
+    // Bound as candidates so a large project still fits a prompt.
+    const unbound = Object.values(manifest.dbtProvenance.nodes).filter((node) => !bound.has(node.uniqueId));
+    const tokens = authoringTokens(request.question);
+    const ranked = [
+        ...unbound.filter((node) => tokens.some((token) => `${node.name} ${node.uniqueId} ${node.sourcePath ?? ''}`.toLowerCase().includes(token))),
+        ...unbound,
+    ].filter((node, index, values) => values.findIndex((other) => other.uniqueId === node.uniqueId) === index).slice(0, 24);
+    const payload = {
+        request: request.question.trim(),
+        targetDomain: domain,
+        targetAreaId: areaId,
+        currentModels: Object.values(modeling.entities).filter((entity) => entity.domain === domain).map((entity) => ({
+            id: entity.localId, dbtUniqueId: entity.dbtUniqueId, businessName: entity.businessName,
+            businessContext: entity.businessContext, grain: entity.grain, keys: entity.keys, analyticalRole: entity.analyticalRole,
+        })),
+        currentRelationships: Object.values(modeling.relationships).filter((relationship) => relationship.ownerDomain === domain).map((relationship) => ({
+            id: relationship.localId, from: modeling.entities[relationship.from]?.localId, to: modeling.entities[relationship.to]?.localId,
+            keys: relationship.keys, cardinality: relationship.cardinality, fanout: relationship.fanout, status: relationship.status,
+        })),
+        availableDbtModels: ranked.map((node) => describe(node.uniqueId)),
+        focusedModel: request.selectedObject?.kind === 'model'
+            ? Object.values(modeling.entities).find((entity) => entity.qualifiedId === request.selectedObject.id)
+            : undefined,
+    };
+    let raw;
+    try {
+        raw = await provider.generate([
+            {
+                role: 'system',
+                content: [
+                    'You design analytical data models. Propose modeling changes for review; you are never applying them.',
+                    'Return exactly one JSON object in a ```json fence: {"operations":[...]}. No prose outside the fence.',
+                    'Each operation is {"kind":"upsert_entity","id":"<snake_case>","dbtModel":"<exact dbt unique id>","businessName":"...","businessContext":"...","grain":"...","keys":["..."],"analyticalRole":"event|dimension|snapshot|bridge|unknown"}',
+                    'or {"kind":"upsert_relationship","id":"<snake_case>","from":"<entity id>","to":"<entity id>","keys":[{"from":"<column>","to":"<column>"}],"cardinality":"one_to_one|one_to_many|many_to_one|many_to_many|unknown","fanout":"safe|dedupe_required|attribution_required|forbidden|unknown","verb":"...","description":"...","rationale":"..."}.',
+                    'Use ONLY dbt unique ids and column names present in the supplied metadata. Never invent an identifier.',
+                    'businessContext states what one row means in business terms. Never restate the request back as business context.',
+                    'Set cardinality and fanout from the evidence; use "unknown" when the metadata does not establish them. Never claim a relationship is certified or validated.',
+                    'Do not propose deletions, cross-domain relationships, or changes to dbt-owned SQL, columns, tests, or descriptions.',
+                ].join(' '),
+            },
+            { role: 'user', content: JSON.stringify(payload) },
+        ], { maxTokens: 3000, temperature: 0 });
+    }
+    catch (error) {
+        throw new Error(`The AI provider could not complete this modeling request: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const parsed = parseAiModelingOperations(raw);
+    if (parsed.length === 0)
+        throw new Error('Modeling AI did not return any usable modeling changes. Try naming the models or the relationship you want.');
+    // Validate every identifier against the live snapshot. An operation that
+    // references something the project does not have is dropped, not repaired.
+    const knownDbtIds = new Set(Object.keys(manifest.dbtProvenance.nodes));
+    const columnsFor = new Map();
+    const proposedEntityIds = new Set(Object.values(modeling.entities).filter((entity) => entity.domain === domain).map((entity) => entity.localId));
+    const operations = [];
+    for (const candidate of parsed) {
+        if (candidate.kind === 'upsert_entity') {
+            if (!candidate.dbtModel || !knownDbtIds.has(candidate.dbtModel))
+                continue;
+            const id = authoringSlug(candidate.id || candidate.dbtModel.split('.').at(-1) || 'model').replace(/-/g, '_');
+            if (!id)
+                continue;
+            proposedEntityIds.add(id);
+            const detail = manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, candidate.dbtModel) : undefined;
+            const columns = new Set((detail?.columns ?? []).map((column) => column.name.toLowerCase()));
+            columnsFor.set(id, columns);
+            operations.push({
+                id: `entity:${domain}:${id}`,
+                kind: 'modeling_change',
+                evidence: [candidate.dbtModel, ...(detail?.sourcePath ? [detail.sourcePath] : [])],
+                change: {
+                    operation: 'upsert_entity',
+                    value: {
+                        id, domain, areaId, dbtModel: candidate.dbtModel,
+                        businessName: candidate.businessName?.trim() || titleCaseAuthoring(id),
+                        businessContext: candidate.businessContext?.trim() || undefined,
+                        grain: candidate.grain && columns.has(candidate.grain.toLowerCase()) ? candidate.grain : undefined,
+                        keys: (candidate.keys ?? []).filter((key) => columns.has(key.toLowerCase())),
+                        analyticalRole: parseImportedAnalyticalRole(candidate.analyticalRole) ?? 'unknown',
+                        status: 'draft',
+                    },
+                },
+            });
+            continue;
+        }
+        const from = authoringSlug(candidate.from ?? '').replace(/-/g, '_');
+        const to = authoringSlug(candidate.to ?? '').replace(/-/g, '_');
+        if (!proposedEntityIds.has(from) || !proposedEntityIds.has(to) || from === to)
+            continue;
+        const knownColumns = (entityId) => {
+            const cached = columnsFor.get(entityId);
+            if (cached)
+                return cached;
+            const entity = Object.values(modeling.entities).find((item) => item.domain === domain && item.localId === entityId);
+            const detail = entity && manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, entity.dbtUniqueId) : undefined;
+            const columns = new Set((detail?.columns ?? []).map((column) => column.name.toLowerCase()));
+            columnsFor.set(entityId, columns);
+            return columns;
+        };
+        const fromColumns = knownColumns(from);
+        const toColumns = knownColumns(to);
+        const keys = (candidate.keys ?? []).filter((key) => key?.from && key?.to && fromColumns.has(key.from.toLowerCase()) && toColumns.has(key.to.toLowerCase()));
+        if (keys.length === 0)
+            continue;
+        const id = authoringSlug(candidate.id || `${from}_to_${to}`).replace(/-/g, '_');
+        operations.push({
+            id: `relationship:${domain}:${id}`,
+            kind: 'modeling_change',
+            dependsOn: [`entity:${domain}:${from}`, `entity:${domain}:${to}`].filter((dependency) => operations.some((operation) => operation.id === dependency)),
+            evidence: ['Modeling AI proposal from dbt metadata; requires warehouse validation before certification'],
+            change: {
+                operation: 'upsert_relationship',
+                value: {
+                    id, domain, areaId, from, to, keys,
+                    cardinality: parseImportedCardinality(candidate.cardinality),
+                    fanout: parseImportedFanout(candidate.fanout),
+                    status: 'draft',
+                    verb: candidate.verb?.trim() || undefined,
+                    description: candidate.description?.trim() || undefined,
+                    rationale: candidate.rationale?.trim() || undefined,
+                },
+            },
+        });
+    }
+    if (operations.length === 0)
+        throw new Error('Modeling AI referenced models or columns that are not in the current dbt snapshot, so nothing was proposed.');
+    return operations;
+}
+/** Tolerant JSON extraction; a malformed provider reply yields no operations. */
+export function parseAiModelingOperations(raw) {
+    const fenced = raw.match(/```json\s*([\s\S]*?)```/i)?.[1] ?? raw.match(/```\s*([\s\S]*?)```/)?.[1] ?? raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(fenced.trim());
+    }
+    catch {
+        return [];
+    }
+    const text = (value) => (typeof value === 'string' ? value : undefined);
+    return contextArray(contextRecord(parsed).operations).flatMap((value) => {
+        const record = contextRecord(value);
+        if (record.kind === 'upsert_entity') {
+            return [{
+                    kind: 'upsert_entity',
+                    id: text(record.id),
+                    dbtModel: text(record.dbtModel),
+                    businessName: text(record.businessName),
+                    businessContext: text(record.businessContext),
+                    grain: text(record.grain),
+                    analyticalRole: record.analyticalRole,
+                    keys: contextStrings(record.keys),
+                }];
+        }
+        if (record.kind === 'upsert_relationship') {
+            return [{
+                    kind: 'upsert_relationship',
+                    id: text(record.id),
+                    from: text(record.from),
+                    to: text(record.to),
+                    verb: text(record.verb),
+                    description: text(record.description),
+                    rationale: text(record.rationale),
+                    cardinality: record.cardinality,
+                    fanout: record.fanout,
+                    keys: contextArray(record.keys).flatMap((entry) => {
+                        const key = contextRecord(entry);
+                        return typeof key.from === 'string' && typeof key.to === 'string' ? [{ from: key.from, to: key.to }] : [];
+                    }),
+                }];
+        }
+        return [];
+    });
+}
+/**
+ * Evidence-only modeling suggestions: deterministic, no provider required.
+ *
+ * This is the `AGT-024` provider-unavailable fallback, not "Modeling AI". It
+ * matches dbt model names against the request and pairs shared `*_id` columns.
+ * Callers must label its output honestly so a user is never told a template
+ * expansion was an AI proposal.
+ */
+function buildDeterministicModelingOperations(projectRoot, manifest, request) {
+    const modeling = manifest.modeling;
+    if (!modeling || !manifest.dbtProvenance)
+        throw new Error('Modeling AI requires a compiled dbt-first project snapshot.');
+    const context = request.workspaceContext ?? {};
+    const requestedDomain = typeof context.domain === 'string'
+        ? context.domain
+        : request.selectedObject?.kind === 'domain'
+            ? request.selectedObject.id
+            : undefined;
+    const domain = requestedDomain ?? Object.keys(modeling.packages)[0];
+    if (!domain || !modeling.packages[domain])
+        throw new Error('Select or create a Domain before building models with AI.');
+    const selectedIdentity = request.selectedObject?.id;
+    const selectedRelationship = request.selectedObject?.kind === 'relationship'
+        ? Object.values(modeling.relationships).find((item) => item.qualifiedId === selectedIdentity || item.id === selectedIdentity || item.localId === selectedIdentity)
+        : undefined;
+    if (selectedRelationship) {
+        const cardinality = /one[-_ ]to[-_ ]one|1\s*:\s*1/i.test(request.question)
+            ? 'one_to_one'
+            : /one[-_ ]to[-_ ]many|1\s*:\s*n/i.test(request.question)
+                ? 'one_to_many'
+                : /many[-_ ]to[-_ ]one|n\s*:\s*1/i.test(request.question)
+                    ? 'many_to_one'
+                    : /many[-_ ]to[-_ ]many|n\s*:\s*n/i.test(request.question)
+                        ? 'many_to_many'
+                        : selectedRelationship.cardinality;
+        return [{
+                id: `relationship:${selectedRelationship.qualifiedId}`,
+                kind: 'modeling_change',
+                evidence: [selectedRelationship.sourcePath, ...(selectedRelationship.validation?.queryFingerprint ? [`validation:${selectedRelationship.validation.queryFingerprint}`] : [])],
+                change: {
+                    operation: 'upsert_relationship',
+                    value: {
+                        id: selectedRelationship.localId,
+                        domain: selectedRelationship.ownerDomain ?? domain,
+                        areaId: modelAreaLocalId(selectedRelationship.areaId),
+                        from: modeling.entities[selectedRelationship.from]?.localId ?? selectedRelationship.from,
+                        to: modeling.entities[selectedRelationship.to]?.localId ?? selectedRelationship.to,
+                        keys: selectedRelationship.keys,
+                        cardinality,
+                        fanout: selectedRelationship.fanout === 'unsafe' ? 'forbidden' : selectedRelationship.fanout,
+                        status: 'draft',
+                        owner: selectedRelationship.owner,
+                        ownerDomain: selectedRelationship.ownerDomain,
+                        verb: selectedRelationship.verb,
+                        description: selectedRelationship.description,
+                        rationale: request.question.trim(),
+                        roles: selectedRelationship.roles,
+                        optionality: selectedRelationship.optionality,
+                        joinTypes: selectedRelationship.joinTypes,
+                        aggregation: selectedRelationship.aggregation,
+                        temporal: selectedRelationship.temporal,
+                        attributionBlock: selectedRelationship.attributionBlock,
+                        importRefs: selectedRelationship.importRefs,
+                        evidenceExpiresAt: undefined,
+                    },
+                },
+            }];
+    }
+    const selectedEntity = request.selectedObject?.kind === 'model'
+        ? Object.values(modeling.entities).find((item) => item.qualifiedId === selectedIdentity || item.id === selectedIdentity || item.localId === selectedIdentity)
+        : undefined;
+    if (selectedEntity) {
+        // Without a provider there is nothing evidence-backed to propose here.
+        // Copying the raw request into `businessContext` would present the user's
+        // own prompt back to them as authored business meaning.
+        throw new Error('Writing business context needs an AI provider. Configure one in Settings, or edit this model directly in Modeling.');
+    }
+    const requestedArea = typeof context.modelAreaId === 'string' ? context.modelAreaId : typeof context.areaId === 'string' ? context.areaId : undefined;
+    const existingArea = Object.values(modeling.areas).find((area) => area.domain === domain
+        && (!requestedArea || area.qualifiedId === requestedArea || area.localId === requestedArea));
+    const areaId = existingArea?.localId ?? modelAreaLocalId(requestedArea) ?? `${authoringSlug(request.question).slice(0, 36) || 'metadata'}_models`;
+    const operations = [];
+    if (!existingArea) {
+        operations.push({
+            id: `area:${domain}:${areaId}`,
+            kind: 'modeling_change',
+            evidence: [`domain:${domain}`],
+            change: { operation: 'upsert_area', value: { id: areaId, domain, name: titleCaseAuthoring(areaId), description: `Metadata-backed modeling area requested by the author: ${request.question.trim()}`, intentExamples: [request.question.trim()] } },
+        });
+    }
+    const bound = new Set(Object.values(modeling.entities).map((entity) => entity.dbtUniqueId));
+    const tokens = authoringTokens(request.question);
+    let candidates = Object.values(manifest.dbtProvenance.nodes).filter((node) => !bound.has(node.uniqueId));
+    const matched = candidates.filter((node) => tokens.some((token) => `${node.name} ${node.uniqueId} ${node.sourcePath ?? ''}`.toLowerCase().includes(token)));
+    if (matched.length)
+        candidates = matched;
+    candidates = candidates.slice(0, 12);
+    if (candidates.length === 0)
+        throw new Error('No unbound dbt models match this request. Focus an existing model to update its business context.');
+    const usedIds = new Set(Object.values(modeling.entities).filter((entity) => entity.domain === domain).map((entity) => entity.localId));
+    for (const node of candidates) {
+        const base = authoringSlug(node.name).replace(/-/g, '_') || 'model';
+        let id = base;
+        let suffix = 2;
+        while (usedIds.has(id))
+            id = `${base}_${suffix++}`;
+        usedIds.add(id);
+        operations.push({
+            id: `entity:${domain}:${id}`,
+            kind: 'modeling_change',
+            dependsOn: existingArea ? [] : [`area:${domain}:${areaId}`],
+            evidence: [node.uniqueId, ...(node.sourcePath ? [node.sourcePath] : [])],
+            change: { operation: 'upsert_entity', value: { id, domain, areaId, dbtModel: node.uniqueId, businessName: titleCaseAuthoring(node.name), status: 'draft', analyticalRole: 'unknown' } },
+        });
+    }
+    if (/\b(connect|relationship|join|related)\b/i.test(request.question) && candidates.length >= 2) {
+        const manifestPath = resolveDbtManifestPath(projectRoot);
+        const left = manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, candidates[0].uniqueId) : undefined;
+        const right = manifestPath ? loadDbtNodeAuthoringDetail(manifestPath, candidates[1].uniqueId) : undefined;
+        const rightColumns = new Set((right?.columns ?? []).map((column) => column.name.toLowerCase()));
+        const sharedKey = (left?.columns ?? []).map((column) => column.name).find((name) => /(^id$|_id$)/i.test(name) && rightColumns.has(name.toLowerCase()));
+        if (sharedKey) {
+            const fromOperation = operations.find((operation) => operation.id.startsWith('entity:') && operation.kind === 'modeling_change' && operation.change.operation === 'upsert_entity' && operation.change.value.dbtModel === candidates[0].uniqueId);
+            const toOperation = operations.find((operation) => operation.id.startsWith('entity:') && operation.kind === 'modeling_change' && operation.change.operation === 'upsert_entity' && operation.change.value.dbtModel === candidates[1].uniqueId);
+            if (fromOperation?.kind === 'modeling_change' && fromOperation.change.operation === 'upsert_entity' && toOperation?.kind === 'modeling_change' && toOperation.change.operation === 'upsert_entity') {
+                const relationshipId = `${fromOperation.change.value.id}_to_${toOperation.change.value.id}`;
+                operations.push({
+                    id: `relationship:${domain}:${relationshipId}`,
+                    kind: 'modeling_change',
+                    dependsOn: [fromOperation.id, toOperation.id],
+                    evidence: [`shared column suggestion:${sharedKey}`, left?.uniqueId ?? '', right?.uniqueId ?? ''].filter(Boolean),
+                    change: { operation: 'upsert_relationship', value: { id: relationshipId, domain, areaId, from: fromOperation.change.value.id, to: toOperation.change.value.id, keys: [{ from: sharedKey, to: sharedKey }], cardinality: 'unknown', fanout: 'unknown', status: 'draft', rationale: 'Candidate only: shared dbt column name requires warehouse validation.' } },
+                });
+            }
+        }
+    }
+    return operations;
+}
+/**
+ * Skills AI: draft a domain skill's purpose, guardrails, and vocabulary.
+ *
+ * `SKILL-006` — the model sees qualified modeling/metric references, the
+ * current skill, and the Domain/Area scope. It writes prose and vocabulary
+ * only; every governed reference is taken from the deterministic base built
+ * below, so it cannot invent a metric, block, or model. `previewContextAuthoring`
+ * independently forces `status: 'draft'`, so a drafted skill never guides an
+ * agent until a human activates it.
+ */
+async function buildAiSkillOperations(projectRoot, manifest, request, provider) {
+    const base = buildMetadataBoundSkillOperations(projectRoot, manifest, request);
+    const operation = base[0];
+    if (!operation || operation.kind !== 'skill_change')
+        return base;
+    const raw = await provider.generate([
+        {
+            role: 'system',
+            content: [
+                'You write governed analytics guidance for one business domain.',
+                'Return exactly one JSON object in a ```json fence: {"description":"...","body":"...","triggers":["..."],"clarifyWhen":["..."],"vocabulary":{"term":"meaning"}}. No prose outside the fence.',
+                'body is markdown with a "## Purpose" section, a "## Guardrails" section, and a "## Clarify" section.',
+                'Write guidance an analyst would follow. Never restate the request back as the guidance.',
+                'Never name a metric, block, model, or relationship that is not in the supplied governed references.',
+                'Do not grant tools, authorize joins or data access, activate the skill, or write executable code.',
+            ].join(' '),
+        },
+        {
+            role: 'user',
+            content: JSON.stringify({
+                request: request.question.trim(),
+                domain: operation.value.domain,
+                modelAreaRefs: operation.value.modelAreaRefs,
+                currentSkill: { id: operation.value.id, description: operation.value.description, body: operation.value.body },
+                governedReferences: {
+                    metrics: operation.value.preferredMetrics,
+                    blocks: operation.value.preferredBlocks,
+                    modelingRefs: operation.value.sourceRefs,
+                },
+            }),
+        },
+    ], { maxTokens: 2000, temperature: 0.2 });
+    const fenced = raw.match(/```json\s*([\s\S]*?)```/i)?.[1] ?? raw.match(/```\s*([\s\S]*?)```/)?.[1] ?? raw;
+    let parsed;
+    try {
+        parsed = contextRecord(JSON.parse(fenced.trim()));
+    }
+    catch {
+        return base;
+    }
+    const body = typeof parsed.body === 'string' ? parsed.body.trim() : '';
+    if (!body)
+        return base;
+    const vocabulary = contextRecord(parsed.vocabulary);
+    return [{
+            ...operation,
+            evidence: [...(operation.evidence ?? []), 'drafted by Skills AI from governed references only'],
+            value: {
+                ...operation.value,
+                description: typeof parsed.description === 'string' && parsed.description.trim() ? parsed.description.trim() : operation.value.description,
+                body,
+                triggers: contextStrings(parsed.triggers).slice(0, 12).length ? contextStrings(parsed.triggers).slice(0, 12) : operation.value.triggers,
+                clarifyWhen: contextStrings(parsed.clarifyWhen).slice(0, 8).length ? contextStrings(parsed.clarifyWhen).slice(0, 8) : operation.value.clarifyWhen,
+                vocabulary: Object.fromEntries(Object.entries(vocabulary)
+                    .filter(([, value]) => typeof value === 'string')
+                    .slice(0, 24)),
+                // Governed references always come from the deterministic base; the model
+                // never gets to add one.
+                preferredMetrics: operation.value.preferredMetrics,
+                preferredBlocks: operation.value.preferredBlocks,
+                sourceRefs: operation.value.sourceRefs,
+                status: 'draft',
+            },
+        }];
+}
+function buildMetadataBoundSkillOperations(projectRoot, manifest, request) {
+    const context = request.workspaceContext ?? {};
+    const selectedIdentity = request.selectedObject?.kind === 'skill' ? request.selectedObject.id : undefined;
+    const existing = selectedIdentity
+        ? loadSkills(projectRoot).skills.find((skill) => skill.qualifiedId === selectedIdentity || skill.id === selectedIdentity)
+        : undefined;
+    const domain = typeof context.domain === 'string'
+        ? context.domain
+        : existing?.domain
+            ?? (request.selectedObject?.kind === 'domain' ? request.selectedObject.id : undefined)
+            ?? Object.keys(manifest.modeling?.packages ?? {})[0];
+    if (!domain)
+        throw new Error('Select a Domain before building a Skill with AI.');
+    const area = typeof context.modelAreaId === 'string' ? context.modelAreaId : existing?.modelAreaRefs?.[0];
+    const focusReference = request.selectedObject?.kind === 'model' || request.selectedObject?.kind === 'relationship'
+        ? request.selectedObject.id
+        : undefined;
+    if (focusReference && !contextSourceReferenceExists(manifest, focusReference))
+        throw new Error('The focused modeling object is not present in the current snapshot.');
+    const id = existing?.localId ?? existing?.id ?? `${authoringSlug(request.question).slice(0, 48) || domain.replace(/[^a-z0-9]+/gi, '-')}-guidance`;
+    const body = existing
+        ? `${existing.body.trim()}\n\n## Proposed correction\n${request.question.trim()}\n`
+        : `## Purpose\nGuide analysis for ${domain} using reviewed repository metadata.\n\n## Guardrails\n${request.question.trim()}\n\n## Clarify\nAsk when the requested metric, model, or relationship is not governed.`;
+    const value = {
+        id,
+        qualifiedId: existing?.qualifiedId,
+        sourcePath: existing?.sourcePath,
+        scope: 'project',
+        domain,
+        domains: [domain],
+        modelAreaRefs: area ? [area] : [],
+        kind: existing?.kind ?? 'domain_reference',
+        status: 'draft',
+        owner: existing?.owner,
+        triggers: existing?.triggers ?? authoringTokens(request.question).slice(0, 8),
+        exclusions: existing?.exclusions ?? [],
+        description: existing?.description ?? `Metadata-backed guidance for ${titleCaseAuthoring(domain)}.`,
+        preferredMetrics: existing?.preferredMetrics ?? Object.values(manifest.metrics ?? {}).filter((metric) => metric.domain === domain).slice(0, 12).map((metric) => metric.name),
+        preferredBlocks: existing?.preferredBlocks ?? Object.values(manifest.blocks ?? {}).filter((block) => block.domain === domain && block.status === 'certified').slice(0, 12).map((block) => block.name),
+        preferredDimensions: existing?.preferredDimensions ?? [],
+        requiredFilters: existing?.requiredFilters ?? [],
+        clarifyWhen: existing?.clarifyWhen ?? ['The request needs a model, metric, or relationship not present in the current governed context.'],
+        examples: existing?.examples ?? [request.question.trim()],
+        sourceRefs: [...new Set([...(existing?.sourceRefs ?? []), ...(focusReference ? [focusReference] : [])])],
+        vocabulary: existing?.vocabulary ?? {},
+        analyticalPolicy: existing?.analyticalPolicy,
+        body,
+        isStarter: existing?.isStarter,
+    };
+    const before = existing?.sourcePath && existsSync(existing.sourcePath) ? readFileSync(existing.sourcePath, 'utf8') : '';
+    return [{
+            id: `skill:${existing?.qualifiedId ?? `${domain}::skill::${id}`}`,
+            kind: 'skill_change',
+            operation: existing ? 'update' : 'create',
+            targetQualifiedId: existing?.qualifiedId,
+            expectedSourceHash: existing ? createHash('sha256').update(before).digest('hex') : undefined,
+            evidence: [existing?.sourcePath ?? `domain:${domain}`, ...(focusReference ? [focusReference] : [])],
+            value,
+        }];
+}
+/**
+ * The Domain an author lands in when none is selected: the single existing
+ * Domain if there is exactly one, otherwise a new one named after the dbt
+ * project. Callers keep full control — this is only the prefilled default.
+ */
+function defaultAuthoringDomainId(manifest) {
+    const packages = Object.keys(manifest.modeling?.packages ?? {});
+    if (packages.length === 1)
+        return packages[0];
+    const projectName = manifest.dbtProvenance?.projectName;
+    return projectName ? authoringSlug(projectName).replace(/-/g, '_') || 'analytics' : 'analytics';
+}
+function authoringTokens(value) {
+    const stop = new Set(['the', 'and', 'for', 'with', 'from', 'this', 'that', 'build', 'create', 'model', 'models', 'skill', 'please', 'into', 'about']);
+    return [...new Set(value.toLowerCase().split(/[^a-z0-9_]+/).filter((token) => token.length > 2 && !stop.has(token)))];
+}
+function authoringSlug(value) {
+    return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+function titleCaseAuthoring(value) {
+    return value.replace(/[._-]+/g, ' ').replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function contextBootstrapDir(projectRoot) {
     return join(projectRoot, '.dql', 'local', 'context-bootstrap');
 }
 function contextBootstrapPath(projectRoot, id) {
@@ -17172,6 +18922,132 @@ export function dashboardRuntimeVariables(dashboard, overrides = {}) {
     }
     return { ...variables, ...overrides };
 }
+/** Resolve semantic filters only through the component's explicit mapping. */
+export function dashboardSemanticFiltersForTile(dashboard, item, dashboardValues) {
+    if (!item.semantic)
+        return [];
+    return (dashboard.filters ?? []).flatMap((filter) => {
+        if (filter.scope?.tileIds && !filter.scope.tileIds.includes(item.i))
+            return [];
+        const binding = item.filterBindings?.find((candidate) => candidate.filter === filter.id
+            && candidate.capability !== 'unsupported'
+            && !candidate.unsupportedReason);
+        const dimension = binding?.binding;
+        const value = dashboardValues[filter.id];
+        if (!dimension || !item.semantic?.dimensions?.includes(dimension) || isEmptyDashboardFilterValue(value))
+            return [];
+        const values = Array.isArray(value) ? value.map(String) : [String(value)];
+        return [{ dimension, operator: values.length > 1 ? 'in' : 'equals', values }];
+    });
+}
+/**
+ * Return bounded, run-scoped filter choices only from columns the server has
+ * already proven safe for predicate filtering. These sampled labels are sent
+ * to the browser for a searchable control and are never written to `.dqld`.
+ */
+export function collectDashboardFilterOptions(dashboard, tiles, defaultLimit = 100) {
+    const items = new Map(dashboard.layout.items.map((item) => [item.i, item]));
+    const optionSets = [];
+    for (const filter of dashboard.filters ?? []) {
+        if (filter.type === 'boolean' || filter.type === 'relative_date' || filter.type === 'number_range')
+            continue;
+        const dateControl = filter.type === 'daterange' || filter.type === 'date';
+        const limit = Math.max(1, Math.min(100, filter.optionSource?.limit ?? defaultLimit));
+        const values = new Set();
+        const sourceTileIds = [];
+        let truncated = false;
+        for (const tile of tiles) {
+            const result = dashboardFilterOptionResult(tile.result);
+            if (tile.status !== 'ok' || !result?.rows.length)
+                continue;
+            const item = items.get(tile.tileId);
+            const binding = item?.filterBindings?.find((candidate) => candidate.filter === filter.id && candidate.capability !== 'unsupported');
+            if (!binding)
+                continue;
+            const requestedColumn = dashboardOutputColumn(binding?.binding ?? filter.field?.name ?? filter.bindsTo ?? filter.id);
+            if (!requestedColumn)
+                continue;
+            const safeColumn = tile.filterableColumns?.find((candidate) => normalizeDashboardOptionColumn(candidate.column) === normalizeDashboardOptionColumn(requestedColumn));
+            if (!safeColumn)
+                continue;
+            const resultColumn = result.columns.find((column) => normalizeDashboardOptionColumn(column) === normalizeDashboardOptionColumn(safeColumn.column));
+            if (!resultColumn)
+                continue;
+            sourceTileIds.push(tile.tileId);
+            for (const row of result.rows) {
+                const value = dashboardFilterOptionValue(row[resultColumn]);
+                if (value !== null)
+                    values.add(value);
+            }
+            if (result.truncated || (result.rowCount ?? result.rows.length) > result.rows.length)
+                truncated = true;
+        }
+        if (values.size === 0) {
+            if (dateControl) {
+                optionSets.push({
+                    filterId: filter.id,
+                    values: [],
+                    truncated,
+                    sourceTileIds: Array.from(new Set(sourceTileIds)),
+                    valueCount: 0,
+                });
+            }
+            continue;
+        }
+        const sorted = Array.from(values).sort((left, right) => left.localeCompare(right, undefined, { numeric: true, sensitivity: 'base' }));
+        const dateValues = dateControl
+            ? sorted
+                .map((value) => ({ value, timestamp: Date.parse(value) }))
+                .filter((item) => Number.isFinite(item.timestamp))
+                .sort((left, right) => left.timestamp - right.timestamp)
+            : [];
+        optionSets.push({
+            filterId: filter.id,
+            values: dateControl ? [] : sorted.slice(0, limit),
+            truncated: dateControl ? truncated : truncated || sorted.length > limit,
+            sourceTileIds: Array.from(new Set(sourceTileIds)),
+            ...(dateControl ? {
+                valueCount: dateValues.length,
+                ...(dateValues.length ? {
+                    dateRange: {
+                        min: new Date(dateValues[0].timestamp).toISOString().slice(0, 10),
+                        max: new Date(dateValues[dateValues.length - 1].timestamp).toISOString().slice(0, 10),
+                    },
+                } : {}),
+            } : {}),
+        });
+    }
+    return optionSets;
+}
+function dashboardFilterOptionResult(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!Array.isArray(record.columns) || !record.columns.every((column) => typeof column === 'string'))
+        return null;
+    if (!Array.isArray(record.rows) || !record.rows.every((row) => Boolean(row) && typeof row === 'object' && !Array.isArray(row)))
+        return null;
+    return {
+        columns: record.columns,
+        rows: record.rows,
+        ...(typeof record.rowCount === 'number' ? { rowCount: record.rowCount } : {}),
+        ...(typeof record.truncated === 'boolean' ? { truncated: record.truncated } : {}),
+    };
+}
+function normalizeDashboardOptionColumn(value) {
+    return value.replace(/[`"[\]]/g, '').trim().split('.').filter(Boolean).at(-1)?.toLowerCase() ?? '';
+}
+function dashboardFilterOptionValue(value) {
+    if (typeof value === 'string')
+        return value.trim() ? value : null;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return String(value);
+    if (typeof value === 'boolean')
+        return String(value);
+    if (value instanceof Date && Number.isFinite(value.getTime()))
+        return value.toISOString();
+    return null;
+}
 /**
  * Resolve only declared tile parameter bindings.  Dashboard filters remain
  * values; they never become SQL identifiers or an implicit name-based binding.
@@ -17212,6 +19088,10 @@ export function applyDashboardFiltersToBlockExecution(input) {
     const clauses = [];
     let nextPosition = sqlParams.reduce((max, param) => Math.max(max, param.position), 0);
     for (const filter of input.dashboard.filters ?? []) {
+        if (filter.scope?.tileIds && input.tileId && !filter.scope.tileIds.includes(input.tileId)) {
+            skippedFilters.push({ filter: filter.id, reason: 'component is outside this filter scope' });
+            continue;
+        }
         const value = dashboardFilterValue(filter, variables);
         if (isEmptyDashboardFilterValue(value)) {
             skippedFilters.push({ filter: filter.id, reason: 'no value supplied' });
@@ -17226,7 +19106,7 @@ export function applyDashboardFiltersToBlockExecution(input) {
             });
             continue;
         }
-        const binding = resolveDashboardFilterBinding(filter, input.block);
+        const binding = resolveDashboardFilterBinding(filter, input.block, input.tileFilterBindings);
         if (!binding) {
             skippedFilters.push({ filter: filter.id, reason: `block "${input.block.name}" does not declare a compatible filter binding` });
             continue;
@@ -17348,8 +19228,16 @@ function bindDashboardFilterToExistingParams(filter, value, block, sqlParams, va
     }
     return [];
 }
-function resolveDashboardFilterBinding(filter, block) {
+function resolveDashboardFilterBinding(filter, block, tileFilterBindings = []) {
     const candidates = uniqueDashboardStrings([filter.id, filter.bindsTo ?? '']).map(normalizeDashboardFilterName);
+    for (const entry of tileFilterBindings ?? []) {
+        const mode = entry.mode ?? (entry.binding ? 'predicate' : undefined);
+        if (mode === 'predicate'
+            && entry.binding
+            && !entry.unsupportedReason
+            && candidates.includes(normalizeDashboardFilterName(entry.filter)))
+            return entry.binding;
+    }
     for (const entry of block.filterBindings ?? []) {
         if (candidates.includes(normalizeDashboardFilterName(entry.filter)))
             return entry.binding;
@@ -17393,6 +19281,13 @@ function buildDashboardFilterPredicate(input) {
     const values = Array.isArray(input.value) ? input.value.filter((item) => !isEmptyDashboardFilterValue(item)) : [input.value];
     if (values.length === 0)
         return null;
+    if (input.filterType === 'search' && values.length === 1) {
+        const search = String(values[0] ?? '').trim();
+        if (!search)
+            return null;
+        const param = addDashboardFilterParam(input, 'contains', `%${search}%`);
+        return `LOWER(${input.expression}) LIKE LOWER($${param.position})`;
+    }
     if (values.length === 1) {
         const param = addDashboardFilterParam(input, 'value', values[0]);
         return `${input.expression} = $${param.position}`;
@@ -18815,6 +20710,22 @@ export function openBlockStudioDocument(projectRoot, relativePath, semanticLayer
         validation: validateBlockStudioSource(source, semanticLayer),
     };
 }
+const BLOCK_STUDIO_DRAFT_RUNTIME_DIAGNOSTICS = new Set([
+    'metricflow_unavailable',
+    'semantic_compose_failed',
+    'semantic_layer_missing',
+    'semantic_runtime_required',
+]);
+/**
+ * Draft persistence is stricter than loose text storage but does not require a
+ * configured execution runtime. Syntax, unsafe SQL, invalid semantic identity,
+ * and parameter-contract errors must be corrected before a block file is
+ * written; runtime availability remains a Run/Certify concern.
+ */
+export function blockStudioValidationAllowsDraftSave(validation) {
+    return !validation.diagnostics.some((diagnostic) => diagnostic.severity === 'error'
+        && !BLOCK_STUDIO_DRAFT_RUNTIME_DIAGNOSTICS.has(diagnostic.code ?? ''));
+}
 /**
  * Replace the CONTENTS of every string literal with same-length filler, keeping
  * the quotes and every offset intact.
@@ -19422,17 +21333,33 @@ export function validateBlockStudioSource(source, semanticLayer) {
             });
         }
     }
-    const parameterInvocation = prepareBlockInvocation({ source, surface: 'block_studio' });
-    if (parameterInvocation.errors.length > 0) {
-        diagnostics.push(...parameterInvocation.errors.map((message) => ({ severity: 'error', code: 'parameter_parse', message })));
+    let parameters = [];
+    try {
+        const parameterInvocation = prepareBlockInvocation({ source, surface: 'block_studio' });
+        parameters = parameterInvocation.parameters;
+        if (parameterInvocation.errors.length > 0) {
+            diagnostics.push(...parameterInvocation.errors.map((message) => ({ severity: 'error', code: 'parameter_parse', message })));
+        }
+    }
+    catch (error) {
+        // The main parser diagnostic above owns malformed source. Parameter
+        // extraction must never turn a recoverable validation response into a 500.
+        if (!diagnostics.some((diagnostic) => diagnostic.code === 'syntax')) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'parameter_parse',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
     }
     return {
         valid: diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
+        saveable: blockStudioValidationAllowsDraftSave({ diagnostics }),
         diagnostics,
         semanticRefs,
         chartConfig: chartConfig ?? undefined,
         executableSql,
-        parameters: parameterInvocation.parameters,
+        parameters,
     };
 }
 export async function createDqlArtifactGenerationSessionForProject(projectRoot, options, semanticLayer) {