@duckcodeailabs/dql-cli 1.6.33 → 1.6.34

package/dist/local-runtime.js

@@ -14,7 +14,7 @@ import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
 import { createDqlAgentProviderRunner } from './llm/providers/dql-agent-provider.js';
 import { listRemoteMcpSettings, saveRemoteMcpSettings } from './llm/mcp-config.js';
-import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, loadSkills, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
+import { ClaudeProvider, ConversationStore, advanceThreadState, buildConversationSnapshot, recallRelevantTurns, GeminiProvider, MemoryStore, OllamaProvider, OpenAIProvider, buildBlockBusinessFingerprint, buildBlockSqlFingerprints, buildLocalContextPack, defaultConversationPath, defaultMemoryPath, ensureDefaultMemoryFiles, ensureMetadataCatalogFresh, propose, proposePlan, recordCorrectionTrace, emitCorrectionEvalCase, mineJoinPatterns, reviewHint, AgentRunEngine, FileAgentRunStore, defaultAgentRunGates, createLlmAgentRunPlanner, createHybridRouter, computeResultStats, synthesizeAnswer, streamOrGenerate, narrateResult, normalizeAnthropicBaseUrl, buildProposePreview, buildFromPrompt, defaultAgentRunStorePath, resolveLocalOwner, resolveProposeConfig, recordQueryRun, recordRuntimeSchemaSnapshot, latestRuntimeSchemaSnapshotForProject, loadSkills, migrateLegacySkills, draftDomainSkillBootstrap, buildDomainSkillBootstrapPrompt, mergeDomainSkillBootstrapEnrichment, writeSkill, deleteSkill, deriveGeneratedDraftSlug, reindexProject, defaultKgPath, planApp, planResearch, loadSemanticMetrics, routeReasoningEffort, routeForCascadeAnswerTier, clampReasoningEffort, bumpReasoningEffort, resolveThinkingMode, coerceThinkingMode, probeLocalOllamaEmbeddings, upsertGeneratedDqlArtifactDraft, } from '@duckcodeailabs/dql-agent';
 import { gatherProposeEnrichment } from './propose-enrich.js';
 import { handleAppsApi, proposeAppAiBuild, recommendVisualization } from './apps-api.js';
 import { getActiveProvider, getEffectiveProviderConfig, isProviderSettingsId, listProviderSettings, saveProviderSettings, } from './settings/provider-settings.js';
@@ -145,6 +145,7 @@ export function parseAgentRunRequestBody(body) {
             runId: agentRunString(record.runId),
             reasoningEffort: parseAgentRunReasoningEffort(record.reasoningEffort),
             analysisDepth: parseAgentRunAnalysisDepth(record.analysisDepth) ?? parseAgentRunAnalysisDepth(record.depth),
+            thinkingMode: coerceThinkingMode(record.thinkingMode),
         },
     };
 }
@@ -325,6 +326,32 @@ export async function startLocalServer(opts) {
         }
         return candidate;
     };
+    // Zero-config semantic search: if the user is running Ollama with an embedding model
+    // but hasn't set an embed env var, auto-detect it so retrieval + metric/block matching
+    // get real semantic recall out of the box (match by meaning, not just keywords) — the
+    // biggest lever for "find the right metric/block instead of jumping to raw SQL".
+    // Explicit config always wins; when nothing is found we stay on the deterministic
+    // keyword matcher. Scoped to the app server (not eval/CI) and fully best-effort.
+    if (!process.env.DQL_OLLAMA_EMBED_URL && !process.env.DQL_OPENAI_API_KEY && !process.env.OPENAI_API_KEY) {
+        try {
+            const detected = await probeLocalOllamaEmbeddings();
+            if (detected) {
+                process.env.DQL_OLLAMA_EMBED_URL = detected.endpoint;
+                process.env.DQL_OLLAMA_EMBED_MODEL = detected.model;
+                console.log(`[dql] Semantic search on: local Ollama embeddings (${detected.model}) — matching by meaning, not just keywords.`);
+            }
+            else {
+                console.log('[dql] Semantic search: keyword-only. For higher matching accuracy, install Ollama and run `ollama pull nomic-embed-text` — DQL detects and uses it automatically, fully local & free.');
+            }
+        }
+        catch {
+            // Probe failure never blocks startup — fall back to the keyword matcher.
+        }
+    }
+    // Auto-ensure the active connection's driver so a configured connection is never
+    // left "broken" after a fresh clone, a CLI upgrade, or a Node version change (the
+    // driver lives in gitignored, per-project .dql/connectors). Best-effort + non-fatal.
+    ensureConnectorInstalledForStartup(projectRoot, connection?.driver);
     // Load semantic layer via provider system (dql native, dbt, cubejs, etc.)
     let semanticLayer;
     let semanticLayerErrors = [];
@@ -549,7 +576,7 @@ export async function startLocalServer(opts) {
             return provider.generate([{ role: 'system', content: system }, { role: 'user', content: user }], { maxTokens: 600, temperature: 0.2, signal });
         },
     });
-    async function runGovernedAgentAnswerForRun(request, repair, route = 'generated_answer') {
+    async function runGovernedAgentAnswerForRun(request, repair, route = 'generated_answer', onProgress) {
         const governed = resolveGovernedAnswerRunner(projectRoot);
         const resolvedProvider = governed?.provider ?? null;
         const runner = governed?.runner ?? null;
@@ -559,10 +586,16 @@ export async function startLocalServer(opts) {
         let governedAnswer;
         let providerError;
         const isRepair = (repair?.attempt ?? 0) > 0 && Boolean(repair?.repairHint);
-        const reasoningEffort = request.reasoningEffort
-            ? resolveRequestedRunReasoningEffort(projectRoot, resolvedProvider, request.reasoningEffort, isRepair)
+        // The chat composer sends a `thinkingMode` (auto/low/medium/high); resolve it
+        // into the effort+depth bundle it stands for. An explicit `reasoningEffort` /
+        // `analysisDepth` on the request (e.g. a CLI flag) still wins over the mode.
+        const thinkingResolved = request.thinkingMode ? resolveThinkingMode(request.thinkingMode) : {};
+        const requestedEffort = request.reasoningEffort ?? thinkingResolved.reasoningEffort;
+        const requestedDepth = request.analysisDepth ?? thinkingResolved.analysisDepth;
+        const reasoningEffort = requestedEffort
+            ? resolveRequestedRunReasoningEffort(projectRoot, resolvedProvider, requestedEffort, isRepair)
             : resolveRunReasoningEffort(projectRoot, resolvedProvider, route, isRepair);
-        const analysisDepth = request.analysisDepth ?? (route === 'research' ? 'deep' : undefined);
+        const analysisDepth = requestedDepth ?? (route === 'research' ? 'deep' : undefined);
         const contextEnvelope = {
             mode: 'agent_run',
             selectedObject: request.selectedObject,
@@ -575,7 +608,9 @@ export async function startLocalServer(opts) {
                 ...(isRepair ? [`This is a repair attempt — fix the previous failure: ${repair?.repairHint}`] : []),
             ].join(' '),
         };
-        const controller = new AbortController();
+        const controller = request.runId
+            ? activeAgentRunControllers.get(request.runId) ?? new AbortController()
+            : new AbortController();
         // Best-effort active warehouse dialect so Lane-2 semantic compiles emit
         // dialect-correct SQL (e.g. DATE_TRUNC / identifier quoting). Absent when no
         // connection is configured — the compiler then uses its default dialect.
@@ -605,6 +640,8 @@ export async function startLocalServer(opts) {
             executeGeneratedSql: executeGeneratedSqlForAgent,
             getSchemaContext: getSchemaContextForAgent,
         }, (turn) => {
+            if (turn.kind === 'thinking')
+                onProgress?.(turn.text);
             if (turn.kind === 'tool_result' && turn.id === 'governed_answer') {
                 governedAnswer = turn.output;
             }
@@ -633,15 +670,82 @@ export async function startLocalServer(opts) {
         ].filter((token) => Boolean(token));
         return tokens.length > 0 ? tokens.join('; ') : governedAnswer.text;
     }
-    const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emitAnswerDelta }) => {
+    /**
+     * The model picks a visualization while composing the answer, but only the
+     * executed rows know whether that choice is viable. Preserve an authored DQL
+     * chart; otherwise validate the model preference against the actual result and
+     * attach a compact, explainable display contract for every consumer.
+     */
+    function applySmartVisualization(governedAnswer, question) {
+        const result = governedAnswer.result;
+        if (!result || !Array.isArray(result.rows))
+            return;
+        const rows = result.rows.filter((row) => Boolean(agentRunRecord(row)));
+        const columns = Array.isArray(result.columns)
+            ? result.columns.map((column) => typeof column === 'string'
+                ? column
+                : agentRunString(agentRunRecord(column)?.name) ?? String(column))
+            : (rows.length > 0 ? Object.keys(rows[0]) : []);
+        if (rows.length === 0 || columns.length === 0)
+            return;
+        const existing = agentRunRecord(result.chartConfig) ?? {};
+        // A declared chart on the execution result came from authored DQL and is a
+        // governed display contract. Agent `suggestedViz` remains a soft preference.
+        if (typeof existing.chart === 'string')
+            return;
+        const recommendation = recommendVisualization(projectRoot, {
+            blockRef: governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name,
+            prompt: question,
+            resultSchema: columns,
+            rowSample: rows.slice(0, 25),
+            defaultVisualization: governedAnswer.suggestedViz,
+        });
+        if (!recommendation.ok)
+            return;
+        const fieldHints = recommendation.display.fieldHints ?? {};
+        const chart = recommendation.display.defaultVisualization.replace(/_/g, '-');
+        const agentChoice = typeof governedAnswer.suggestedViz === 'string'
+            ? governedAnswer.suggestedViz.toLowerCase().replace(/_/g, '-')
+            : undefined;
+        result.chartConfig = {
+            ...existing,
+            chart,
+            decisionSource: agentChoice === chart ? 'agent' : 'data',
+            rationale: recommendation.display.rationale,
+            ...(typeof fieldHints.x === 'string' ? { x: fieldHints.x } : {}),
+            ...(typeof fieldHints.y === 'string' ? { y: fieldHints.y } : {}),
+        };
+        governedAnswer.suggestedViz = chart;
+        const evidence = governedAnswer.evidence ?? {
+            route: [],
+            lineage: [],
+            businessContext: [],
+            selectedAssets: [],
+            sourceTables: [],
+            semanticObjects: [],
+            citations: [],
+        };
+        governedAnswer.evidence = evidence;
+        evidence.route = [
+            ...evidence.route,
+            {
+                tool: 'recommend_visualization',
+                status: 'selected',
+                label: `Smart visualization: ${chart.replace(/-/g, ' ')}`,
+                detail: recommendation.display.rationale,
+            },
+        ];
+    }
+    const answerRunExecutor = async ({ request, route, routeDecision, attempt, repairHint, emit, emitAnswerDelta }) => {
         let governedAnswer;
         try {
-            governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route);
+            governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt, repairHint }, route, (message) => emit({ type: 'executor.started', message, route }));
             // Surface the approved Hint-Graph corrections that shaped this answer so the
             // UI can show an "applied learnings" chip (memoryContext is already on the answer).
             if (!governedAnswer.appliedHints) {
                 governedAnswer.appliedHints = governedAnswer.contextPack?.appliedHints;
             }
+            applySmartVisualization(governedAnswer, request.question);
         }
         catch (error) {
             const message = formatAgentRunInfrastructureError(error, 'AI answer provider');
@@ -662,12 +766,24 @@ export async function startLocalServer(opts) {
         }
         const resolvedRoute = resolvedRunRouteFromAnswer(governedAnswer) ?? route;
         const isCertified = governedAnswer.certification === 'certified' || governedAnswer.kind === 'certified';
+        const isSemantic = governedAnswer.route?.tier === 'semantic_metric';
         const isGroundingGap = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'grounding_gap';
         const isProviderError = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'provider_error';
+        // The model tried to compose a governed query and declined despite having usable
+        // context (e.g. it wasn't confident about a multi-table join). That is NOT a
+        // question for the USER to clarify — it's a case to retry harder: escalate to a
+        // deeper research pass (higher reasoning effort + deep analysis) through the
+        // engine's bounded loop, exactly as a grounding gap is retried today.
+        const isModelDeclined = governedAnswer.kind === 'no_answer' && governedAnswer.refusalCode === 'model_declined';
         const groundingRepairHint = isGroundingGap ? groundingGapRepairHint(governedAnswer) : undefined;
-        // A provider outage is a retryable infrastructure failure, not a question the
-        // user needs to clarify — surface it as blocked so the UI offers a retry.
-        const needsClarification = governedAnswer.kind === 'no_answer' && !isGroundingGap && !isProviderError;
+        const declinedRepairHint = isModelDeclined
+            ? 'The first attempt declined to compose a governed query despite available context. Investigate the join path across the requested entities/metrics and compose a review-required query rather than declining.'
+            : undefined;
+        // Only a genuinely AMBIGUOUS question is surfaced as "needs clarification". A
+        // grounding gap or a model decline is retried/escalated by the engine, and a
+        // provider outage is surfaced as blocked so the UI offers a retry.
+        const needsClarification = governedAnswer.kind === 'no_answer'
+            && !isGroundingGap && !isProviderError && !isModelDeclined;
         const sql = governedAnswer.proposedSql ?? governedAnswer.sql;
         const runnableSql = governedAnswer.kind === 'no_answer' ? undefined : sql;
         // Synthesis is a legacy polish pass. Certified/no-answer paths and lanes
@@ -700,9 +816,31 @@ export async function startLocalServer(opts) {
                 synthesizedAnswer = undefined;
             }
         }
-        const status = isProviderError ? 'blocked' : needsClarification ? 'needs_clarification' : isCertified ? 'completed' : 'needs_review';
-        const trustState = isProviderError ? 'blocked' : needsClarification ? 'not_applicable' : isCertified ? 'certified' : 'review_required';
-        const stopReason = isProviderError ? 'blocked' : needsClarification ? 'needs_clarification' : isCertified ? 'certified_answer_found' : 'human_review_required';
+        const status = isProviderError
+            ? 'blocked'
+            : needsClarification
+                ? 'needs_clarification'
+                : isCertified || isSemantic
+                    ? 'completed'
+                    : 'needs_review';
+        const trustState = isProviderError
+            ? 'blocked'
+            : needsClarification
+                ? 'not_applicable'
+                : isCertified
+                    ? 'certified'
+                    : isSemantic
+                        ? 'governed'
+                        : 'review_required';
+        const stopReason = isProviderError
+            ? 'blocked'
+            : needsClarification
+                ? 'needs_clarification'
+                : isCertified
+                    ? 'certified_answer_found'
+                    : isSemantic
+                        ? 'governed_semantic_answer'
+                        : 'human_review_required';
         const nextActions = needsClarification
             ? [{ id: 'clarify', label: 'Clarify question', route: 'generated_answer' }]
             : [
@@ -712,6 +850,7 @@ export async function startLocalServer(opts) {
             ];
         return {
             resolvedRoute,
+            answerRefusalCode: governedAnswer.kind === 'no_answer' ? governedAnswer.refusalCode : undefined,
             answerTier: governedAnswer.route?.tier,
             summary: governedAnswer.route?.label ?? (isCertified ? 'Answered from certified DQL context.' : 'Answered with review-required generated analysis.'),
             answer: synthesizedAnswer ?? governedAnswer.answer ?? governedAnswer.text,
@@ -725,18 +864,20 @@ export async function startLocalServer(opts) {
                 ? (governedAnswer.dqlArtifact && !isProviderError
                     ? [agentRunArtifact('dql_block_draft', 'DQL draft (review required)', governedAnswer.dqlArtifact, undefined, 'review_required')]
                     : [])
-                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : 'review_required')],
+                : [agentRunArtifact('answer', isCertified ? 'Certified answer' : isSemantic ? 'Governed semantic answer' : 'Review-required answer', governedAnswer, governedAnswer.sourceCertifiedBlock ?? governedAnswer.block?.name, isCertified ? 'certified' : isSemantic ? 'governed' : 'review_required')],
             evaluations: [
                 agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to governed answer.', {
                     plannedRoute: route,
                     resolvedRoute,
                     aiRoute: governedAnswer.route,
                 }),
-                agentRunEvaluation('trust-boundary', 'Trust boundary', isCertified, isCertified ? 'info' : 'warning', isCertified
+                agentRunEvaluation('trust-boundary', 'Trust boundary', isCertified || isSemantic, isCertified || isSemantic ? 'info' : 'warning', isCertified
                     ? 'The answer came from certified DQL context.'
-                    : needsClarification
-                        ? 'The answer loop needs more context before producing a governed answer.'
-                        : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
+                    : isSemantic
+                        ? 'The answer was compiled and executed from governed semantic definitions; it is not a human-certified reusable block.'
+                        : needsClarification
+                            ? 'The answer loop needs more context before producing a governed answer.'
+                            : 'The answer is generated or semantic-layer backed and remains review-required.', governedAnswer.route),
                 ...(isGroundingGap ? [
                     {
                         ...agentRunEvaluation('grounding-gap', 'Metadata grounding', false, 'warning', 'The answer loop found a metadata grounding gap that can be retried with wider context.', {
@@ -749,6 +890,18 @@ export async function startLocalServer(opts) {
                         repairAction: { kind: 'retry', hint: groundingRepairHint },
                     },
                 ] : []),
+                ...(isModelDeclined ? [
+                    {
+                        ...agentRunEvaluation('declined-despite-context', 'Answer grounding', false, 'blocking', 'The model declined to compose a governed query despite available context — escalating to a deeper investigation before accepting a refusal.', {
+                            refusalCode: governedAnswer.refusalCode,
+                            refusalDetails: governedAnswer.refusalDetails,
+                            validationWarnings: governedAnswer.validationWarnings,
+                            route: governedAnswer.route,
+                        }),
+                        suggestedRepair: declinedRepairHint,
+                        repairAction: { kind: 'escalate', route: 'research', hint: declinedRepairHint },
+                    },
+                ] : []),
                 ...(governedAnswer.executionError ? [
                     agentRunEvaluation('execution-error', 'Execution error', false, 'warning', governedAnswer.executionError),
                 ] : []),
@@ -808,6 +961,7 @@ export async function startLocalServer(opts) {
     const agentRunExecutors = {
         conversation: conversationRunExecutor,
         certified_answer: answerRunExecutor,
+        semantic_answer: answerRunExecutor,
         generated_answer: answerRunExecutor,
         research: async (researchContext) => {
             const { runId, request, routeDecision, emit } = researchContext;
@@ -984,10 +1138,26 @@ export async function startLocalServer(opts) {
             };
         },
         sql_cell: async ({ request, routeDecision, attempt, repairHint }) => {
-            const result = await buildAgentPromptArtifact(request, 'cell', { attempt, repairHint });
+            // P4: route Notebook SQL-cell generation through the SAME tool-rich governed
+            // pipeline Ask AI uses (schema-discovery tools P3 + declined-retry P1 + budget
+            // recovery P2), instead of the tool-less buildFromPrompt path. A SQL cell only
+            // needs the SQL, which the governed answer produces directly as proposedSql.
+            const governedAnswer = await runGovernedAgentAnswerForRun(request, { attempt: attempt ?? 0, repairHint });
+            const sql = governedAnswer.proposedSql ?? governedAnswer.sql ?? '';
+            const explanation = governedAnswer.answer ?? governedAnswer.text;
+            const hasSql = Boolean(sql.trim());
+            // Preserve the BuildCellResult shape the notebook UI already consumes.
+            const result = {
+                target: 'cell',
+                sql,
+                explanation,
+                ...(governedAnswer.appliedSkills ? { appliedSkills: governedAnswer.appliedSkills } : {}),
+            };
             return {
-                summary: 'Created a review-required SQL cell draft.',
-                answer: result.target === 'cell' ? result.explanation : undefined,
+                summary: hasSql
+                    ? 'Created a review-required SQL cell draft.'
+                    : (explanation || 'No SQL could be generated for this request.'),
+                answer: explanation,
                 artifacts: [agentRunArtifact('sql_cell', 'Generated SQL cell', result)],
                 evaluations: [
                     agentRunEvaluation('route-decision', 'Route decision', true, 'info', routeDecision?.reason ?? 'Routed request to SQL cell generation.'),
@@ -1055,6 +1225,15 @@ export async function startLocalServer(opts) {
                     ],
                 };
             }
+            // P4 (partial): a direct "build a block from a cold prompt" still uses the
+            // tool-less buildFromPrompt path. Unlike a SQL cell, a block needs SQL→DQL-block
+            // CONSTRUCTION (name, outputs, grain, certifier verdict, reflection), which
+            // buildFromPrompt owns — routing this through answer() cleanly requires driving
+            // that construction from the tool-rich pipeline (thread captureGeneratedDraft
+            // through the governed answer), a larger change deferred to its own session.
+            // NOTE: the two-step "ask a question → Create DQL draft" flow ALREADY routes
+            // block creation through the tool-rich governed pipeline via the carried-artifact
+            // branch above, so only this cold-start direct-build case remains tool-less.
             const result = await buildAgentPromptArtifact(request, 'block', { attempt, repairHint });
             const ready = result.target === 'block' ? result.certifierVerdict.ready : false;
             return {
@@ -1222,6 +1401,9 @@ export async function startLocalServer(opts) {
         getCatalogContext: () => buildAgentRunCatalogContext(),
     });
     const agentRunStore = new FileAgentRunStore({ path: defaultAgentRunStorePath(projectRoot) });
+    // A run may outlive its streaming browser connection, so cancellation is
+    // server-owned and keyed by run id rather than relying on fetch abort alone.
+    const activeAgentRunControllers = new Map();
     // Server-side conversation threads: persisted multi-turn state (survives refresh).
     // Lazy so a failed native-sqlite load never blocks the runtime; conversation
     // persistence degrades to the per-request context instead.
@@ -1400,7 +1582,7 @@ export async function startLocalServer(opts) {
             sql: prepared.sql,
         };
     };
-    const getSchemaContextForAgent = async (question) => {
+    const getSchemaContextForAgent = async (question, preparedContextPack) => {
         const scanRuntimeSchema = async () => {
             if (!connection)
                 return { ranked: [], snapshot: [] };
@@ -1414,11 +1596,14 @@ export async function startLocalServer(opts) {
                 snapshot: buildAgentSchemaContext(question, result.rows, { includeUnscored: true, limit: 500 }),
             };
         };
-        const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question).catch(() => []);
+        const catalogContext = await buildAgentSchemaContextFromCatalog(projectRoot, question, preparedContextPack).catch(() => []);
         if (catalogContext.length > 0) {
             if (!connection)
                 return catalogContext;
-            const runtimeScan = shouldAugmentAgentRuntimeSchema(question)
+            // Rescan live when the question shape calls for it OR the stored snapshot is
+            // stale/absent (P6) — otherwise a warehouse schema change between sessions is
+            // silently reasoned over from a cached snapshot that never expires.
+            const runtimeScan = (shouldAugmentAgentRuntimeSchema(question) || runtimeSnapshotStale(projectRoot))
                 ? await scanRuntimeSchema().catch(() => undefined)
                 : undefined;
             const runtimeContext = runtimeScan?.ranked ?? [];
@@ -2321,6 +2506,8 @@ export async function startLocalServer(opts) {
             owner: typeof body.owner === 'string' ? body.owner : undefined,
             tags: Array.isArray(body.tags) ? body.tags.map(String) : undefined,
             provider: typeof body.provider === 'string' ? body.provider : undefined,
+            async: body.async === true,
+            persistence: body.persistence === 'session-only' || body.persistence === 'draft-files' ? body.persistence : undefined,
         }, semanticLayer);
     };
     const loadDqlGenerationSession = (importId) => {
@@ -2470,6 +2657,20 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON({ runs, total: agentRunStore.list().length, limit }));
             return;
         }
+        if (req.method === 'POST' && /^\/api\/agent-runs\/[^/]+\/cancel$/.test(path)) {
+            const match = path.match(/^\/api\/agent-runs\/([^/]+)\/cancel$/);
+            const id = decodeURIComponent(match?.[1] ?? '');
+            const controller = activeAgentRunControllers.get(id);
+            if (!controller) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: 'This run is no longer active.' }));
+                return;
+            }
+            controller.abort(new Error('Stopped by user.'));
+            res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ ok: true, id }));
+            return;
+        }
         if (req.method === 'POST' && path === '/api/agent-runs') {
             try {
                 const body = await readJSON(req).catch(() => null);
@@ -2489,27 +2690,36 @@ export async function startLocalServer(opts) {
                     parsed.request.conversationContext = await conversationContextFromThread(conversationStore, parsed.request.threadId, parsed.request.conversationContext, parsed.request.question);
                 }
                 const wantsStream = url.searchParams.get('stream') === '1' || url.searchParams.get('stream') === 'true';
-                if (wantsStream) {
-                    res.writeHead(200, {
-                        'Content-Type': 'text/event-stream; charset=utf-8',
-                        'Cache-Control': 'no-cache',
-                        'Connection': 'keep-alive',
-                        'X-Accel-Buffering': 'no',
-                    });
-                    const run = await agentRunEngine.run(parsed.request, (event) => {
-                        writeAgentRunSse(res, 'agent-run-event', event);
-                    }, (delta) => {
-                        writeAgentRunSse(res, 'agent-run-answer-delta', { runId: parsed.request.runId, delta });
-                    });
+                const runId = parsed.request.runId;
+                if (runId)
+                    activeAgentRunControllers.set(runId, new AbortController());
+                try {
+                    if (wantsStream) {
+                        res.writeHead(200, {
+                            'Content-Type': 'text/event-stream; charset=utf-8',
+                            'Cache-Control': 'no-cache',
+                            'Connection': 'keep-alive',
+                            'X-Accel-Buffering': 'no',
+                        });
+                        const run = await agentRunEngine.run(parsed.request, (event) => {
+                            writeAgentRunSse(res, 'agent-run-event', event);
+                        }, (delta) => {
+                            writeAgentRunSse(res, 'agent-run-answer-delta', { runId: parsed.request.runId, delta });
+                        });
+                        recordConversationTurn(conversationStore, parsed.request.threadId, run);
+                        writeAgentRunSse(res, 'agent-run-complete', run);
+                        res.end();
+                        return;
+                    }
+                    const run = await agentRunEngine.run(parsed.request);
                     recordConversationTurn(conversationStore, parsed.request.threadId, run);
-                    writeAgentRunSse(res, 'agent-run-complete', run);
-                    res.end();
-                    return;
+                    res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ run }));
+                }
+                finally {
+                    if (runId)
+                        activeAgentRunControllers.delete(runId);
                 }
-                const run = await agentRunEngine.run(parsed.request);
-                recordConversationTurn(conversationStore, parsed.request.threadId, run);
-                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ run }));
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -2919,7 +3129,9 @@ export async function startLocalServer(opts) {
         //    are shared; PERSONAL skills (user set) are user-bound. ────────────────
         if (req.method === 'GET' && path === '/api/skills') {
             try {
-                const skills = loadSkills(projectRoot).skills.map(serializeSkill);
+                const skills = loadSkills(projectRoot).skills
+                    .filter((skill) => skill.scope === 'project')
+                    .map(serializeSkill);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ skills }));
             }
@@ -2932,16 +3144,20 @@ export async function startLocalServer(opts) {
         // Form pickers: metrics from the semantic layer + certified block ids.
         if (req.method === 'GET' && path === '/api/skills/options') {
             try {
+                const query = (url.searchParams.get('q') ?? '').trim().toLowerCase();
+                const limit = Math.min(50, Math.max(1, Number(url.searchParams.get('limit') ?? 30) || 30));
+                const matches = (value) => !query || value.toLowerCase().includes(query);
                 const metrics = semanticLayer
-                    ? semanticLayer.listMetrics().map((m) => m.name).sort()
+                    ? semanticLayer.listMetrics().map((m) => m.name).filter(matches).sort().slice(0, limit)
                     : [];
                 const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
                 const blocks = Object.values(manifest.blocks)
                     .filter((b) => b.status === 'certified')
                     .map((b) => b.name)
+                    .filter(matches)
                     .sort();
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ metrics, blocks }));
+                res.end(serializeJSON({ metrics, blocks: blocks.slice(0, limit) }));
             }
             catch (error) {
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -3076,6 +3292,117 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        // ── Domain + Skill bootstrap — evidence-first, session-only until save. ──
+        if (req.method === 'POST' && path === '/api/context-bootstrap') {
+            try {
+                const body = (await readJSON(req).catch(() => ({})));
+                const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+                const existingSkills = new Set(loadSkills(projectRoot).skills.map((skill) => skill.id));
+                const candidates = draftDomainSkillBootstrap(manifest).map((candidate) => (candidate.kind === 'skill' && candidate.skill && existingSkills.has(candidate.skill.id)
+                    ? { ...candidate, action: 'unchanged', evidence: [...candidate.evidence, 'Existing skill preserved'] }
+                    : candidate));
+                const session = writeContextBootstrapSession(projectRoot, {
+                    candidates,
+                    status: 'queued',
+                    ai: { requested: body.ai !== false, mode: 'pending' },
+                    progress: bootstrapProgress(candidates, new Set(), 4, 'Queued repository inventory for domain and skill drafts…', ['Draft session created.']),
+                });
+                void enrichContextBootstrapSession(projectRoot, session.id).catch((error) => {
+                    updateContextBootstrapSession(projectRoot, session.id, (current) => ({
+                        ...current,
+                        status: 'needs_attention',
+                        progress: bootstrapProgress(current.candidates, new Set(), 100, 'Repository draft is ready, but AI enrichment could not start.', [...current.progress.events, 'AI enrichment could not start.']),
+                        warnings: [...(current.warnings ?? []), `AI enrichment could not start: ${error instanceof Error ? error.message : String(error)}`],
+                    }));
+                });
+                res.writeHead(202, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(session));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/context-bootstrap/latest') {
+            try {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ session: latestOpenContextBootstrapSession(projectRoot) }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/context-bootstrap/')) {
+            try {
+                const id = decodeURIComponent(path.slice('/api/context-bootstrap/'.length));
+                const session = readContextBootstrapSession(projectRoot, id);
+                if (!session) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Bootstrap session not found.' }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(session));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && /^\/api\/context-bootstrap\/[^/]+\/save-selected$/.test(path)) {
+            try {
+                const match = path.match(/^\/api\/context-bootstrap\/([^/]+)\/save-selected$/);
+                const id = decodeURIComponent(match?.[1] ?? '');
+                const session = readContextBootstrapSession(projectRoot, id);
+                if (!session)
+                    throw new Error('Bootstrap session not found.');
+                if (!['ready', 'needs_attention'].includes(session.status)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Wait for the repository draft to finish before saving selected candidates.' }));
+                    return;
+                }
+                const body = (await readJSON(req).catch(() => ({})));
+                const selected = new Set(Array.isArray(body.candidateIds) ? body.candidateIds.filter((value) => typeof value === 'string') : []);
+                const saved = [];
+                for (const candidate of session.candidates) {
+                    if (!selected.has(candidate.id))
+                        continue;
+                    if (candidate.action === 'unchanged') {
+                        saved.push({ id: candidate.id, status: 'skipped' });
+                        continue;
+                    }
+                    try {
+                        if (candidate.kind === 'domain' && candidate.domain) {
+                            const written = writeDomainDeclaration(projectRoot, candidate.domain);
+                            saved.push({ id: candidate.id, path: written.path, status: 'saved' });
+                        }
+                        else if (candidate.kind === 'skill' && candidate.skill) {
+                            const skill = writeSkill(projectRoot, { ...candidate.skill, scope: 'project', status: 'draft' });
+                            saved.push({ id: candidate.id, path: relative(projectRoot, skill.sourcePath), status: 'saved' });
+                        }
+                        else {
+                            saved.push({ id: candidate.id, status: 'blocked', blockers: ['Candidate has no writable artifact.'] });
+                        }
+                    }
+                    catch (error) {
+                        saved.push({ id: candidate.id, status: 'blocked', blockers: [error instanceof Error ? error.message : String(error)] });
+                    }
+                }
+                await refreshLocalMetadataCatalog(projectRoot);
+                updateContextBootstrapSession(projectRoot, id, (current) => ({ ...current, closedAt: new Date().toISOString() }));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ id, saved }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         if (req.method === 'GET' && path === '/favicon.ico') {
             res.writeHead(200, {
                 'Content-Type': 'image/svg+xml',
@@ -3456,6 +3783,14 @@ export async function startLocalServer(opts) {
                     reviewHint(projectRoot, { hintId: hint.id, decision: 'approved', reviewer: author ?? 'local', note: 'Self-approved (OSS single-user).' });
                     approvedHint = { ...hint, status: 'approved' };
                 }
+                // W4.3 — turn the correction into a durable regression eval case so the wrong
+                // answer can never silently return. Best-effort; never blocks the correction.
+                try {
+                    emitCorrectionEvalCase(projectRoot, { question, correctedSql });
+                }
+                catch {
+                    /* best-effort */
+                }
                 // Plain-language advisory memory mirroring the lesson, for transparency + recall.
                 try {
                     const memory = new MemoryStore(defaultMemoryPath(projectRoot));
@@ -4297,6 +4632,23 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON(await readGitRemote(projectRoot)));
             return;
         }
+        if (req.method === 'GET' && path === '/api/git/governed-context') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(await readGitGovernedContext(projectRoot)));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/governed-context/enable') {
+            try {
+                const result = await enableGitGovernedContextTracking(projectRoot);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
         if (req.method === 'POST' && path === '/api/git/stage') {
             try {
                 const body = (await readJSON(req));
@@ -4361,6 +4713,24 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        if (req.method === 'POST' && path === '/api/git/review') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitCreateReview(projectRoot, {
+                    paths: body.paths ?? [],
+                    title: body.title ?? '',
+                    body: body.body ?? '',
+                    base: body.base ?? 'main',
+                });
+                res.writeHead(result.ok ? 201 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
         if (req.method === 'POST' && path === '/api/git/pull') {
             try {
                 const result = await gitPull(projectRoot);
@@ -4471,13 +4841,13 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: 'name and content are required' }));
                     return;
                 }
+                // OSS keeps the save flow deliberately small: the person saving the
+                // reusable answer is accountable for it. Domain/description/tags are
+                // helpful defaults, but not reasons to send a single-user back to a
+                // review queue.
                 const missing = [];
                 if (!owner || !owner.trim())
                     missing.push('owner');
-                if (!domain || !domain.trim())
-                    missing.push('domain');
-                if (!description || !description.trim())
-                    missing.push('description');
                 if (missing.length > 0) {
                     res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({
@@ -4500,8 +4870,34 @@ export async function startLocalServer(opts) {
                     invariants,
                     gitMetadata: readGitMetadata(projectRoot),
                 });
+                // Save first, then certify against the same local runtime used for the
+                // answer. Passing blocks become certified immediately; anything that
+                // cannot prove itself remains a clearly labelled draft at this path.
+                setBlockStudioStatus(projectRoot, created.path, 'draft');
+                let source = readFileSync(join(projectRoot, created.path), 'utf-8');
+                let status = 'draft';
+                let blockers = [];
+                let certification;
+                try {
+                    const verdict = await certifyBlockStudioSource(source, created.path);
+                    blockers = Array.from(new Set(verdict.checklist.blockers));
+                    certification = {
+                        certified: verdict.certification.certified && blockers.length === 0,
+                        errors: verdict.certification.errors,
+                        warnings: verdict.certification.warnings,
+                    };
+                    if (certification.certified) {
+                        setBlockStudioStatus(projectRoot, created.path, 'certified');
+                        status = 'certified';
+                        source = readFileSync(join(projectRoot, created.path), 'utf-8');
+                    }
+                }
+                catch (error) {
+                    blockers = [error instanceof Error ? error.message : String(error)];
+                }
+                await refreshLocalMetadataCatalog(projectRoot);
                 res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON(created));
+                res.end(serializeJSON({ ...created, content: source, status, blockers, certification }));
             }
             catch (error) {
                 if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
@@ -4540,6 +4936,11 @@ export async function startLocalServer(opts) {
                                 const stat = statSync(filePath);
                                 // Quick regex parse for key block fields
                                 const nameMatch = /block\s+"([^"]+)"/.exec(source);
+                                // `domains/**/domain.dql` is a business-boundary declaration,
+                                // not a reusable block. Only a real block declaration belongs
+                                // in the Blocks library.
+                                if (!nameMatch)
+                                    continue;
                                 const domainMatch = /domain\s*=\s*"([^"]+)"/.exec(source);
                                 const statusMatch = /status\s*=\s*"([^"]+)"/.exec(source);
                                 const ownerMatch = /owner\s*=\s*"([^"]+)"/.exec(source);
@@ -5029,6 +5430,115 @@ export async function startLocalServer(opts) {
             }
             return;
         }
+        const aiImportSaveSelectedMatch = path.match(/^\/api\/block-studio\/ai-imports\/([^/]+)\/save-selected$/);
+        if (req.method === 'POST' && aiImportSaveSelectedMatch) {
+            const importId = decodeURIComponent(aiImportSaveSelectedMatch[1]);
+            try {
+                const body = await readJSON(req);
+                const candidateIds = Array.from(new Set(Array.isArray(body.candidateIds) ? body.candidateIds.map((value) => String(value)) : []));
+                const owner = typeof body.owner === 'string' ? body.owner.trim() : '';
+                if (candidateIds.length === 0 || !owner) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Select at least one candidate and provide an owner.' }));
+                    return;
+                }
+                const results = [];
+                for (const candidateId of candidateIds) {
+                    try {
+                        let candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
+                        if (candidate.reviewStatus === 'saved' && candidate.savedPath && existsSync(join(projectRoot, candidate.savedPath))) {
+                            results.push({
+                                candidateId,
+                                path: candidate.savedPath,
+                                status: 'certified',
+                                blockers: [],
+                                candidate: candidate,
+                                block: openBlockStudioDocument(projectRoot, candidate.savedPath, semanticLayer),
+                            });
+                            continue;
+                        }
+                        if (candidate.recommendedAction === 'reuse_existing') {
+                            results.push({
+                                candidateId,
+                                status: 'error',
+                                blockers: ['An equivalent governed block already exists. Open and reuse it instead of saving a duplicate.'],
+                                candidate: candidate,
+                            });
+                            continue;
+                        }
+                        candidate = updateBlockStudioImportCandidate(projectRoot, importId, candidateId, { owner });
+                        const readiness = validateImportCandidateForSave(candidate);
+                        const validationBlockers = readiness.errors;
+                        if (validationBlockers.length === 0) {
+                            const certifiedSource = setBlockStudioSourceStatus(readiness.candidate.dqlSource, 'certified');
+                            const certification = await certifyBlockStudioSource(certifiedSource, readiness.candidate.savedPath, { enterprise: false });
+                            const blockers = Array.from(new Set(certification.checklist.blockers));
+                            if (certification.certification.certified && blockers.length === 0) {
+                                const savedPath = saveBlockStudioArtifacts(projectRoot, {
+                                    currentPath: readiness.candidate.savedPath,
+                                    source: certifiedSource,
+                                    name: readiness.candidate.name,
+                                    domain: readiness.candidate.domain,
+                                    description: readiness.candidate.description,
+                                    owner,
+                                    tags: readiness.candidate.tags,
+                                    lineage: readiness.candidate.lineage.sourceTables,
+                                    importMeta: { importId, candidateId, sourceKind: readiness.candidate.sourceKind, sourcePath: readiness.candidate.sourcePath },
+                                });
+                                const savedCandidate = {
+                                    ...readiness.candidate,
+                                    dqlSource: certifiedSource,
+                                    reviewStatus: 'saved',
+                                    savedPath,
+                                    analysisStatus: 'ready',
+                                    validation: validateBlockStudioSource(certifiedSource, semanticLayer),
+                                    generationMode: readiness.candidate.generationMode ?? 'deterministic',
+                                    generationProvider: readiness.candidate.generationProvider ?? 'local-deterministic',
+                                    llmContext: readiness.candidate.llmContext ?? deterministicDqlGenerationContext(readiness.candidate, readiness.candidate.evidence ?? []),
+                                    evidence: readiness.candidate.evidence ?? [],
+                                    draftSave: { status: 'saved', path: savedPath, savedAt: new Date().toISOString() },
+                                };
+                                writeBlockStudioImportCandidate(projectRoot, importId, savedCandidate);
+                                results.push({ candidateId, path: savedPath, status: 'certified', blockers: [], candidate: savedCandidate, block: openBlockStudioDocument(projectRoot, savedPath, semanticLayer) });
+                                continue;
+                            }
+                            validationBlockers.push(...blockers);
+                        }
+                        const draftCandidate = saveDqlGenerationDraft(importId, {
+                            ...readiness.candidate,
+                            dqlSource: setBlockStudioSourceStatus(readiness.candidate.dqlSource, 'draft'),
+                            analysisStatus: 'needs_attention',
+                        });
+                        writeBlockStudioImportCandidate(projectRoot, importId, draftCandidate);
+                        results.push({
+                            candidateId,
+                            path: draftCandidate.savedPath,
+                            status: 'draft',
+                            blockers: Array.from(new Set(validationBlockers.length > 0 ? validationBlockers : ['Certification gates did not pass.'])),
+                            candidate: draftCandidate,
+                            block: draftCandidate.savedPath ? openBlockStudioDocument(projectRoot, draftCandidate.savedPath, semanticLayer) : undefined,
+                        });
+                    }
+                    catch (error) {
+                        results.push({
+                            candidateId,
+                            status: 'error',
+                            blockers: [],
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+                await refreshLocalMetadataCatalog(projectRoot);
+                const nextSession = loadDqlGenerationSession(importId);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: results.every((result) => result.status !== 'error'), session: nextSession, results }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
         const aiImportPathMatch = path.match(/^\/api\/block-studio\/ai-imports\/([^/]+)(?:\/candidates\/([^/]+)(?:\/(preview|certify))?)?$/);
         if (aiImportPathMatch) {
             const importId = decodeURIComponent(aiImportPathMatch[1]);
@@ -5065,9 +5575,20 @@ export async function startLocalServer(opts) {
                         llmContext: typeof body.llmContext === 'string' ? body.llmContext : undefined,
                     });
                     const validated = validateImportCandidate(candidate);
-                    const savedDraft = saveDqlGenerationDraft(importId, validated);
+                    const savedDraft = validated.draftSave?.status === 'pending' && !isDraftBlockPath(validated.savedPath)
+                        ? {
+                            ...validated,
+                            analysisStatus: 'ready',
+                            generationMode: validated.generationMode ?? 'deterministic',
+                            generationProvider: validated.generationProvider ?? 'local-deterministic',
+                            llmContext: validated.llmContext ?? deterministicDqlGenerationContext(validated, validated.evidence ?? []),
+                            evidence: validated.evidence ?? [],
+                            draftSave: { status: 'pending' },
+                        }
+                        : saveDqlGenerationDraft(importId, validated);
                     writeBlockStudioImportCandidate(projectRoot, importId, savedDraft);
-                    await refreshLocalMetadataCatalog(projectRoot);
+                    if (savedDraft.draftSave.status === 'saved')
+                        await refreshLocalMetadataCatalog(projectRoot);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(savedDraft));
                     return;
@@ -5075,11 +5596,22 @@ export async function startLocalServer(opts) {
                 if (req.method === 'POST' && candidateId && action === 'preview') {
                     const candidate = readBlockStudioImportCandidate(projectRoot, importId, candidateId);
                     const preview = await runBlockStudioPreviewSource(candidate.dqlSource);
-                    const next = saveDqlGenerationDraft(importId, {
+                    const previewed = {
                         ...candidate,
                         preview,
+                        analysisStatus: 'ready',
                         validation: validateBlockStudioSource(candidate.dqlSource, semanticLayer),
-                    });
+                    };
+                    const next = candidate.draftSave?.status === 'pending' && !isDraftBlockPath(candidate.savedPath)
+                        ? {
+                            ...previewed,
+                            generationMode: candidate.generationMode ?? 'deterministic',
+                            generationProvider: candidate.generationProvider ?? 'local-deterministic',
+                            llmContext: candidate.llmContext ?? deterministicDqlGenerationContext(candidate, candidate.evidence ?? []),
+                            evidence: candidate.evidence ?? [],
+                            draftSave: { status: 'pending' },
+                        }
+                        : saveDqlGenerationDraft(importId, previewed);
                     writeBlockStudioImportCandidate(projectRoot, importId, next);
                     res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON(next));
@@ -7474,13 +8006,24 @@ export function serializeJSON(value) {
 function serializeSkill(skill) {
     return {
         id: skill.id,
-        scope: skill.scope,
-        user: skill.user,
+        scope: 'project',
+        user: undefined,
         domain: skill.domain,
+        domains: skill.domains,
+        kind: skill.kind,
+        status: skill.status,
+        owner: skill.owner,
+        triggers: skill.triggers,
+        exclusions: skill.exclusions,
         description: skill.description,
         body: skill.body,
         preferredMetrics: skill.preferredMetrics,
         preferredBlocks: skill.preferredBlocks,
+        preferredDimensions: skill.preferredDimensions,
+        requiredFilters: skill.requiredFilters,
+        clarifyWhen: skill.clarifyWhen,
+        examples: skill.examples,
+        sourceRefs: skill.sourceRefs,
         vocabulary: skill.vocabulary,
         sourcePath: skill.sourcePath,
         isStarter: skill.isStarter,
@@ -7498,7 +8041,7 @@ function parseSkillInput(raw, fallbackId) {
     const id = typeof skill.id === 'string' && skill.id.trim() ? skill.id.trim() : fallbackId;
     if (!id)
         return null;
-    const scope = skill.scope === 'personal' ? 'personal' : skill.scope === 'project' ? 'project' : undefined;
+    const scope = skill.scope === 'project' ? 'project' : undefined;
     if (!scope)
         return null;
     if (typeof skill.body !== 'string')
@@ -7516,13 +8059,24 @@ function parseSkillInput(raw, fallbackId) {
     };
     return {
         id,
-        scope,
-        user: scope === 'personal' && typeof skill.user === 'string' ? skill.user : undefined,
+        scope: 'project',
+        user: undefined,
         domain: typeof skill.domain === 'string' && skill.domain.trim() ? skill.domain.trim() : undefined,
+        domains: asStrings(skill.domains),
+        kind: skill.kind === 'domain_reference' || skill.kind === 'metric_policy' || skill.kind === 'glossary' || skill.kind === 'analysis_pattern' || skill.kind === 'sql_policy' ? skill.kind : 'custom',
+        status: skill.status === 'draft' || skill.status === 'deprecated' ? skill.status : 'active',
+        owner: typeof skill.owner === 'string' ? skill.owner : undefined,
+        triggers: asStrings(skill.triggers),
+        exclusions: asStrings(skill.exclusions),
         description: typeof skill.description === 'string' ? skill.description : undefined,
         body: skill.body,
         preferredMetrics: asStrings(skill.preferredMetrics),
         preferredBlocks: asStrings(skill.preferredBlocks),
+        preferredDimensions: asStrings(skill.preferredDimensions),
+        requiredFilters: asStrings(skill.requiredFilters),
+        clarifyWhen: asStrings(skill.clarifyWhen),
+        examples: asStrings(skill.examples),
+        sourceRefs: asStrings(skill.sourceRefs),
         vocabulary: asMap(skill.vocabulary),
         isStarter: skill.isStarter === true ? true : undefined,
     };
@@ -7537,10 +8091,23 @@ function manifestDomainToDto(domain, counts) {
     return {
         id: domain.name,
         name: domain.name,
+        parent: domain.parent,
         owner: domain.owner,
+        businessOwner: domain.businessOwner,
         boundedContext: domain.boundedContext,
         sourceSystems: domain.sourceSystems,
         description: domain.description,
+        primaryTerms: domain.primaryTerms,
+        tags: domain.tags,
+        businessOutcome: domain.businessOutcome,
+        reviewCadence: domain.reviewCadence,
+        inScope: domain.inScope,
+        outOfScope: domain.outOfScope,
+        dbtGroups: domain.dbtGroups,
+        dbtPaths: domain.dbtPaths,
+        dbtTags: domain.dbtTags,
+        semanticDomains: domain.semanticDomains,
+        semanticTags: domain.semanticTags,
         sourcePath: domain.filePath,
         blockCount: counts.blockCount,
         skillCount: counts.skillCount,
@@ -7603,11 +8170,168 @@ export function parseDomainInput(raw, fallbackId) {
         : undefined;
     return {
         name,
+        parent: typeof domain.parent === 'string' ? domain.parent : undefined,
         owner: typeof domain.owner === 'string' ? domain.owner : undefined,
+        businessOwner: typeof domain.businessOwner === 'string' ? domain.businessOwner : undefined,
         boundedContext: typeof domain.boundedContext === 'string' ? domain.boundedContext : undefined,
         sourceSystems: asStrings(domain.sourceSystems),
         description: typeof domain.description === 'string' ? domain.description : undefined,
+        primaryTerms: asStrings(domain.primaryTerms),
+        tags: asStrings(domain.tags),
+        businessOutcome: typeof domain.businessOutcome === 'string' ? domain.businessOutcome : undefined,
+        reviewCadence: typeof domain.reviewCadence === 'string' ? domain.reviewCadence : undefined,
+        inScope: asStrings(domain.inScope),
+        outOfScope: asStrings(domain.outOfScope),
+        dbtGroups: asStrings(domain.dbtGroups),
+        dbtPaths: asStrings(domain.dbtPaths),
+        dbtTags: asStrings(domain.dbtTags),
+        semanticDomains: asStrings(domain.semanticDomains),
+        semanticTags: asStrings(domain.semanticTags),
+        sourcePath: typeof domain.sourcePath === 'string' ? domain.sourcePath : undefined,
+    };
+}
+function contextBootstrapDir(projectRoot) {
+    return join(projectRoot, '.dql', 'local', 'context-bootstrap');
+}
+function contextBootstrapPath(projectRoot, id) {
+    const safe = id.replace(/[^a-zA-Z0-9_-]/g, '');
+    return join(contextBootstrapDir(projectRoot), `${safe}.json`);
+}
+function writeContextBootstrapSession(projectRoot, input) {
+    const id = `ctx_${Date.now().toString(36)}_${createHash('sha1').update(JSON.stringify(input.candidates)).digest('hex').slice(0, 8)}`;
+    const session = { id, createdAt: new Date().toISOString(), persistence: 'session-only', ...input };
+    const dir = contextBootstrapDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(contextBootstrapPath(projectRoot, id), JSON.stringify(session, null, 2), 'utf-8');
+    return session;
+}
+function updateContextBootstrapSession(projectRoot, id, update) {
+    const current = readContextBootstrapSession(projectRoot, id);
+    if (!current)
+        return null;
+    const next = update(current);
+    writeFileSync(contextBootstrapPath(projectRoot, id), JSON.stringify(next, null, 2), 'utf-8');
+    return next;
+}
+function bootstrapProgress(candidates, readyCandidateIds, percent, message, events) {
+    const count = (kind) => {
+        const all = candidates.filter((candidate) => candidate.kind === kind);
+        return { total: all.length, ready: all.filter((candidate) => readyCandidateIds.has(candidate.id)).length };
     };
+    return { percent, message, domains: count('domain'), skills: count('skill'), events: events.slice(-6) };
+}
+async function enrichContextBootstrapSession(projectRoot, id) {
+    // One compiled snapshot serves the entire session; do not re-search a large
+    // repository for every domain/skill candidate.
+    const manifest = buildManifest({ projectRoot, dqlVersion: 'notebook' });
+    let session = updateContextBootstrapSession(projectRoot, id, (current) => ({
+        ...current,
+        status: 'inventory',
+        progress: bootstrapProgress(current.candidates, new Set(), 12, 'Repository inventory is ready. Checking the configured AI provider…', ['Repository inventory complete.']),
+    }));
+    if (!session)
+        return;
+    const provider = session.ai.requested ? await createBlockStudioAssistProvider(projectRoot) : null;
+    if (!provider) {
+        updateContextBootstrapSession(projectRoot, id, (current) => ({
+            ...current,
+            status: 'ready',
+            ai: { ...current.ai, mode: 'evidence_only' },
+            progress: bootstrapProgress(current.candidates, new Set(current.candidates.map((candidate) => candidate.id)), 100, 'Evidence-first draft is ready. Configure an AI provider to enrich its prose and guidance.', ['Repository inventory complete.', 'No configured AI provider was available; retained evidence-only drafts.']),
+            warnings: [...(current.warnings ?? []), 'No configured AI provider was available. Candidates were drafted from repository evidence only.'],
+        }));
+        return;
+    }
+    session = updateContextBootstrapSession(projectRoot, id, (current) => ({
+        ...current,
+        status: 'grounding',
+        ai: { ...current.ai, mode: 'provider', provider: provider.name },
+        progress: bootstrapProgress(current.candidates, new Set(), 25, `Grounding ${current.candidates.length} candidate(s) in governed repository metadata…`, ['Repository inventory complete.', `Using ${provider.name} to enrich bounded guidance.`]),
+    }));
+    if (!session)
+        return;
+    const chunks = [];
+    for (let index = 0; index < session.candidates.length; index += 4)
+        chunks.push(session.candidates.slice(index, index + 4));
+    const complete = new Set();
+    const warnings = [];
+    for (let index = 0; index < chunks.length; index += 1) {
+        const before = readContextBootstrapSession(projectRoot, id);
+        if (!before)
+            return;
+        updateContextBootstrapSession(projectRoot, id, (current) => ({
+            ...current,
+            status: 'generating',
+            progress: bootstrapProgress(current.candidates, complete, 25 + Math.floor((index / Math.max(chunks.length, 1)) * 60), `Writing grounded guidance for ${index * 4 + 1}–${Math.min((index + 1) * 4, current.candidates.length)} of ${current.candidates.length} candidates…`, [...current.progress.events, `AI enrichment batch ${index + 1} of ${chunks.length}.`]),
+        }));
+        const prompt = buildDomainSkillBootstrapPrompt(manifest, chunks[index]);
+        try {
+            const response = await provider.generate([
+                { role: 'system', content: prompt.system },
+                { role: 'user', content: prompt.user },
+            ], { maxTokens: 1800, temperature: 0.1 });
+            updateContextBootstrapSession(projectRoot, id, (current) => {
+                const candidateById = new Map(current.candidates.map((candidate) => [candidate.id, candidate]));
+                const currentChunk = chunks[index].map((candidate) => candidateById.get(candidate.id) ?? candidate);
+                const merged = mergeDomainSkillBootstrapEnrichment(currentChunk, response);
+                for (const candidate of merged.candidates)
+                    candidateById.set(candidate.id, candidate);
+                for (const candidate of chunks[index])
+                    complete.add(candidate.id);
+                warnings.push(...merged.rejected);
+                const candidates = current.candidates.map((candidate) => candidateById.get(candidate.id) ?? candidate);
+                return {
+                    ...current,
+                    candidates,
+                    progress: bootstrapProgress(candidates, complete, 25 + Math.floor(((index + 1) / Math.max(chunks.length, 1)) * 60), `Grounded guidance ready for ${complete.size} of ${candidates.length} candidates.`, [...current.progress.events, `AI enrichment batch ${index + 1} complete.`]),
+                };
+            });
+        }
+        catch (error) {
+            for (const candidate of chunks[index])
+                complete.add(candidate.id);
+            warnings.push(`AI enrichment batch ${index + 1} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    updateContextBootstrapSession(projectRoot, id, (current) => ({
+        ...current,
+        status: warnings.length ? 'needs_attention' : 'ready',
+        progress: bootstrapProgress(current.candidates, new Set(current.candidates.map((candidate) => candidate.id)), 100, warnings.length ? 'Drafts are ready; review the noted AI enrichment gaps before saving.' : 'Grounded domain and skill drafts are ready for review.', [...current.progress.events, warnings.length ? 'Some AI enrichment needs attention.' : 'Validation complete.']),
+        warnings: warnings.length ? [...(current.warnings ?? []), ...warnings] : current.warnings,
+    }));
+}
+function readContextBootstrapSession(projectRoot, id) {
+    const path = contextBootstrapPath(projectRoot, id);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return parsed?.id === id && Array.isArray(parsed.candidates) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function latestOpenContextBootstrapSession(projectRoot) {
+    const dir = contextBootstrapDir(projectRoot);
+    if (!existsSync(dir))
+        return null;
+    const paths = readdirSync(dir)
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => join(dir, name))
+        .sort((left, right) => statSync(right).mtimeMs - statSync(left).mtimeMs);
+    for (const path of paths) {
+        try {
+            const session = JSON.parse(readFileSync(path, 'utf-8'));
+            if (session?.id && Array.isArray(session.candidates) && !session.closedAt)
+                return session;
+        }
+        catch {
+            // A truncated local session should not hide an earlier valid session.
+        }
+    }
+    return null;
 }
 async function refreshLocalMetadataCatalog(projectRoot) {
     try {
@@ -7929,6 +8653,7 @@ export function buildSemanticCompostingChangeset(projectRoot, options = {}) {
                 minSupport: Math.max(2, Math.floor(options.minSupport ?? 2)),
             },
             candidates: [],
+            joinCandidates: [],
             prBody: '',
         };
     }
@@ -7995,6 +8720,8 @@ export function buildSemanticCompostingChangeset(projectRoot, options = {}) {
         .filter((candidate) => Boolean(candidate))
         .slice(0, limit);
     const donorBlocksUsed = new Set(candidates.flatMap((candidate) => candidate.donorBlocks.map((donor) => donor.path))).size;
+    // Composting v2 (W4.4) — recurring join shapes across certified blocks.
+    const joinCandidates = mineJoinPatterns(certifiedBlocks.map((block) => ({ name: block.name, sql: block.sql })), minSupport).slice(0, limit);
     return {
         ready: true,
         summary: {
@@ -8006,6 +8733,7 @@ export function buildSemanticCompostingChangeset(projectRoot, options = {}) {
             minSupport,
         },
         candidates,
+        joinCandidates,
         prBody: renderCompostingPrBody(candidates),
     };
 }
@@ -8513,6 +9241,37 @@ function installConnectorPackage(projectRoot, driver) {
     });
     return getConnectorInstallStatuses(projectRoot).find((status) => status.driver === definition.driver);
 }
+/**
+ * Ensure the active connection's driver package is present at startup.
+ *
+ * The connection CONFIG persists in dql.config.json, but the driver package
+ * (duckdb, snowflake-sdk, …) lives in the gitignored, per-project .dql/connectors
+ * — so a fresh clone, a `npm i -g` upgrade of the CLI, or even a Node version bump
+ * (native bindings are Node-version-specific) leaves a configured connection with
+ * no loadable driver, and the user has to reinstall it by hand from the Connections
+ * page. This installs it once, at boot, so connections just work after any
+ * install/upgrade. Best-effort and non-fatal: an offline machine keeps the manual
+ * "Install" button and a clear message rather than a failed startup.
+ */
+export function ensureConnectorInstalledForStartup(projectRoot, driver) {
+    if (!driver)
+        return;
+    const definition = CONNECTOR_INSTALLS[driver];
+    // Built-in drivers (e.g. the local file driver) and unknown drivers need nothing.
+    if (!definition || definition.builtIn || !definition.packageSpec || !definition.packageName)
+        return;
+    if (isConnectorPackageInstalled(projectRoot, definition.packageName))
+        return;
+    console.log(`[dql] Installing the ${definition.label} driver into .dql/connectors (first run after install/upgrade)…`);
+    try {
+        installConnectorPackage(projectRoot, driver);
+        console.log(`[dql] ${definition.label} driver ready — connection restored without manual setup.`);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        console.log(`[dql] Could not auto-install the ${definition.label} driver (${detail}). Open the Connections page and click "Install" once you have network access.`);
+    }
+}
 function getStoredConnections(raw) {
     const value = raw.connections;
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -9942,9 +10701,6 @@ export async function createDqlArtifactGenerationSessionForProject(projectRoot,
     return session;
 }
 export async function createDqlGenerationSessionForProject(projectRoot, options, semanticLayer) {
-    const deterministicOnly = isDeterministicDqlGenerationProvider(options.provider);
-    const requestedProvider = !deterministicOnly && isProviderSettingsId(options.provider) ? options.provider : undefined;
-    const provider = deterministicOnly ? null : await createBlockStudioAssistProvider(projectRoot, requestedProvider);
     const session = createBlockStudioImportSession(projectRoot, {
         inputPath: options.inputPath ?? '',
         inputMode: options.inputMode,
@@ -9954,77 +10710,183 @@ export async function createDqlGenerationSessionForProject(projectRoot, options,
         owner: options.owner,
         tags: options.tags,
     });
+    const persistence = options.persistence ?? 'draft-files';
+    if (options.async) {
+        const queuedCandidates = session.candidates.map((candidate) => ({
+            ...candidate,
+            analysisStatus: 'queued',
+            generationMode: 'deterministic',
+            generationProvider: 'pending',
+            llmContext: '',
+            evidence: [],
+            draftSave: { status: 'pending' },
+        }));
+        const queuedSession = {
+            ...session,
+            mode: 'ai-import',
+            persistence,
+            candidates: queuedCandidates,
+            generation: {
+                provider: 'pending',
+                aiEnabled: false,
+                contextObjectCount: 0,
+                createdDrafts: 0,
+                warnings: [],
+            },
+        };
+        writeBlockStudioImportSession(projectRoot, queuedSession);
+        void processDqlGenerationSessionForProject(projectRoot, session, { ...options, async: false, persistence }, semanticLayer)
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            for (const candidate of queuedCandidates) {
+                const current = readBlockStudioImportCandidate(projectRoot, session.id, candidate.id);
+                if (current.analysisStatus === 'ready')
+                    continue;
+                writeBlockStudioImportCandidate(projectRoot, session.id, {
+                    ...current,
+                    analysisStatus: 'needs_attention',
+                    warnings: Array.from(new Set([...(current.warnings ?? []), message])),
+                });
+            }
+        });
+        return queuedSession;
+    }
+    return processDqlGenerationSessionForProject(projectRoot, session, { ...options, persistence }, semanticLayer);
+}
+async function processDqlGenerationSessionForProject(projectRoot, session, options, semanticLayer) {
+    const deterministicOnly = isDeterministicDqlGenerationProvider(options.provider);
+    const requestedProvider = !deterministicOnly && isProviderSettingsId(options.provider) ? options.provider : undefined;
+    const provider = deterministicOnly ? null : await createBlockStudioAssistProvider(projectRoot, requestedProvider);
+    const persistence = options.persistence ?? 'draft-files';
     const warnings = [];
-    const nextCandidates = [];
-    let contextObjectCount = 0;
     for (const candidate of session.candidates) {
-        const contextPack = await buildDqlGenerationContextPack(projectRoot, candidate).catch((error) => {
-            warnings.push(`Context pack failed for ${candidate.name}: ${error instanceof Error ? error.message : String(error)}`);
-            return null;
+        writeBlockStudioImportCandidate(projectRoot, session.id, {
+            ...readBlockStudioImportCandidate(projectRoot, session.id, candidate.id),
+            analysisStatus: 'retrieving',
+            draftSave: { status: 'pending' },
         });
-        contextObjectCount += contextPack?.objects.length ?? 0;
-        const evidence = contextPack ? dqlGenerationEvidenceFromContext(contextPack, candidate) : deterministicDqlGenerationEvidence(candidate);
-        let patch = deterministicDqlGenerationPatch(candidate, evidence);
-        let generatorName = 'local-deterministic';
-        let generationMode = 'deterministic';
-        if (provider) {
-            const aiPatch = await buildAiDqlGenerationPatch(provider, candidate, evidence, contextPack).catch((error) => {
-                warnings.push(`AI generation fell back for ${candidate.name}: ${error instanceof Error ? error.message : String(error)}`);
-                return null;
+    }
+    const sharedContextPack = await buildDqlGenerationSessionContextPack(projectRoot, session.candidates).catch((error) => {
+        warnings.push(`Shared context pack failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    });
+    const contextObjectCount = sharedContextPack?.objects.length ?? 0;
+    const nextCandidates = await mapWithConcurrency(session.candidates, 3, async (candidate) => {
+        try {
+            const contextPack = sharedContextPack;
+            const evidence = contextPack ? dqlGenerationEvidenceFromContext(contextPack, candidate) : deterministicDqlGenerationEvidence(candidate);
+            writeBlockStudioImportCandidate(projectRoot, session.id, {
+                ...readBlockStudioImportCandidate(projectRoot, session.id, candidate.id),
+                analysisStatus: 'reviewing',
+                evidence,
             });
-            if (aiPatch) {
-                patch = mergeDqlGenerationPatch(patch, aiPatch, candidate, evidence);
-                generatorName = provider.name;
-                generationMode = 'ai';
+            let patch = deterministicDqlGenerationPatch(candidate, evidence);
+            let generatorName = 'local-deterministic';
+            let generationMode = 'deterministic';
+            const deterministicSimilarity = buildDqlGenerationSimilarityMatches(candidate, patch, contextPack);
+            if (deterministicSimilarity.recommendedAction === 'reuse_existing') {
+                patch = {
+                    ...patch,
+                    similarityMatches: deterministicSimilarity.matches,
+                    recommendedAction: 'reuse_existing',
+                };
+                generatorName = 'certified-reuse';
             }
+            else if (provider) {
+                const aiPatch = await buildAiDqlGenerationPatch(provider, candidate, evidence, contextPack).catch((error) => {
+                    warnings.push(`AI generation fell back for ${candidate.name}: ${error instanceof Error ? error.message : String(error)}`);
+                    return null;
+                });
+                if (aiPatch) {
+                    patch = mergeDqlGenerationPatch(patch, aiPatch, candidate, evidence);
+                    generatorName = provider.name;
+                    generationMode = 'ai';
+                }
+            }
+            const similarity = patch.recommendedAction === 'reuse_existing'
+                ? deterministicSimilarity
+                : buildDqlGenerationSimilarityMatches(candidate, patch, contextPack);
+            patch = {
+                ...patch,
+                similarityMatches: similarity.matches,
+                recommendedAction: similarity.recommendedAction,
+            };
+            for (const warning of patch.warnings ?? [])
+                warnings.push(`${candidate.name}: ${warning}`);
+            const enriched = updateBlockStudioImportCandidate(projectRoot, session.id, candidate.id, {
+                name: patch.name,
+                domain: patch.domain,
+                description: patch.description,
+                owner: patch.owner,
+                tags: patch.tags,
+                terms: patch.terms,
+                pattern: patch.pattern,
+                grain: patch.grain,
+                entities: patch.entities,
+                outputs: patch.outputs,
+                dimensions: patch.dimensions,
+                allowedFilters: patch.allowedFilters,
+                parameterPolicy: patch.parameterPolicy,
+                filterBindings: patch.filterBindings,
+                parameterDecisions: patch.parameterDecisions,
+                similarityMatches: patch.similarityMatches,
+                recommendedAction: patch.recommendedAction,
+                sourceSystems: patch.sourceSystems,
+                replacementFor: patch.replacementFor,
+                reviewCadence: patch.reviewCadence,
+                sql: patch.sql,
+                llmContext: patch.llmContext,
+                evidence,
+                conversionNotes: dqlGenerationConversionNotes(generatorName),
+                generationMode,
+                generationProvider: generatorName,
+            });
+            const validated = {
+                ...enriched,
+                dqlSource: buildSemanticImportCandidateSource(enriched, patch, semanticLayer) ?? enriched.dqlSource,
+                validation: validateBlockStudioSource(enriched.dqlSource, semanticLayer),
+                analysisStatus: 'ready',
+            };
+            validated.validation = validateBlockStudioSource(validated.dqlSource, semanticLayer);
+            const result = persistence === 'draft-files'
+                ? saveDqlGenerationDraftForProject(projectRoot, session.id, validated)
+                : {
+                    ...validated,
+                    reviewStatus: validated.recommendedAction === 'reuse_existing' ? 'review' : 'draft',
+                    generationMode: validated.generationMode ?? 'deterministic',
+                    generationProvider: validated.generationProvider ?? 'local-deterministic',
+                    llmContext: validated.llmContext ?? deterministicDqlGenerationContext(validated, validated.evidence ?? []),
+                    evidence: validated.evidence ?? [],
+                    draftSave: {
+                        status: validated.recommendedAction === 'reuse_existing' ? 'skipped' : 'pending',
+                        reason: validated.recommendedAction === 'reuse_existing' ? 'Reuse an existing governed block; no draft file was created.' : undefined,
+                    },
+                };
+            writeBlockStudioImportCandidate(projectRoot, session.id, result);
+            return result;
         }
-        const similarity = buildDqlGenerationSimilarityMatches(candidate, patch, contextPack);
-        patch = {
-            ...patch,
-            similarityMatches: similarity.matches,
-            recommendedAction: similarity.recommendedAction,
-        };
-        for (const warning of patch.warnings ?? [])
-            warnings.push(`${candidate.name}: ${warning}`);
-        const enriched = updateBlockStudioImportCandidate(projectRoot, session.id, candidate.id, {
-            name: patch.name,
-            domain: patch.domain,
-            description: patch.description,
-            owner: patch.owner,
-            tags: patch.tags,
-            terms: patch.terms,
-            pattern: patch.pattern,
-            grain: patch.grain,
-            entities: patch.entities,
-            outputs: patch.outputs,
-            dimensions: patch.dimensions,
-            allowedFilters: patch.allowedFilters,
-            parameterPolicy: patch.parameterPolicy,
-            filterBindings: patch.filterBindings,
-            parameterDecisions: patch.parameterDecisions,
-            similarityMatches: patch.similarityMatches,
-            recommendedAction: patch.recommendedAction,
-            sourceSystems: patch.sourceSystems,
-            replacementFor: patch.replacementFor,
-            reviewCadence: patch.reviewCadence,
-            sql: patch.sql,
-            llmContext: patch.llmContext,
-            evidence,
-            conversionNotes: dqlGenerationConversionNotes(generatorName),
-            generationMode,
-            generationProvider: generatorName,
-        });
-        const validated = {
-            ...enriched,
-            validation: validateBlockStudioSource(enriched.dqlSource, semanticLayer),
-        };
-        const savedDraft = saveDqlGenerationDraftForProject(projectRoot, session.id, validated);
-        writeBlockStudioImportCandidate(projectRoot, session.id, savedDraft);
-        nextCandidates.push(savedDraft);
-    }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`${candidate.name}: ${message}`);
+            const current = readBlockStudioImportCandidate(projectRoot, session.id, candidate.id);
+            const failed = {
+                ...current,
+                analysisStatus: 'needs_attention',
+                warnings: Array.from(new Set([...(current.warnings ?? []), message])),
+                generationMode: current.generationMode ?? 'deterministic',
+                generationProvider: current.generationProvider ?? 'local-deterministic',
+                llmContext: current.llmContext ?? deterministicDqlGenerationContext(current, current.evidence ?? []),
+                evidence: current.evidence ?? deterministicDqlGenerationEvidence(current),
+                draftSave: current.draftSave ?? { status: 'pending' },
+            };
+            writeBlockStudioImportCandidate(projectRoot, session.id, failed);
+            return failed;
+        }
+    });
     const generationSession = {
         ...session,
         mode: 'ai-import',
+        persistence,
         candidates: nextCandidates,
         updatedAt: new Date().toISOString(),
         generation: {
@@ -10040,6 +10902,19 @@ export async function createDqlGenerationSessionForProject(projectRoot, options,
         await refreshLocalMetadataCatalog(projectRoot);
     return generationSession;
 }
+async function mapWithConcurrency(items, limit, mapper) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, async () => {
+        while (cursor < items.length) {
+            const index = cursor;
+            cursor += 1;
+            results[index] = await mapper(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
 function saveDqlGenerationDraftForProject(projectRoot, importId, candidate) {
     if (candidate.recommendedAction === 'reuse_existing') {
         const topMatch = candidate.similarityMatches?.[0];
@@ -10598,6 +11473,43 @@ async function buildDqlGenerationContextPack(projectRoot, candidate) {
         strictness: 'balanced',
     });
 }
+async function buildDqlGenerationSessionContextPack(projectRoot, candidates) {
+    const tables = Array.from(new Set(candidates.flatMap((candidate) => candidate.lineage.sourceTables))).join(', ');
+    const question = [
+        `Analyze ${candidates.length} SQL import candidate${candidates.length === 1 ? '' : 's'} for governed DQL reuse or composition.`,
+        tables ? `Source tables: ${tables}.` : '',
+        ...candidates.slice(0, 20).map((candidate, index) => [
+            `Candidate ${index + 1}: ${candidate.name}`,
+            candidate.description,
+            candidate.sql.slice(0, 1000),
+        ].filter(Boolean).join('\n')),
+    ].filter(Boolean).join('\n\n');
+    return buildLocalContextPack(projectRoot, {
+        question,
+        mode: 'build',
+        surface: 'block-studio',
+        limit: 160,
+        objectTypes: [
+            'dql_block',
+            'dql_term',
+            'business_view',
+            'domain',
+            'semantic_metric',
+            'semantic_model',
+            'semantic_dimension',
+            'semantic_measure',
+            'dbt_model',
+            'dbt_source',
+            'dbt_column',
+            'warehouse_table',
+            'datalex_domain',
+            'datalex_entity',
+            'datalex_contract',
+            'datalex_term',
+        ],
+        strictness: 'balanced',
+    });
+}
 function dqlGenerationEvidenceFromContext(contextPack, candidate) {
     const directEvidence = contextPack.objects
         .filter((object) => isDqlGenerationEvidenceObject(object))
@@ -10749,6 +11661,54 @@ function deterministicDqlGenerationPatch(candidate, evidence) {
         reviewCadence: 'monthly',
     };
 }
+function buildSemanticImportCandidateSource(candidate, patch, semanticLayer) {
+    if (!semanticLayer || candidate.recommendedAction === 'reuse_existing')
+        return null;
+    const aggregateAliases = Array.from(candidate.sql.matchAll(/\b(?:sum|count|avg|min|max)\s*\([^)]*\)\s+(?:as\s+)?([A-Za-z_][A-Za-z0-9_]*)/gi))
+        .map((match) => match[1]);
+    if (aggregateAliases.length === 0)
+        return null;
+    const metrics = semanticLayer.listMetrics();
+    const matchedMetrics = aggregateAliases.map((alias) => metrics.find((metric) => normalizedTerm(metric.name) === normalizedTerm(alias)));
+    if (matchedMetrics.some((metric) => !metric))
+        return null;
+    const metricNames = Array.from(new Set(matchedMetrics.map((metric) => metric.name)));
+    const compatibleDimensions = semanticLayer.listCompatibleDimensions(metricNames);
+    const compatibleByName = new Map(compatibleDimensions.map((dimension) => [normalizedTerm(dimension.name), dimension]));
+    const groupFields = extractDqlGenerationGroupByFields(candidate.sql)
+        .map((field) => field.split('.').pop() ?? field)
+        .filter((field) => !/^\d+$/.test(field));
+    const matchedDimensions = groupFields.map((field) => compatibleByName.get(normalizedTerm(field)));
+    if (groupFields.length > 0 && matchedDimensions.some((dimension) => !dimension))
+        return null;
+    const dimensionNames = Array.from(new Set(matchedDimensions.map((dimension) => dimension.name)));
+    const allowedFilters = (patch.allowedFilters ?? [])
+        .map((filter) => compatibleByName.get(normalizedTerm(filter))?.name)
+        .filter((filter) => Boolean(filter));
+    const quote = (value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    const metricLine = metricNames.length === 1
+        ? `  metric = ${quote(metricNames[0])}`
+        : `  metrics = [${metricNames.map(quote).join(', ')}]`;
+    const lines = [
+        `block ${quote(candidate.name)} {`,
+        '  status = "draft"',
+        `  domain = ${quote(candidate.domain)}`,
+        '  type = "semantic"',
+        `  description = ${quote(candidate.description)}`,
+        `  owner = ${quote(candidate.owner)}`,
+        `  tags = [${candidate.tags.map(quote).join(', ')}]`,
+        metricLine,
+        dimensionNames.length > 0 ? `  dimensions = [${dimensionNames.map(quote).join(', ')}]` : '',
+        allowedFilters.length > 0 ? `  requested_filters = [${allowedFilters.map(quote).join(', ')}]` : '',
+        '',
+        '  visualization {',
+        `    chart = "${dimensionNames.length > 0 ? 'bar' : 'kpi'}"`,
+        '  }',
+        '}',
+        '',
+    ];
+    return lines.filter((line, index) => line !== '' || (index > 0 && lines[index - 1] !== '')).join('\n');
+}
 function inferDqlGenerationTerms(evidence) {
     return Array.from(new Set(evidence
         .filter((item) => item.kind === 'dql_term' || item.kind === 'datalex_term')
@@ -12210,7 +13170,7 @@ function indentBlock(value, spaces) {
 function normalizeBlockStudioContent(options) {
     const content = options.content?.trim();
     if (content && /^\s*block\s+"/i.test(content)) {
-        return `${content.trimEnd()}\n`;
+        return `${applySavedBlockMetadata(content, options).trimEnd()}\n`;
     }
     return buildBlankBlockContent({
         name: options.name,
@@ -12224,6 +13184,29 @@ function normalizeBlockStudioContent(options) {
         sql: content || 'SELECT 1 AS value',
     });
 }
+/** Apply the fields supplied by the save dialog to an AI/DQL artifact as well. */
+function applySavedBlockMetadata(source, options) {
+    let next = source.trim();
+    next = next.replace(/block\s+"[^"]*"\s*\{/, `block "${escapeDqlString(options.name)}" {`);
+    const upsert = (key, value) => {
+        const pattern = new RegExp(`^(\\s*)${key}\\s*=.*$`, 'm');
+        if (pattern.test(next)) {
+            next = next.replace(pattern, (_match, indent) => `${indent}${key} = ${value}`);
+        }
+        else {
+            next = next.replace(/block\s+"[^"]*"\s*\{/, (match) => `${match}\n  ${key} = ${value}`);
+        }
+    };
+    upsert('domain', `"${escapeDqlString(options.domain)}"`);
+    if (options.owner?.trim())
+        upsert('owner', `"${escapeDqlString(options.owner.trim())}"`);
+    if (options.description?.trim())
+        upsert('description', `"${escapeDqlString(options.description.trim())}"`);
+    if (options.tags && options.tags.length > 0) {
+        upsert('tags', `[${options.tags.map((tag) => `"${escapeDqlString(tag)}"`).join(', ')}]`);
+    }
+    return next;
+}
 function buildBlankBlockContent(options) {
     const lines = [
         `block "${escapeDqlString(options.name)}" {`,
@@ -13399,6 +14382,93 @@ async function gitPush(cwd) {
         ? { ok: true, output: gitErrorOutput(res) }
         : { ok: false, error: gitErrorOutput(res) };
 }
+async function execGh(cwd, args) {
+    const { execFile } = await import('node:child_process');
+    return new Promise((resolve) => {
+        execFile('gh', args, { cwd, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+            resolve({
+                stdout: String(stdout ?? ''),
+                stderr: String(stderr ?? ''),
+                code: err ? (err.code ? 1 : err.code ?? 1) : 0,
+            });
+        });
+    });
+}
+function gitReviewBranchName(title) {
+    const slug = title.toLowerCase().trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 46) || 'governed-update';
+    return `dql/review/${slug}-${Date.now().toString(36)}`;
+}
+function gitHubCompareUrl(remoteUrl, branch, base) {
+    if (!remoteUrl)
+        return undefined;
+    const normalized = remoteUrl
+        .replace(/^git@github\.com:/, 'https://github.com/')
+        .replace(/\.git$/, '');
+    const match = /^https?:\/\/github\.com\/([^/]+\/[^/]+)$/.exec(normalized);
+    return match ? `https://github.com/${match[1]}/compare/${encodeURIComponent(base)}...${encodeURIComponent(branch)}?expand=1` : undefined;
+}
+/**
+ * The only Git write workflow that can create a PR from the UI. It explicitly
+ * creates/switches a review branch when starting from the base branch and never
+ * calls merge. Existing staged changes outside the requested files are blocked
+ * so a review cannot accidentally include unrelated work.
+ */
+async function gitCreateReview(cwd, input) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const title = input.title.trim();
+    if (!title)
+        return { ok: false, error: 'Review title required' };
+    const validPaths = validatePaths(gitRoot, input.paths);
+    if (!validPaths.ok)
+        return { ok: false, error: validPaths.error };
+    const base = input.base.trim() || 'main';
+    const status = await readGitStatus(gitRoot);
+    const stagedOutsideReview = status.changes
+        .filter((change) => change.status[0] !== ' ' && change.status[0] !== '?' && !validPaths.paths.includes(change.path))
+        .map((change) => change.path);
+    if (stagedOutsideReview.length > 0) {
+        return { ok: false, error: `Unstage unrelated files before requesting review: ${stagedOutsideReview.slice(0, 3).join(', ')}` };
+    }
+    const remoteBeforeReview = await readGitRemote(gitRoot);
+    if (!remoteBeforeReview.url) {
+        return { ok: false, error: 'Add a Git remote before requesting review. No branch or commit was created.' };
+    }
+    let branch = status.branch;
+    if (!branch || branch === 'HEAD' || branch === base || branch === 'master') {
+        branch = gitReviewBranchName(title);
+        const created = await gitCreateBranch(gitRoot, branch, true);
+        if (!created.ok)
+            return created;
+    }
+    const stage = await gitStage(gitRoot, validPaths.paths);
+    if (!stage.ok)
+        return stage;
+    const commit = await gitCommit(gitRoot, title, false);
+    if (!commit.ok)
+        return commit;
+    const pushed = await gitPush(gitRoot);
+    if (!pushed.ok)
+        return { ...pushed, branch, hash: commit.hash };
+    const remote = await readGitRemote(gitRoot);
+    const compareUrl = gitHubCompareUrl(remote.url, branch, base);
+    const pr = await execGh(gitRoot, ['pr', 'create', '--base', base, '--head', branch, '--title', title, '--body', input.body.trim() || `Review governed analytics changes: ${title}`]);
+    if (pr.code === 0) {
+        const prUrl = (pr.stdout.match(/https:\/\/github\.com\/[^\s]+\/pull\/\d+/)?.[0]) ?? compareUrl;
+        return { ok: true, branch, hash: commit.hash, prUrl };
+    }
+    return {
+        ok: true,
+        branch,
+        hash: commit.hash,
+        prUrl: compareUrl,
+        warning: `Branch pushed. Open the compare page to create the PR: ${gitErrorOutput(pr) || 'GitHub CLI is not available or authenticated.'}`,
+    };
+}
 async function gitPull(cwd) {
     const gitRoot = await resolveGitRoot(cwd);
     if (!gitRoot)
@@ -13431,6 +14501,81 @@ async function readGitRemote(cwd) {
     const url = await execGit(gitRoot, ['remote', 'get-url', name]);
     return { inRepo: true, url: url.code === 0 ? url.stdout.trim() : null, name };
 }
+function collectGovernedSourcePaths(root, folder, predicate) {
+    const start = join(root, folder);
+    if (!existsSync(start))
+        return [];
+    const paths = [];
+    const walk = (dir) => {
+        if (paths.length >= 400)
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (paths.length >= 400)
+                return;
+            const absolute = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(absolute);
+            else if (entry.isFile() && predicate(entry.name))
+                paths.push(absolute);
+        }
+    };
+    walk(start);
+    return paths;
+}
+async function gitGovernedFileState(gitRoot, path) {
+    const tracked = await execGit(gitRoot, ['ls-files', '--error-unmatch', '--', path]);
+    const status = await execGit(gitRoot, ['status', '--porcelain=v1', '--untracked-files=all', '--', path]);
+    if (tracked.code === 0)
+        return status.stdout.trim() ? 'changed' : 'tracked';
+    const ignored = await execGit(gitRoot, ['check-ignore', '-q', '--', path]);
+    return ignored.code === 0 ? 'ignored' : 'untracked';
+}
+async function readGitGovernedContext(cwd) {
+    const gitRoot = await resolveGitRoot(cwd);
+    const empty = () => ({ total: 0, tracked: 0, changed: 0, untracked: 0, ignored: 0, paths: [] });
+    if (!gitRoot)
+        return { inRepo: false, trackingReady: false, domains: empty(), skills: empty() };
+    const summarize = async (files) => {
+        const group = empty();
+        for (const absolute of files) {
+            const path = relative(gitRoot, absolute).replace(/\\/g, '/');
+            const state = await gitGovernedFileState(gitRoot, path);
+            group.total += 1;
+            group[state] += 1;
+            if (group.paths.length < 24)
+                group.paths.push({ path, state });
+        }
+        return group;
+    };
+    const [domains, skills] = await Promise.all([
+        summarize(collectGovernedSourcePaths(cwd, 'domains', (name) => name === 'domain.dql')),
+        summarize([
+            ...collectGovernedSourcePaths(cwd, 'skills', (name) => name.endsWith('.skill.md')),
+            ...collectGovernedSourcePaths(cwd, '.dql/skills', (name) => name.endsWith('.skill.md')),
+        ]),
+    ]);
+    return { inRepo: true, trackingReady: domains.ignored === 0 && skills.ignored === 0, domains, skills };
+}
+/** Replace only the legacy broad `.dql/` ignore with cache/runtime-specific rules. */
+async function enableGitGovernedContextTracking(cwd) {
+    const gitRoot = await resolveGitRoot(cwd);
+    if (!gitRoot)
+        return { ok: false, error: 'Not a git repository' };
+    const ignorePath = join(cwd, '.gitignore');
+    const existing = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf-8') : '';
+    const lines = existing.split(/\r?\n/);
+    const next = lines.filter((line) => !/^\s*\/?\.dql\/\s*$/.test(line));
+    const keepLocal = ['.dql/runs/', '.dql/cache/', '.dql/imports/', '.dql/local/', '.dql/docker-starter/'];
+    for (const rule of keepLocal) {
+        if (!next.some((line) => line.trim() === rule))
+            next.push(rule);
+    }
+    const rendered = `${next.join('\n').replace(/\n+$/, '')}\n`;
+    if (rendered !== existing)
+        writeFileSync(ignorePath, rendered, 'utf-8');
+    const migration = migrateLegacySkills(cwd);
+    return { ok: true, changed: rendered !== existing || migration.moved.length > 0 };
+}
 async function gitCreateBranch(cwd, name, checkout) {
     const gitRoot = await resolveGitRoot(cwd);
     if (!gitRoot)
@@ -13710,10 +14855,31 @@ function isAiPinRefreshDue(lastRefreshedAt) {
         return true;
     return Date.now() - last >= 24 * 60 * 60 * 1000;
 }
-async function buildAgentSchemaContextFromCatalog(projectRoot, question) {
-    const contextPack = await buildLocalContextPack(projectRoot, { question, limit: 80 });
+async function buildAgentSchemaContextFromCatalog(projectRoot, question, preparedContextPack) {
+    const contextPack = preparedContextPack ?? await buildLocalContextPack(projectRoot, { question, limit: 80 });
     return buildAgentSchemaContextFromContextPack(question, contextPack);
 }
+/** How long a stored live-warehouse schema snapshot is trusted before a rescan (P6). */
+const RUNTIME_SNAPSHOT_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+/**
+ * Whether the project's stored live-schema snapshot is missing or older than the
+ * freshness window (P6). Used to force a fresh information_schema scan even when the
+ * question-shape heuristic wouldn't otherwise trigger one — so a warehouse schema
+ * change between sessions isn't silently reasoned over. Best-effort: a catalog error
+ * returns false so it never causes a rescan storm.
+ */
+export function runtimeSnapshotStale(projectRoot, maxAgeMs = RUNTIME_SNAPSHOT_MAX_AGE_MS) {
+    try {
+        const snapshot = latestRuntimeSchemaSnapshotForProject(projectRoot);
+        if (!snapshot?.capturedAt)
+            return true;
+        const age = Date.now() - new Date(snapshot.capturedAt).getTime();
+        return !Number.isFinite(age) || age > maxAgeMs;
+    }
+    catch {
+        return false;
+    }
+}
 function recordAgentRuntimeSchemaSnapshot(projectRoot, schemaContext, source) {
     if (schemaContext.length === 0)
         return;