@multileaf/ai-workflow 0.4.1 → 0.6.0

package/dist/workflow.js

@@ -7,8 +7,9 @@ import { assertSafeProjectPath, withSafeProjectWrites, writeProjectFilesAtomical
 import { parseProjectProfile, profileProject } from "./profile.js";
 import { applyOverrides } from "./confirmation.js";
 import { mergeFacts } from "./intelligence.js";
-import { createInterpretationRequest } from "./interpreter.js";
-import { recommendCapabilities, resourcesForCapabilities, serializeRecommendations, } from "./recommendations.js";
+import { configureOptionalModels } from "./model-onboarding.js";
+import { createInterpretationRequest, createOpenAiCompatibleProvider, createProjectInterpreter, buildInterpreterQuery, loadAiProviderConfig, selectInterpreterKeyFiles, } from "./interpreter.js";
+import { recommendCapabilities, rankRecommendations, resourcesForCapabilities, serializeRecommendations, } from "./recommendations.js";
 import { selectRecommendations } from "./selection.js";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
@@ -20,9 +21,9 @@ import { validatePackageContract } from "./package-contract.js";
 import { parseLock, resolvePackage, serializeLock } from "./lockfile.js";
 import { executeVercelSkills, installVercelSkill, nodeCommandExecutor } from "./vercel-skills.js";
 import { scanProject } from "./scanner.js";
-import { readFactOverrides, saveSettingOverrides, saveSettingsSection, loadSettings, } from "./settings.js";
-import { buildEvidenceTriageRequest, createOllamaDecisionProvider, DEFAULT_DECISION_CONFIG, loadDecisionConfig, } from "./decision.js";
-import { buildSemanticIndex, createOllamaEmbeddingProvider, DEFAULT_SEMANTIC_CONFIG, loadSemanticConfig, parseSemanticIndex, querySemanticIndex, SEMANTIC_INDEX_PATH, serializeSemanticIndex, } from "./semantic.js";
+import { readFactOverrides, saveSettingOverrides, saveSettingsSection } from "./settings.js";
+import { buildEvidenceTriageRequest, buildRecommendationRankingRequest, buildSemanticRerankRequest, createOllamaDecisionProvider, loadDecisionConfig, } from "./decision.js";
+import { buildSemanticIndex, createOllamaEmbeddingProvider, loadSemanticConfig, parseSemanticIndex, querySemanticIndex, rerankSemanticMatches, SEMANTIC_INDEX_PATH, serializeSemanticIndex, } from "./semantic.js";
 import { assertKnownPermissions, assertPermissions, assertPackagePermissions, serializePermissionReview, } from "./package-audit.js";
 import { planPackageUpdate } from "./package-updates.js";
 import { searchRegistry, serializeRegistry } from "./registry.js";
@@ -42,7 +43,7 @@ import { evaluateQualityGate } from "./quality-gates.js";
 import { parseMigrationCheckpoint, planNeutralResourceMigration, readResourceBytes, serializeMigrationPreview, serializeMigrationCheckpoint, validateNeutralResourceDocument, writeResourceBytes, } from "./migration.js";
 import { parsePrivateRegistries, parseTeamPreset, serializePrivateRegistries, serializeTeamPreset, fetchPrivateRegistryClient, } from "./team-configuration.js";
 import { enforcePolicyGate, gitPolicyTracking } from "./policy-gate.js";
-import { DEFAULT_TELEMETRY_CONFIG, loadTelemetryConfig, parseTelemetryConfig, serializeTelemetryMapping, } from "./telemetry.js";
+import { DEFAULT_TELEMETRY_CONFIG, loadTelemetryConfig, offerTelemetryConsent, parseTelemetryConfig, purgeTelemetryBuffer, readTelemetryBuffer, serializeTelemetryMapping, TELEMETRY_BUFFER_CAP, TELEMETRY_BUFFER_FILE, } from "./telemetry.js";
 import { createPluginScaffold, validatePluginDirectory, writePluginScaffold, } from "./plugin-sdk.js";
 import { executeOrchestrationPlan, parseOrchestrationPlan, serializeOrchestrationPreview, serializeOrchestrationResults, validateOrchestrationParallelism, } from "./orchestration.js";
 export async function runCommand(args, root, fs, services = {}) {
@@ -331,10 +332,12 @@ export async function runCommand(args, root, fs, services = {}) {
             pendingWrites.set(manifestPath, `schema: 1\nproject:\n  name: ${root.split("/").pop()}\ntarget:\n  active: ${target}\npolicies:\n  artifact_language: en\n`);
             writeProjectFilesAtomically(fs, root, [...pendingWrites].map(([path, content]) => ({ path, content })), [...BASE_DIRECTORIES.map((directory) => join(aiw, directory)), join(root, ".context/adrs")]);
             let optionalModels = [];
+            let telemetryEnabled;
             if (stdin.isTTY) {
                 const terminal = createInterface({ input: stdin, output: stdout });
                 try {
                     optionalModels = await configureOptionalModels(fs, aiw, (question) => terminal.question(question));
+                    telemetryEnabled = await offerTelemetryConsent(fs, aiw, (question) => terminal.question(question));
                 }
                 finally {
                     terminal.close();
@@ -345,34 +348,49 @@ export async function runCommand(args, root, fs, services = {}) {
                 output: `AI Workflow initialized for target: ${target} with only the ai-init skill. Run /ai-init to scan the project and choose which resources to install.` +
                     (optionalModels.length
                         ? ` Optional models enabled: ${optionalModels.join(", ")}. They activate once the models are available.`
+                        : "") +
+                    (telemetryEnabled !== undefined
+                        ? telemetryEnabled
+                            ? " Telemetry enabled (command name and outcome only); disable anytime with `aiw telemetry disable`."
+                            : " Telemetry disabled; enable anytime with `aiw telemetry enable`."
                         : ""),
             };
         }
         if (command === "telemetry") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
-            const usage = "Usage: aiw telemetry <status|enable|disable> [--commands=include|exclude] [--outcomes=include|exclude]";
+            const usage = "Usage: aiw telemetry <status|enable|disable> [--verbose] [--commands=include|exclude] [--outcomes=include|exclude]";
             const action = args[1];
             if (!action)
                 return { exitCode: 1, error: usage };
             const telemetryConfig = loadTelemetryConfig(fs, aiw);
+            const actionArgs = args.slice(2).filter((arg) => arg !== "--verbose");
+            const verbose = args.includes("--verbose");
             if (action === "status") {
-                if (args.length !== 2)
+                if (actionArgs.length !== 0)
                     return { exitCode: 1, error: usage };
                 const config = telemetryConfig;
+                const buffered = verbose ? readTelemetryBuffer(fs, aiw) : undefined;
                 return {
                     exitCode: 0,
-                    output: `Telemetry is ${config.enabled ? "enabled" : "disabled"}. Command collection: ${config.includeCommand ? "included" : "excluded"}. Outcome collection: ${config.includeOutcome ? "included" : "excluded"}.`,
+                    output: `Telemetry is ${config.enabled ? "enabled" : "disabled"}. Command collection: ${config.includeCommand ? "included" : "excluded"}. Outcome collection: ${config.includeOutcome ? "included" : "excluded"}.` +
+                        (buffered !== undefined
+                            ? `\nLocal buffer: ${buffered.length} event${buffered.length === 1 ? "" : "s"} (cap ${TELEMETRY_BUFFER_CAP}, .aiw/${TELEMETRY_BUFFER_FILE}).` +
+                                (buffered.length > 0
+                                    ? `\n${buffered.map((event) => `- ${JSON.stringify(event)}`).join("\n")}`
+                                    : "")
+                            : ""),
                 };
             }
             if (action === "disable") {
-                if (args.length !== 2)
+                if (actionArgs.length !== 0)
                     return { exitCode: 1, error: usage };
+                purgeTelemetryBuffer(fs, aiw);
                 saveSettingsSection(fs, aiw, "telemetry", serializeTelemetryMapping(DEFAULT_TELEMETRY_CONFIG));
                 return { exitCode: 0, output: "Telemetry disabled." };
             }
             if (action === "enable") {
-                const options = args.slice(2);
+                const options = args.slice(2).filter((arg) => arg !== "--verbose");
                 if (options.some((option) => !/^--(?:commands|outcomes)=(?:include|exclude)$/.test(option)) ||
                     new Set(options.map((option) => option.slice(0, option.indexOf("=")))).size !==
                         options.length)
@@ -424,10 +442,57 @@ export async function runCommand(args, root, fs, services = {}) {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const profile = await (services.profiler?.profile(root) ?? profileProject(root));
-            if (services.interpreter) {
+            let interpreter = services.interpreter;
+            let interpreterModel;
+            if (!interpreter) {
+                const aiConfig = loadAiProviderConfig(fs, aiw);
+                if (aiConfig?.enabled) {
+                    interpreter = createProjectInterpreter(root, services.aiProvider ?? createOpenAiCompatibleProvider(aiConfig));
+                    interpreterModel = aiConfig.model;
+                }
+            }
+            else
+                interpreterModel = "host-injected";
+            const modelUsage = [];
+            if (interpreter) {
                 const scan = await (services.scanner?.scan(root) ?? scanProject(root));
-                const inferred = await services.interpreter.interpret(createInterpretationRequest(profile, scan.files));
+                let scopedFiles = scan.files;
+                let priorityFiles;
+                const contextConfig = loadSemanticConfig(fs, aiw);
+                const contextIndexPath = join(aiw, SEMANTIC_INDEX_PATH);
+                if (contextConfig?.enabled && fs.exists(contextIndexPath)) {
+                    try {
+                        const index = parseSemanticIndex(fs.read(contextIndexPath));
+                        if (index.model === contextConfig.model && index.chunks.length > 0) {
+                            const embedding = services.embeddingProvider ?? createOllamaEmbeddingProvider(contextConfig);
+                            if (await embedding.available()) {
+                                const matches = await querySemanticIndex(index, buildInterpreterQuery(profile), embedding, contextConfig);
+                                priorityFiles = [
+                                    ...selectInterpreterKeyFiles(scan.files),
+                                    ...matches.map((match) => match.file),
+                                ];
+                                const allowed = new Set(priorityFiles);
+                                scopedFiles = scan.files.filter((file) => allowed.has(file));
+                                modelUsage.push({
+                                    label: "embedding",
+                                    tokens: Math.ceil(buildInterpreterQuery(profile).length / 4),
+                                    detail: `${contextConfig.model} — scoped interpreter context to ${matches.length} semantic matches`,
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // An unreadable index keeps the scan deterministic with alphabetical scoping.
+                    }
+                }
+                const interpretationRequest = createInterpretationRequest(profile, scopedFiles, 4000, priorityFiles);
+                const inferred = await interpreter.interpret(interpretationRequest);
                 profile.facts = mergeFacts(profile.facts, inferred);
+                modelUsage.push({
+                    label: "interpreter",
+                    tokens: interpretationRequest.estimatedTokens,
+                    detail: `${interpreterModel} — ${inferred.length} facts from ${interpretationRequest.files.length} files`,
+                });
             }
             const overrides = readFactOverrides(fs, aiw);
             const rejectedKeys = new Set(overrides
@@ -442,7 +507,7 @@ export async function runCommand(args, root, fs, services = {}) {
             fs.write(join(aiw, "profile.yml"), `schema: 1\nstatus: scanned\nfacts:\n${evidence}\nruntime:\n  languages: [${profile.runtime.languages.join(", ")}]\nframeworks: [${profile.frameworks.join(", ")}]\npackage_manager: ${profile.packageManager}\nquality:\n  linter: ${profile.quality.linter?.name ?? "unknown"}\n  linter_command: ${profile.quality.linter?.command ?? "unknown"}\n  formatter: ${profile.quality.formatter?.name ?? "unknown"}\n  formatter_command: ${profile.quality.formatter?.command ?? "unknown"}\n  typecheck: ${profile.quality.typecheck?.name ?? "unknown"}\n  typecheck_command: ${profile.quality.typecheck?.command ?? "unknown"}\ntesting: ${profile.testing?.name ?? "unknown"}\ntesting_command: ${profile.testing?.command ?? "unknown"}\nci: [${profile.ci.join(", ")}]\nworkspaces: [${profile.workspaces.join(", ")}]\nproject_modules: ${JSON.stringify(profile.modules ?? [])}\npolicies:\n  artifact_language: en\n`);
             const semanticConfig = loadSemanticConfig(fs, aiw);
             if (semanticConfig?.enabled) {
-                const provider = createOllamaEmbeddingProvider(semanticConfig);
+                const provider = services.embeddingProvider ?? createOllamaEmbeddingProvider(semanticConfig);
                 if (!(await provider.available()))
                     return {
                         exitCode: 1,
@@ -460,8 +525,34 @@ export async function runCommand(args, root, fs, services = {}) {
                 }, provider, semanticConfig);
                 fs.mkdir(join(aiw, "semantic"));
                 fs.write(join(aiw, SEMANTIC_INDEX_PATH), serializeSemanticIndex(index));
+                const indexedChars = index.chunks.reduce((total, chunk) => total + chunk.text.length, 0);
+                modelUsage.push({
+                    label: "embedding",
+                    tokens: Math.ceil(indexedChars / 4),
+                    detail: `${semanticConfig.model} — indexed ${index.chunks.length} chunks in ${Math.ceil(index.chunks.length / 64)} batch requests`,
+                });
             }
-            return { exitCode: 0, output: "Project profile generated." };
+            if (modelUsage.length > 0) {
+                const usagePath = join(aiw, "usage.yml");
+                const entries = fs.exists(usagePath) ? parseTokenUsage(fs.read(usagePath)) : [];
+                let next = entries;
+                for (const usage of modelUsage)
+                    next = recordTokenUsage(next, {
+                        stage: `scan.${usage.label}`,
+                        budget: usage.tokens,
+                        used: usage.tokens,
+                    });
+                fs.write(usagePath, serializeTokenUsage(next));
+            }
+            return {
+                exitCode: 0,
+                output: "Project profile generated." +
+                    (modelUsage.length > 0
+                        ? `\nModels used:\n${modelUsage
+                            .map((usage) => `- ${usage.label}: ${usage.detail} (~${usage.tokens.toLocaleString("en-US")} tokens)`)
+                            .join("\n")}`
+                        : "\nModels used: none (deterministic scan)."),
+            };
         }
         if (command === "decision") {
             const usage = "Usage: aiw decision triage --artifact=<path> | aiw decision status";
@@ -511,7 +602,7 @@ export async function runCommand(args, root, fs, services = {}) {
             return { exitCode: 1, error: usage };
         }
         if (command === "semantic") {
-            const usage = "Usage: aiw semantic query --text=<query> | aiw semantic status";
+            const usage = "Usage: aiw semantic query --text=<query> [--rerank] | aiw semantic status";
             const action = args[1];
             if (action === "status") {
                 const config = loadSemanticConfig(fs, aiw);
@@ -530,7 +621,9 @@ export async function runCommand(args, root, fs, services = {}) {
                 };
             }
             if (action === "query") {
-                const parsed = parseNamedOptions(args.slice(2), ["text"]);
+                const queryArgs = args.slice(2).filter((arg) => arg !== "--rerank");
+                const rerankRequested = args.slice(2).includes("--rerank");
+                const parsed = parseNamedOptions(queryArgs, ["text"]);
                 if (!parsed?.text)
                     return { exitCode: 1, error: usage };
                 const config = loadSemanticConfig(fs, aiw);
@@ -549,13 +642,38 @@ export async function runCommand(args, root, fs, services = {}) {
                         error: `Semantic model ${config.model} is not available at ${config.baseUrl}.`,
                     };
                 const matches = await querySemanticIndex(parseSemanticIndex(fs.read(indexPath)), parsed.text, provider, config);
+                let ranked = matches.map((match) => ({ ...match }));
+                let influence;
+                if (rerankRequested) {
+                    const decisionConfig = loadDecisionConfig(fs, aiw);
+                    if (!decisionConfig?.enabled)
+                        return {
+                            exitCode: 1,
+                            error: "Decision model is disabled. Set decision.enabled=true in .aiw/settings.yml to use --rerank.",
+                        };
+                    const decisionProvider = createOllamaDecisionProvider(decisionConfig);
+                    if (!(await decisionProvider.available()))
+                        return {
+                            exitCode: 1,
+                            error: `Decision model ${decisionConfig.model} is not available at ${decisionConfig.baseUrl}.`,
+                        };
+                    const outcome = await rerankSemanticMatches(matches, parsed.text, async (query, candidates) => {
+                        const response = await decisionProvider.decide(buildSemanticRerankRequest(query, candidates));
+                        const scores = {};
+                        for (const [id, answer] of Object.entries(response.answers))
+                            scores[id] = typeof answer.score === "number" ? answer.score : undefined;
+                        return scores;
+                    });
+                    ranked = outcome.matches;
+                    influence = `rerank influence: ${outcome.changedPositions}/${outcome.matches.length} positions reordered (advisory; cosine recall unchanged)`;
+                }
                 return {
                     exitCode: 0,
-                    output: matches.length === 0
+                    output: ranked.length === 0
                         ? "No semantic matches."
-                        : matches
-                            .map((match) => `- ${match.file} (score ${match.score.toFixed(3)})\n  ${match.excerpt}`)
-                            .join("\n"),
+                        : `${ranked
+                            .map((match) => `- ${match.file} (score ${match.score.toFixed(3)}${match.rerankScore !== undefined ? `, rerank ${match.rerankScore.toFixed(3)}` : ""})\n  ${match.excerpt}`)
+                            .join("\n")}${influence ? `\n${influence}` : ""}`,
                 };
             }
             return { exitCode: 1, error: usage };
@@ -922,6 +1040,33 @@ export async function runCommand(args, root, fs, services = {}) {
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const profile = await (services.profiler?.profile(root) ?? profileProject(root));
             const recommendations = services.recommender?.recommend(profile) ?? recommendCapabilities(profile);
+            let ordered = recommendations;
+            let ranked;
+            const rankingConfig = loadDecisionConfig(fs, aiw);
+            if (rankingConfig?.enabled) {
+                const decisionProvider = services.decisionProvider ?? createOllamaDecisionProvider(rankingConfig);
+                if (!(await decisionProvider.available()))
+                    return {
+                        exitCode: 1,
+                        error: `Decision model ${rankingConfig.model} is not available at ${rankingConfig.baseUrl}.`,
+                    };
+                ranked = await rankRecommendations(recommendations, profile, async (scoped, recs) => {
+                    const response = await decisionProvider.decide(buildRecommendationRankingRequest(profileSummaryForRanking(scoped), recs));
+                    const answers = {};
+                    for (const [id, answer] of Object.entries(response.answers))
+                        answers[id] =
+                            typeof answer.score === "number"
+                                ? {
+                                    relevance: answer.score,
+                                    ...(typeof answer.confidence === "number"
+                                        ? { confidence: answer.confidence }
+                                        : {}),
+                                }
+                                : {};
+                    return answers;
+                });
+                ordered = ranked.items;
+            }
             const selectedOption = args.find((arg) => arg.startsWith("--select="));
             const selectedArg = selectedOption?.slice("--select=".length) ?? "";
             let selection;
@@ -931,15 +1076,18 @@ export async function runCommand(args, root, fs, services = {}) {
                 selection = [];
             else {
                 const terminal = createInterface({ input: stdin, output: stdout });
-                selection = await selectRecommendations(recommendations, (question) => terminal.question(question));
+                selection = await selectRecommendations(ordered, (question) => terminal.question(question));
                 terminal.close();
             }
-            fs.write(join(aiw, "recommendations.yml"), serializeRecommendations(recommendations, selection));
+            fs.write(join(aiw, "recommendations.yml"), serializeRecommendations(ordered, selection, ranked?.ranking));
+            const rankingNote = ranked
+                ? ` Advisory decision-model ranking applied (${ranked.changedPositions} positions reordered); evidence states are unchanged.`
+                : "";
             return {
                 exitCode: 0,
-                output: selectedOption === undefined && !stdin.isTTY
-                    ? `${recommendations.length} recommendations generated without selection; review .aiw/recommendations.yml, then record user choices with --select=id,id.`
-                    : `${recommendations.length} recommendations generated.`,
+                output: `${ordered.length} recommendations generated${selectedOption === undefined && !stdin.isTTY
+                    ? " without selection; review .aiw/recommendations.yml, then record user choices with --select=id,id."
+                    : "."}${rankingNote}`,
             };
         }
         if (command === "skills") {
@@ -1795,39 +1943,6 @@ function approvalArtifactPath(aiw, stage) {
     };
     return resolve(aiw, paths[stage]);
 }
-export async function configureOptionalModels(fs, aiwPath, answer) {
-    const enabled = [];
-    const settings = loadSettings(fs, aiwPath) ?? {};
-    if (!("semantic" in settings)) {
-        const response = (await answer(`Enable semantic mapping with a local embedding model (default: ${DEFAULT_SEMANTIC_CONFIG.model} at ${DEFAULT_SEMANTIC_CONFIG.baseUrl})? [y/N] `))
-            .trim()
-            .toLowerCase();
-        if (response === "y" || response === "yes") {
-            saveSettingsSection(fs, aiwPath, "semantic", {
-                enabled: true,
-                model: DEFAULT_SEMANTIC_CONFIG.model,
-                baseUrl: DEFAULT_SEMANTIC_CONFIG.baseUrl,
-                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
-                topK: DEFAULT_SEMANTIC_CONFIG.topK,
-            });
-            enabled.push(`semantic (${DEFAULT_SEMANTIC_CONFIG.model})`);
-        }
-    }
-    if (!("decision" in settings)) {
-        const response = (await answer(`Enable advisory decision triage with a local decision model (default: ${DEFAULT_DECISION_CONFIG.model} at ${DEFAULT_DECISION_CONFIG.baseUrl})? [y/N] `))
-            .trim()
-            .toLowerCase();
-        if (response === "y" || response === "yes") {
-            saveSettingsSection(fs, aiwPath, "decision", {
-                enabled: true,
-                model: DEFAULT_DECISION_CONFIG.model,
-                baseUrl: DEFAULT_DECISION_CONFIG.baseUrl,
-            });
-            enabled.push(`decision (${DEFAULT_DECISION_CONFIG.model})`);
-        }
-    }
-    return enabled;
-}
 function formatConfidence(confidence) {
     return confidence === undefined ? "unknown" : confidence.toFixed(3);
 }
@@ -2193,6 +2308,15 @@ function safeProjectSignal(value) {
         .replace(/\s+/g, " ")
         .slice(0, 180);
 }
+function profileSummaryForRanking(profile) {
+    return [
+        `languages: ${profile.runtime.languages.join(", ") || "none"}`,
+        `frameworks: ${profile.frameworks.join(", ") || "none"}`,
+        `package-manager: ${profile.packageManager}`,
+        `testing: ${profile.testing?.name ?? "none"}`,
+        `linter: ${profile.quality.linter?.name ?? "none"}`,
+    ].join("; ");
+}
 function readSelectedRecommendations(fs, aiw) {
     if (!fs.exists(join(aiw, "recommendations.yml")))
         return [];

package/docs/README.md

@@ -13,6 +13,11 @@ AI Workflow is a portable, spec-driven development system for AI coding agents.
 - [Quality and testing](quality.md)
 - [Token efficiency](token-efficiency.md)
 - [Project intelligence](project-intelligence.md)
+- [Semantic mapping](semantic-mapping.md)
+- [Decision model evaluation](decision-model-evaluation.md)
+- [Telemetry and privacy](telemetry.md)
+- [Multi-agent orchestration](orchestration.md)
+- [Plugin authoring](plugin-authoring.md)
 - [Release process](release-process.md)
 - [Release backlog](release-backlog.md)
 - [Backlog](backlog.md)

package/docs/backlog.md

@@ -29,8 +29,10 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 - [x] **SCAN-006** Implement scoped AI project interpreter. _Acceptance:_ interpreter receives filtered context and produces structured insights requiring confirmation when uncertain.
 - [x] **SCAN-007** Add interpreter privacy and token guardrails. _Acceptance:_ secrets, dependencies, generated files, Git internals, and checkpoints are excluded and token usage is measured.
 - [x] **SCAN-004** Add interactive confirmation and overrides. _Acceptance:_ users can accept, reject, or edit inferred facts.
+- [x] **INT-001** Ship a built-in OpenAI-compatible `AiProvider`. _Acceptance:_ an `aiw` settings section configures a local or remote OpenAI-compatible endpoint (for example Ollama `gpt-oss:20b`) so the scoped AI interpreter works without a host-injected provider; secrets redaction, token ceilings, and scoped-context validation still apply; missing configuration keeps scans deterministic and offline.
 - [x] **REC-001** Build capability recommendation engine. _Acceptance:_ recommendations include rationale, evidence, permissions, conflicts, and confidence.
 - [x] **REC-002** Add interactive capability selection. _Acceptance:_ users select packages and individual resources before installation.
+- [x] **REC-003** Rank capability recommendations with a decision model. _Acceptance:_ when a decision model is enabled in settings, recommendations are ordered by decision-model relevance to the confirmed profile with confidence and rationale; ranking is advisory and never changes evidence states. See `docs/decision-model-evaluation.md`.
 - [x] **GEN-001** Generate project-specific rules, agents, hooks, and context. _Acceptance:_ generated content uses confirmed profile data and English artifacts.
 - [x] **GEN-002** Preserve manual overrides and detect drift. _Acceptance:_ regeneration never silently overwrites user changes.
 
@@ -70,6 +72,23 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 
 - [x] **SEM-001** Add flag-gated semantic mapping to scan and retrieval. _Acceptance:_ `.aiw/semantic.yml` with `enabled: true` verifies model availability before indexing, builds a versioned chunk index during `aiw scan`, and `aiw semantic query` returns ranked matches; missing or disabled configuration keeps scans fully deterministic and offline; semantic results are retrieval aids, never confirmed facts.
 - [x] **SEM-002** Integrate a decision model (jev/clef-flash via Ollama `/v1/systemone`) for advisory gate triage. _Acceptance:_ `.aiw/decision.yml` with `enabled: true` verifies model availability before use; `aiw decision triage` returns advisory `evidence_complete` and `gate` decisions with confidence; disabled or missing configuration makes no network request; advisory output never replaces human approval. See `docs/decision-model-evaluation.md`.
+- [x] **SEM-003** Embed chunks in batches. _Acceptance:_ indexing uses the batch embeddings endpoint (for example Ollama `/api/embed`) instead of one request per chunk, measurably reducing scan time on this repository (baseline: ~34s for 824 chunks) with identical index output.
+- [x] **SEM-004** Exclude lockfiles and generated vendor manifests from the semantic index. _Acceptance:_ files such as `package-lock.json` (observed contributing 75 noise chunks) are skipped during indexing by default with an explicit, documented override.
+- [x] **SEM-005** Re-rank semantic recall with a decision model. _Acceptance:_ when both semantic mapping and a decision model are enabled, `aiw semantic query` optionally re-ranks embedding matches with the decision model, reporting the ranking influence; recall without a decision model is unchanged.
+- [x] **SEM-006** Scope AI interpreter context with semantic retrieval. _Acceptance:_ when semantic mapping is enabled and an index exists, the interpreter receives deterministic key files plus the top semantically relevant chunks for the active analysis question instead of alphabetically ordered files up to the token ceiling; measured token usage decreases and inferred-fact quality does not regress against the current baseline; scans without semantic mapping are unchanged.
+
+## Onboarding — P1
+
+- [x] **TEL-001** Offer telemetry consent during installation. _Acceptance:_ interactive install asks about telemetry after the model questions with an explicit default of No, states the exact event payload (command name and outcome only, no arguments, paths, or contents), records the decision in `.aiw/settings.yml`, and remains reversible through `aiw telemetry enable/disable`; non-interactive installs skip the prompt; the prompt itself never emits an event.
+
+## Telemetry — P2
+
+- [x] **TEL-002** Add an inspectable local telemetry buffer. _Acceptance:_ when telemetry is enabled and a host client is absent, events accumulate in a rotated local buffer under `.aiw/` with a documented retention cap; `aiw telemetry status --verbose` displays buffered events; `aiw telemetry disable` purges the buffer; no network transport is introduced by this item.
+
+- [x] **ONB-001** Detect and offer real local models during installation. _Acceptance:_ interactive install probes the configured Ollama endpoint (`/api/tags`), lists the embedding and decision models actually available, and records the user's selection in `.aiw/settings.yml`; when no server or models are found, the installer reports the optional capability and continues without network assumptions; non-interactive installs are unchanged.
+
+## Context and cost — P2 (continued)
+
 - [x] **CTX-001** Build layered project context store.
 - [x] **CTX-002** Add task-scoped context retrieval and delta loading.
 - [x] **CTX-003** Add summary cache and freshness invalidation.
@@ -86,6 +105,10 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 - [x] **ENT-006** Add web UI for project profile, recommendations, traceability, and migrations. _Acceptance:_ `aiw ui` serves a local-only, responsive and accessible dashboard from packaged project state; profile, recommendations, and requirement evidence are visible; migrations require explicit confirmation and delegate to the existing workflow.
 - [x] **ENT-007** Add multi-agent orchestration and parallel task execution. _Acceptance:_ strict versioned task graphs support deterministic preview, explicit adapter-backed execution, bounded parallelism, dependency-aware failure isolation, and immutable checkpoint evidence.
 
+## Engineering — P2
+
+- [x] **ENG-001** Update GitHub Actions to Node 24-native versions. _Acceptance:_ `actions/checkout` and `actions/setup-node` upgraded past v4 so release workflows no longer emit Node.js 20 deprecation warnings; CI and Release workflows pass on `ubuntu-latest` before and after the October 19, 2026 Ubuntu 26 runner migration.
+
 ## Backlog rules
 
 - [x] **FND-009** Add self-validation workflow. _Acceptance:_ changes affecting AIW behavior execute against this repository and record generated-output evidence.

package/docs/decision-model-evaluation.md

@@ -27,14 +27,14 @@ Clef Flash answers typed questions over a supplied state in a single non-autoreg
 
 The earlier blocker (no exposed endpoint in Ollama 0.40.1) is resolved by the `/v1/systemone` endpoint documented at <https://ollama.com/library/clef-flash>. AI Workflow now ships the advisory layer:
 
-- `src/decision.ts`: `DecisionConfig` (`.aiw/decision.yml`, flag-gated: `enabled` / `model` / `baseUrl`), a `DecisionProvider` with availability verification (`/api/tags`), typed question/response contracts, and `buildEvidenceTriageRequest` for pre-gate triage.
+- `src/decision.ts`: `DecisionConfig` (`.aiw/decision.yml`, flag-gated: `enabled` / `model` / `baseUrl` / optional `apiKeyEnv` for an external OpenAI-compatible endpoint with bearer authentication), a `DecisionProvider` with availability verification (`/api/tags` for Ollama, `/v1/models` with auth for external), typed question/response contracts, and `buildEvidenceTriageRequest` for pre-gate triage.
 - `aiw decision status` and `aiw decision triage --artifact=<path>`: advisory `evidence_complete` (noul) and `gate` (`ready` / `needs-work`) decisions over any project artifact, with explicit confidence reporting.
 
 Observed behavior on real plans: an evidence-free plan scored `gate: ready` with confidence 0.044 and `evidence_complete` 0.260, while a fully evidenced plan scored confidence 0.718 and `evidence_complete` 0.924 — low confidence signals an inconclusive decision rather than approval.
 
 ## Future integration points (advisory)
 
-- **Recommendation ranking**: order capability recommendations by decision-model relevance to the confirmed profile.
+- **Recommendation ranking**: order capability recommendations by decision-model relevance to the confirmed profile. _Status:_ implemented 2026-10-08 behind `decision.enabled` — `aiw recommend` sends one `score` question per recommendation (with the confirmed profile summary and the recommendation rationale/evidence) through `/v1/systemone`, orders the output by advisory relevance, and serializes `decision_relevance` / `decision_confidence` per item. The ranking is advisory: evidence, confidence, and selection logic are unchanged, and without a decision model the deterministic order is preserved.
 - **Semantic re-ranking**: combine embedding recall (`aiw semantic query`) with clef re-ranking for sharper context selection during interpretation.
 
 ## Hard boundary (unchanged)

package/docs/project-intelligence.md

@@ -58,4 +58,16 @@ Before a provider call, the interpreter:
 - redacts common credential assignments, bearer tokens, and private keys;
 - rejects inferred evidence that cites any file outside the scoped request.
 
-The workflow accepts an injected interpreter service. A configured interpreter runs during `aiw scan`, and its structured facts are stored in `.aiw/profile.yml` alongside deterministic facts. Facts below the confidence threshold are marked `requires_confirmation: true`. Without a configured provider, scans remain deterministic and do not make a network request.
+The workflow accepts an injected interpreter service. Additionally, a built-in OpenAI-compatible provider can be configured through an `ai` section in `.aiw/settings.yml` so the interpreter works without a host-injected service:
+
+```yaml
+ai:
+  enabled: true
+  model: gpt-oss:20b # any model served by an OpenAI-compatible endpoint
+  baseUrl: http://localhost:11434 # local (Ollama) or remote
+  apiKeyEnv: AIW_AI_KEY # optional; bearer token read from this environment variable
+```
+
+The provider posts to `<baseUrl>/v1/chat/completions` with a JSON response format and the interpreter's token ceiling; all existing guardrails (secrets redaction, scoped-context validation, binary and sensitive-file exclusion) apply unchanged because the same interpreter pipeline is used. An injected interpreter service always takes precedence. Without an `ai` section, scans remain deterministic and do not make a network request.
+
+A configured interpreter runs during `aiw scan`, and its structured facts are stored in `.aiw/profile.yml` alongside deterministic facts. Facts below the confidence threshold are marked `requires_confirmation: true`.

package/docs/release-process.md

@@ -35,4 +35,4 @@ For the first publication only, create a short-lived granular npm token scoped t
 
 After `0.1.0` exists, configure organization `MultiLeaf`, repository `aiw`, workflow `release.yml`, and environment `npm` as a trusted publisher in the package settings. Publish a subsequent release through OIDC and verify its provenance on npm before deleting the GitHub bootstrap secret and revoking the granular token. A saved publisher configuration alone is insufficient evidence because npm validates it only during publication.
 
-The workflow uses Node 24 and npm 11.5.1 or newer, strictly validates Semantic Versioning, checks that the tag is `v<package-version>`, requires the approved license, and verifies ancestry from `origin/main`. Publish each tag only once; never reuse, move, or overwrite a published version.
+The workflow uses Node 24 and npm 11.5.1 or newer, strictly validates Semantic Versioning, checks that the tag is `v<package-version>`, requires the approved license, and verifies ancestry from `origin/main`. After publishing, a `github-release` job creates the GitHub Release for the tag from the matching `CHANGELOG.md` section, so the signed Git tag, GitHub release, and npm package always agree on the immutable version. Publish each tag only once; never reuse, move, or overwrite a published version.

package/docs/semantic-mapping.md

@@ -1,6 +1,10 @@
 # Semantic Mapping
 
-AI Workflow can build a semantic index of the scanned project with a local embedding model such as `embeddinggemma-2` served by Ollama. Semantic mapping is opt-in and flag-gated: it activates only when a valid configuration exists, and every scan and flow query re-reads the flag. Configuration lives in the local user settings file `.aiw/settings.yml` under the `semantic` section; the legacy `.aiw/semantic.yml` file is still read when `settings.yml` does not exist. During an interactive `aiw install`, the installer offers to create this configuration with defaults; answering `y` writes it before `/ai-init` runs. Declining, or installing non-interactively, leaves the section absent.
+AI Workflow can build a semantic index of the scanned project with a local embedding model such as `embeddinggemma-2` served by Ollama. Semantic mapping is opt-in and flag-gated: it activates only when a valid configuration exists, and every scan and flow query re-reads the flag. Configuration lives in the local user settings file `.aiw/settings.yml` under the `semantic` section; the legacy `.aiw/semantic.yml` file is still read when `settings.yml` does not exist.
+
+The provider can be Ollama (default, `http://localhost:11434`) or any OpenAI-compatible embeddings endpoint: set `apiKeyEnv` to the name of the environment variable holding the bearer token, and requests go to `<baseUrl>/v1/embeddings` with `Authorization: Bearer <token>` instead of Ollama's `/api/embed`. The token is read from the environment at call time and never stored in settings.
+
+During an interactive `aiw install`, the installer walks through provider selection: it probes the configured Ollama endpoint (`GET /api/tags`), offers Ollama or an external provider (external only, when Ollama is unreachable), lists the locally available embedding models — filtering to embedding-type models — and asks permission to run `ollama pull embeddinggemma-2` when none exist. External configuration asks for the endpoint URL, model name, and an optional token environment variable. The chosen setup is validated with a live request before being recorded in `.aiw/settings.yml`; a failed validation can be retried or skipped, and the next capability (decision triage) follows the same flow. Answering `n`, or installing non-interactively, leaves the section absent.
 
 ## Configuration
 
@@ -13,6 +17,8 @@ semantic:
   baseUrl: http://localhost:11434
   chunkChars: 1200 # optional, minimum 200
   topK: 8 # optional, results per query
+  excludeLockfiles: true # optional, skip lockfiles and generated vendor manifests (default: true)
+  apiKeyEnv: AIW_EMBED_KEY # optional, external OpenAI-compatible endpoint bearer token
 ```
 
 - `enabled: false` (or a missing file) disables semantic mapping entirely; scans stay deterministic and make no network request.
@@ -22,18 +28,41 @@ semantic:
 
 When semantic mapping is enabled, `aiw scan` additionally:
 
-1. Reads the scanned files with strict UTF-8 decoding (unreadable files are skipped).
+1. Reads the scanned files with strict UTF-8 decoding (unreadable files are skipped). Lockfiles and generated vendor manifests (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `go.sum`, `Cargo.lock`, `poetry.lock`, `Gemfile.lock`, `composer.lock`, `deno.lock`, `bun.lock`, `bun.lockb`, `uv.lock`, `Pipfile.lock`, `flake.lock`, `npm-shrinkwrap.json`) are skipped by default because they contribute noise chunks without retrieval value; set `excludeLockfiles: false` to index them explicitly.
 2. Splits each file into line-aligned chunks of at most `chunkChars` characters.
-3. Embeds each chunk with `POST /api/embeddings`.
+3. Embeds chunks in batches of up to 64 per request with `POST /api/embed` (Ollama batch embeddings endpoint) instead of one request per chunk.
 4. Writes the versioned index to `.aiw/semantic/index.json` (`schema: 1`).
 
 The index stores the model name; queries against an index built with a different model fail explicitly.
 
+## Usage visibility
+
+Every `aiw scan` reports the models it actually used, for example:
+
+```text
+Project profile generated.
+Models used:
+- embedding: embeddinggemma-2:latest — indexed 824 chunks in 13 batch requests (~45,000 tokens)
+- interpreter: gpt-oss:20b — 5 facts from 12 files (~3,800 tokens)
+```
+
+Token estimates are also recorded per stage in `.aiw/usage.yml` (`scan.embedding`, `scan.interpreter`; the latest scan overwrites its stage entry) and can be inspected with `aiw token-usage`. Scans that use no models report `Models used: none (deterministic scan).`
+
 ## Queries during the flow
 
-`aiw semantic query --text="<natural language>"` ranks indexed chunks by cosine similarity and returns the top `topK` matches with file, score, and excerpt. `aiw semantic status` reports whether mapping is configured and whether the index is built.
+`aiw semantic query --text="<natural language>" [--rerank]` ranks indexed chunks by cosine similarity and returns the top `topK` matches with file, score, and excerpt. With `--rerank`, and only when a decision model is also enabled and available, the decision model additionally scores each retrieved candidate 0–1 for query relevance and the output is reordered by that advisory score; matches without a decision score keep their cosine order. The command reports the ranking influence (how many positions were reordered) and the per-match `rerank` score; cosine recall itself is unchanged and reranking never creates confirmed facts. `aiw semantic status` reports whether mapping is configured and whether the index is built.
 
 ## Boundaries
 
 - Semantic results are retrieval aids, not evidence. They never create confirmed project facts and never bypass human approval gates.
 - The index is derived state; delete and rebuild it with `aiw scan` after structural changes.
+
+## Interpreter scoping
+
+When semantic mapping is enabled and a valid index built with the active model exists, `aiw scan` scopes the AI interpreter's context semantically instead of alphabetically:
+
+1. A deterministic set of key files (README, contributing/architecture docs, and primary package manifests such as `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`) is always included first, in a fixed priority order.
+2. The remaining context is the top semantically relevant files for a deterministic analysis query derived from the detected profile (languages, frameworks, package manager), ranked through the existing embedding index.
+3. Everything else is excluded, so measured token usage decreases while inferred-fact evidence still points at real scoped files.
+
+Without semantic mapping (or when the index is missing, built with another model, or the embedding model is unavailable), the interpreter keeps the previous deterministic alphabetical scoping and scans make no network request for scoping purposes.

package/docs/telemetry.md

@@ -2,6 +2,10 @@
 
 AI Workflow telemetry is disabled by default. No event is recorded unless a user explicitly runs `aiw telemetry enable` and a host application provides a telemetry client.
 
+## Installation consent
+
+During an interactive `aiw install`, after the optional model questions, the installer asks whether to enable anonymous telemetry with an explicit default of **No**. The question states the exact event payload: the command name and its outcome only — never arguments, file paths, or file contents. The answer is recorded in `.aiw/settings.yml` under the `telemetry` section (declining is recorded too, so the question is never repeated), and the decision is reversible at any time with `aiw telemetry enable` / `aiw telemetry disable`. Non-interactive installs skip the prompt entirely and leave the section absent, and the prompt itself never emits a telemetry event.
+
 ## Controls
 
 ```bash
@@ -15,6 +19,14 @@ Preferences are stored in the local user settings file `.aiw/settings.yml` under
 
 Rejected telemetry administration commands never produce telemetry events, even when a previous valid configuration enabled collection. This keeps malformed consent or privacy changes outside the telemetry stream.
 
+## Local buffer
+
+When telemetry is enabled but no host application provides a telemetry client, events accumulate in a rotated local buffer at `.aiw/telemetry-buffer.jsonl` (one JSON event per line, retention cap of 200 events — the oldest events are dropped first). This introduces no network transport: the buffer is written only to the local `.aiw/` directory.
+
+- `aiw telemetry status --verbose` displays the number of buffered events, the retention cap, and each buffered event verbatim.
+- `aiw telemetry disable` purges the buffer.
+- When a host client is present, events go to the client and the local buffer stays untouched.
+
 ## Data contract
 
 An event contains only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {