@multileaf/ai-workflow 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-08
+
+### Added
+
+- Batched semantic indexing: embedding requests now use the Ollama batch endpoint (`POST /api/embed`) with up to 64 chunks per request instead of one request per chunk, and lockfiles and generated vendor manifests (`package-lock.json`, `yarn.lock`, `go.sum`, and others) are excluded from the index by default (`semantic.excludeLockfiles` overrides).
+- Optional decision-model re-ranking for `aiw semantic query --rerank`: when a decision model is enabled, each retrieved candidate is scored 0-1 for query relevance and the output is reordered with a reported ranking influence; cosine recall without a decision model is unchanged.
+- Semantic interpreter scoping during `aiw scan`: when semantic mapping is enabled and an index exists, the AI interpreter receives deterministic key files plus the top semantically relevant files for a profile-derived query instead of the alphabetically ordered file list, reducing token usage.
+- Built-in OpenAI-compatible `AiProvider` configured through an `ai` section in `.aiw/settings.yml` (for example Ollama `gpt-oss:20b`), so the scoped interpreter works without a host-injected provider; secrets redaction, token ceilings, and scoped-context validation apply unchanged, and missing configuration keeps scans deterministic and offline.
+- Advisory decision-model ranking for `aiw recommend`: when a decision model is enabled, recommendations are ordered by relevance to the confirmed profile and serialized with `decision_relevance` / `decision_confidence`; evidence states never change.
+- Telemetry consent during interactive `aiw install`, asked after the optional model questions with an explicit default of No, stating the exact event payload (command name and outcome only); the decision is recorded in `.aiw/settings.yml` and reversible through `aiw telemetry enable/disable`. Non-interactive installs skip the prompt.
+- Local telemetry buffer: when telemetry is enabled and no host client is present, events accumulate in a rotated `.aiw/telemetry-buffer.jsonl` (retention cap of 200 events); `aiw telemetry status --verbose` displays buffered events and `aiw telemetry disable` purges the buffer. No network transport was added.
+- Local model detection during interactive install: the installer 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 it continues with defaults.
+
+### Changed
+
+- GitHub Actions now use Node 24-native `actions/checkout@v5` and `actions/setup-node@v5`, and CI runs on Node 24.
 ## [0.4.1] - 2026-10-08
 
 ### Fixed

package/dist/decision.d.ts

@@ -48,4 +48,15 @@ export declare function parseDecisionConfig(text: string): DecisionConfig;
 export declare function loadDecisionConfig(fs: FileSystem, aiwPath: string): DecisionConfig | undefined;
 export declare function parseDecisionResponse(text: string): DecisionResponse;
 export declare function createOllamaDecisionProvider(config: DecisionConfig): DecisionProvider;
+export type RecommendationRankingCandidate = {
+    id: string;
+    rationale: string;
+    evidence: string[];
+};
+export declare function buildRecommendationRankingRequest(profileSummary: string, candidates: RecommendationRankingCandidate[]): DecisionRequest;
+export type SemanticRerankCandidate = {
+    id: string;
+    text: string;
+};
+export declare function buildSemanticRerankRequest(query: string, candidates: SemanticRerankCandidate[]): DecisionRequest;
 export declare function buildEvidenceTriageRequest(artifact: string): DecisionRequest;

package/dist/decision.js

@@ -96,6 +96,31 @@ export function createOllamaDecisionProvider(config) {
         },
     };
 }
+export function buildRecommendationRankingRequest(profileSummary, candidates) {
+    const questions = {};
+    for (const candidate of candidates) {
+        questions[candidate.id] = {
+            type: "score",
+            instructions: `Confirmed project profile: ${profileSummary}.\nRate from 0 to 1 how relevant this capability recommendation is to that profile.\n\nRecommendation ${candidate.id}: ${candidate.rationale}\nEvidence: ${candidate.evidence.join(", ")}`,
+            criteria: [
+                "0 = irrelevant to the confirmed profile",
+                "1 = highly relevant to the confirmed profile",
+            ],
+        };
+    }
+    return { state: `Capability recommendation ranking for: ${profileSummary}`, questions };
+}
+export function buildSemanticRerankRequest(query, candidates) {
+    const questions = {};
+    for (const candidate of candidates) {
+        questions[candidate.id] = {
+            type: "score",
+            instructions: `Rate from 0 to 1 how well this retrieval candidate answers the user query "${query}".\n\nCandidate:\n${candidate.text}`,
+            criteria: ["0 = irrelevant to the query", "1 = directly and completely answers the query"],
+        };
+    }
+    return { state: `Semantic retrieval rerank for query: ${query}`, questions };
+}
 export function buildEvidenceTriageRequest(artifact) {
     return {
         state: artifact,

package/dist/interpreter.d.ts

@@ -1,5 +1,6 @@
 import type { EvidenceFact } from "./evidence.js";
 import type { ProjectProfile } from "./profile.js";
+import type { FileSystem } from "./types.js";
 export type InterpretationRequest = {
     profile: ProjectProfile;
     files: string[];
@@ -19,5 +20,20 @@ export type AiProvider = {
     generate(request: AiProviderRequest): Promise<string>;
 };
 export type ContextReader = (absolutePath: string) => Promise<string>;
-export declare function createInterpretationRequest(profile: ProjectProfile, files: string[], maxTokens?: number): InterpretationRequest;
+export type AiProviderConfig = {
+    enabled: boolean;
+    model: string;
+    baseUrl: string;
+    apiKeyEnv?: string;
+};
+export declare const DEFAULT_AI_PROVIDER_CONFIG: AiProviderConfig;
+export declare function parseAiProviderMapping(raw: unknown): AiProviderConfig;
+export declare function createInterpretationRequest(profile: ProjectProfile, files: string[], maxTokens?: number, priorityFiles?: string[]): InterpretationRequest;
+export declare const INTERPRETER_KEY_FILE_NAMES: string[];
+export declare function selectInterpreterKeyFiles(files: string[]): string[];
+export declare function buildInterpreterQuery(profile: ProjectProfile): string;
+type AiFetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare function loadAiProviderConfig(fs: FileSystem, aiwPath: string): AiProviderConfig | undefined;
+export declare function createOpenAiCompatibleProvider(config: AiProviderConfig, fetchImpl?: AiFetchLike, env?: Readonly<Record<string, string | undefined>>): AiProvider;
 export declare function createProjectInterpreter(root: string, provider: AiProvider, contextReader?: ContextReader): Interpreter;
+export {};

package/dist/interpreter.js

@@ -1,5 +1,32 @@
 import { lstat, readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
+import { loadSettings } from "./settings.js";
+export const DEFAULT_AI_PROVIDER_CONFIG = {
+    enabled: false,
+    model: "gpt-oss:20b",
+    baseUrl: "http://localhost:11434",
+};
+export function parseAiProviderMapping(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("ai must be a YAML mapping");
+    const record = raw;
+    const enabled = record.enabled;
+    const model = record.model;
+    const baseUrl = record.baseUrl;
+    const apiKeyEnv = record.apiKeyEnv;
+    if (typeof enabled !== "boolean")
+        throw new Error("ai.enabled must be a boolean");
+    if (!enabled)
+        return { ...DEFAULT_AI_PROVIDER_CONFIG, enabled: false };
+    if (typeof model !== "string" || model.trim() === "")
+        throw new Error("ai.model must be a non-empty string when the AI provider is enabled");
+    if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
+        throw new Error("ai.baseUrl must be an http(s) URL when the AI provider is enabled");
+    if (apiKeyEnv !== undefined &&
+        (typeof apiKeyEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(apiKeyEnv)))
+        throw new Error("ai.apiKeyEnv must be an uppercase environment variable name");
+    return { enabled: true, model, baseUrl, ...(apiKeyEnv ? { apiKeyEnv } : {}) };
+}
 const EXCLUDED_SEGMENT = /(^|\/)(\.git|node_modules|vendor|\.venv|venv|dist|build|coverage|out|target|\.next|\.nuxt|\.output)(\/|$)/i;
 const EXCLUDED_AIW = /(^|\/)\.aiw\/(generated|checkpoints)(\/|$)/i;
 const SENSITIVE = /(^|\/)\.env(?:\.[^/]*)?$|\.(pem|key|p12|pfx|secret)$/i;
@@ -58,19 +85,62 @@ function isBinary(content) {
             (code >= 14 && code <= 31));
     });
 }
-export function createInterpretationRequest(profile, files, maxTokens = 4000) {
+export function createInterpretationRequest(profile, files, maxTokens = 4000, priorityFiles) {
     if (!Number.isInteger(maxTokens) || maxTokens <= 0)
         throw new Error("maxTokens must be a positive integer");
-    const selectedFiles = [
-        ...new Set(files.filter(safeFile).map((file) => file.replaceAll("\\", "/"))),
-    ].sort();
+    const safe = [...new Set(files.filter(safeFile).map((file) => file.replaceAll("\\", "/")))];
+    const priority = priorityFiles?.map((file) => file.replaceAll("\\", "/"));
+    const ordered = priority
+        ? [
+            ...new Set(priority.filter((file) => safe.includes(file))),
+            ...safe.filter((file) => !priority.includes(file)).sort(),
+        ]
+        : [...safe].sort();
     return {
         profile,
-        files: selectedFiles,
+        files: ordered,
         maxTokens,
-        estimatedTokens: Math.min(maxTokens, JSON.stringify(profile).length + selectedFiles.join("\n").length),
+        estimatedTokens: Math.min(maxTokens, JSON.stringify(profile).length + ordered.join("\n").length),
     };
 }
+export const INTERPRETER_KEY_FILE_NAMES = [
+    "readme.md",
+    "contributing.md",
+    "architecture.md",
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "go.mod",
+    "cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "composer.json",
+    "gemfile",
+    "deno.json",
+    "mix.exs",
+];
+export function selectInterpreterKeyFiles(files) {
+    const byBasename = new Map();
+    for (const file of files) {
+        const normalized = file.replaceAll("\\", "/");
+        const basename = normalized.split("/").pop()?.toLowerCase() ?? "";
+        if (basename && !byBasename.has(basename))
+            byBasename.set(basename, normalized);
+    }
+    return INTERPRETER_KEY_FILE_NAMES.flatMap((name) => {
+        const match = byBasename.get(name);
+        return match ? [match] : [];
+    });
+}
+export function buildInterpreterQuery(profile) {
+    const parts = [
+        profile.runtime.languages.join(", "),
+        profile.frameworks.join(", "),
+        profile.packageManager,
+    ].filter((part) => part && part !== "unknown");
+    return `Project conventions, architecture, and coding standards${parts.length > 0 ? ` for ${parts.join(" with ")}` : ""}`;
+}
 function parseFacts(output, allowedFiles) {
     let value;
     try {
@@ -109,6 +179,46 @@ function parseFacts(output, allowedFiles) {
         };
     });
 }
+export function loadAiProviderConfig(fs, aiwPath) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings === undefined || !("ai" in settings))
+        return undefined;
+    return parseAiProviderMapping(settings.ai);
+}
+export function createOpenAiCompatibleProvider(config, fetchImpl = (url, init) => fetch(url, init), env = process.env) {
+    return {
+        async generate(request) {
+            const headers = { "content-type": "application/json" };
+            if (config.apiKeyEnv) {
+                const key = env[config.apiKeyEnv];
+                if (key)
+                    headers.authorization = `Bearer ${key}`;
+            }
+            const response = await fetchImpl(`${config.baseUrl}/v1/chat/completions`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({
+                    model: config.model,
+                    messages: [
+                        { role: "system", content: request.system },
+                        { role: "user", content: request.prompt },
+                    ],
+                    max_tokens: request.maxTokens,
+                    ...(request.responseFormat === "json"
+                        ? { response_format: { type: "json_object" } }
+                        : {}),
+                }),
+            });
+            if (!response.ok)
+                throw new Error(`AI provider request failed for model ${config.model}: ${await response.text()}`);
+            const body = (await response.json());
+            const content = body.choices?.[0]?.message?.content;
+            if (typeof content !== "string")
+                throw new Error(`AI provider ${config.model} returned no message content`);
+            return content;
+        },
+    };
+}
 export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path))) {
     const projectRoot = resolve(root);
     return {

package/dist/recommendations.d.ts

@@ -16,5 +16,20 @@ export type CapabilityRecommendation = {
     requires?: string[];
 };
 export declare function recommendCapabilities(profile: ProjectProfile): CapabilityRecommendation[];
+export type RecommendationRanking = {
+    id: string;
+    relevance: number;
+    confidence?: number;
+};
+export type RankedRecommendations = {
+    items: CapabilityRecommendation[];
+    ranking: RecommendationRanking[];
+    changedPositions: number;
+};
+export type DecisionRanker = (profile: ProjectProfile, recommendations: CapabilityRecommendation[]) => Promise<Record<string, {
+    relevance?: number;
+    confidence?: number;
+}>>;
+export declare function rankRecommendations(items: CapabilityRecommendation[], profile: ProjectProfile, ranker: DecisionRanker): Promise<RankedRecommendations>;
 export declare function resourcesForCapabilities(ids: string[]): RecommendedResource[];
-export declare function serializeRecommendations(items: CapabilityRecommendation[], selected?: string[]): string;
+export declare function serializeRecommendations(items: CapabilityRecommendation[], selected?: string[], ranking?: RecommendationRanking[]): string;

package/dist/recommendations.js

@@ -241,6 +241,32 @@ export function recommendCapabilities(profile) {
             : [];
     });
 }
+export async function rankRecommendations(items, profile, ranker) {
+    if (items.length === 0)
+        return { items: [], ranking: [], changedPositions: 0 };
+    const answers = await ranker(profile, items);
+    const ranking = [];
+    const relevanceById = new Map();
+    for (const item of items) {
+        const answer = answers[item.id];
+        const relevance = answer?.relevance !== undefined && Number.isFinite(answer.relevance)
+            ? answer.relevance
+            : undefined;
+        relevanceById.set(item.id, relevance);
+        if (relevance !== undefined)
+            ranking.push({
+                id: item.id,
+                relevance,
+                ...(answer?.confidence !== undefined ? { confidence: answer.confidence } : {}),
+            });
+    }
+    const ordered = [...items].sort((a, b) => (relevanceById.get(b.id) ?? -1) - (relevanceById.get(a.id) ?? -1));
+    let changedPositions = 0;
+    for (let index = 0; index < ordered.length; index += 1)
+        if (ordered[index].id !== items[index].id)
+            changedPositions += 1;
+    return { items: ordered, ranking, changedPositions };
+}
 export function resourcesForCapabilities(ids) {
     const normalizedIds = ids.map((id) => (id === "vitest-testing" ? "verification" : id));
     const selectedCapabilities = new Set(CATALOG.filter(({ id }) => normalizedIds.includes(id)).map(({ id }) => id));
@@ -252,9 +278,14 @@ export function resourcesForCapabilities(ids) {
         ...new Map(resources.map((resource) => [`${resource.type}/${resource.id}`, resource])).values(),
     ];
 }
-export function serializeRecommendations(items, selected = []) {
+export function serializeRecommendations(items, selected = [], ranking = []) {
+    const rankingById = new Map(ranking.map((entry) => [entry.id, entry]));
     return `schema: 1\nrecommendations:\n${items
-        .map((item) => `  - id: ${item.id}\n    provider: ${item.provider}\n    confidence: ${item.confidence}\n    selected: ${selected.includes(item.id)}\n    requires: [${(item.requires ?? []).join(", ")}]\n    resources: [${item.resources.map(({ type, id }) => `${type}/${id}`).join(", ")}]\n    selected_resources: [${item.resources
+        .map((item) => `  - id: ${item.id}\n    provider: ${item.provider}\n    confidence: ${item.confidence}${rankingById.has(item.id)
+        ? `\n    decision_relevance: ${rankingById.get(item.id)?.relevance}${rankingById.get(item.id)?.confidence !== undefined
+            ? `\n    decision_confidence: ${rankingById.get(item.id)?.confidence}`
+            : ""}`
+        : ""}\n    selected: ${selected.includes(item.id)}\n    requires: [${(item.requires ?? []).join(", ")}]\n    resources: [${item.resources.map(({ type, id }) => `${type}/${id}`).join(", ")}]\n    selected_resources: [${item.resources
         .filter(({ type, id }) => selected.includes(`${type}/${id}`))
         .map(({ type, id }) => `${type}/${id}`)
         .join(", ")}]\n    evidence: [${item.evidence.map((evidence) => `"${evidence}"`).join(", ")}]\n    rationale: ${item.rationale}`)

package/dist/semantic.d.ts

@@ -5,6 +5,7 @@ export type SemanticConfig = {
     baseUrl: string;
     chunkChars: number;
     topK: number;
+    excludeLockfiles: boolean;
 };
 export type SemanticIndexChunk = {
     file: string;
@@ -21,6 +22,17 @@ export type SemanticMatch = {
     score: number;
     excerpt: string;
 };
+export type RerankedMatch = SemanticMatch & {
+    rerankScore?: number;
+};
+export type RerankOutcome = {
+    matches: RerankedMatch[];
+    changedPositions: number;
+};
+export type DecisionReranker = (query: string, candidates: {
+    id: string;
+    text: string;
+}[]) => Promise<Record<string, number | undefined>>;
 export type EmbeddingProvider = {
     available(): Promise<boolean>;
     embed(texts: string[]): Promise<number[][]>;
@@ -28,14 +40,19 @@ export type EmbeddingProvider = {
 export declare const SEMANTIC_CONFIG_PATH = "semantic.yml";
 export declare const SEMANTIC_INDEX_PATH = "semantic/index.json";
 export declare const DEFAULT_SEMANTIC_CONFIG: SemanticConfig;
+export declare const SEMANTIC_LOCKFILE_NAMES: Set<string>;
+export declare function isExcludedIndexFile(file: string): boolean;
 export declare function parseSemanticMapping(raw: unknown): SemanticConfig;
 export declare function serializeSemanticConfig(config: SemanticConfig): string;
 export declare function loadSemanticConfig(fs: FileSystem, aiwPath: string): SemanticConfig | undefined;
 export declare function parseSemanticConfig(text: string): SemanticConfig;
-export declare function createOllamaEmbeddingProvider(config: SemanticConfig): EmbeddingProvider;
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare function createOllamaEmbeddingProvider(config: SemanticConfig, fetchImpl?: FetchLike): EmbeddingProvider;
 export declare function chunkText(content: string, chunkChars: number): string[];
 export declare function cosineSimilarity(a: number[], b: number[]): number;
 export declare function buildSemanticIndex(files: string[], readContent: (file: string) => Promise<string | undefined>, provider: EmbeddingProvider, config: SemanticConfig): Promise<SemanticIndex>;
 export declare function serializeSemanticIndex(index: SemanticIndex): string;
 export declare function parseSemanticIndex(text: string): SemanticIndex;
 export declare function querySemanticIndex(index: SemanticIndex, query: string, provider: EmbeddingProvider, config: SemanticConfig): Promise<SemanticMatch[]>;
+export declare function rerankSemanticMatches(matches: SemanticMatch[], query: string, reranker: DecisionReranker): Promise<RerankOutcome>;
+export {};

package/dist/semantic.js

@@ -8,7 +8,28 @@ export const DEFAULT_SEMANTIC_CONFIG = {
     baseUrl: "http://localhost:11434",
     chunkChars: 1200,
     topK: 8,
+    excludeLockfiles: true,
 };
+export const SEMANTIC_LOCKFILE_NAMES = new Set([
+    "bun.lock",
+    "bun.lockb",
+    "cargo.lock",
+    "composer.lock",
+    "deno.lock",
+    "flake.lock",
+    "gemfile.lock",
+    "go.sum",
+    "npm-shrinkwrap.json",
+    "package-lock.json",
+    "pipfile.lock",
+    "pnpm-lock.yaml",
+    "poetry.lock",
+    "uv.lock",
+    "yarn.lock",
+]);
+export function isExcludedIndexFile(file) {
+    return SEMANTIC_LOCKFILE_NAMES.has(file.split("/").pop()?.toLowerCase() ?? "");
+}
 export function parseSemanticMapping(raw) {
     if (!raw || typeof raw !== "object")
         throw new Error("semantic must be a YAML mapping");
@@ -18,10 +39,14 @@ export function parseSemanticMapping(raw) {
     const baseUrl = raw2.baseUrl;
     const chunkChars = raw2.chunkChars;
     const topK = raw2.topK;
+    const rawExclude = raw2.excludeLockfiles;
     if (typeof enabled !== "boolean")
         throw new Error("semantic.enabled must be a boolean");
+    const excludeLockfiles = rawExclude === undefined ? true : rawExclude;
     if (!enabled)
-        return { ...DEFAULT_SEMANTIC_CONFIG, enabled: false };
+        return { ...DEFAULT_SEMANTIC_CONFIG, enabled: false, excludeLockfiles };
+    if (rawExclude !== undefined && typeof rawExclude !== "boolean")
+        throw new Error("semantic.excludeLockfiles must be a boolean");
     if (typeof model !== "string" || model.trim() === "")
         throw new Error("semantic.model must be a non-empty string when semantic mapping is enabled");
     if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
@@ -32,10 +57,17 @@ export function parseSemanticMapping(raw) {
         throw new Error("semantic.chunkChars must be an integer of at least 200");
     if (typeof parsedTopK !== "number" || !Number.isInteger(parsedTopK) || parsedTopK < 1)
         throw new Error("semantic.topK must be a positive integer");
-    return { enabled: true, model, baseUrl, chunkChars: parsedChunk, topK: parsedTopK };
+    return {
+        enabled: true,
+        model,
+        baseUrl,
+        chunkChars: parsedChunk,
+        topK: parsedTopK,
+        excludeLockfiles,
+    };
 }
 export function serializeSemanticConfig(config) {
-    return `semantic:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}\n  chunkChars: ${config.chunkChars}\n  topK: ${config.topK}\n`;
+    return `semantic:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}\n  chunkChars: ${config.chunkChars}\n  topK: ${config.topK}\n  excludeLockfiles: ${config.excludeLockfiles}\n`;
 }
 export function loadSemanticConfig(fs, aiwPath) {
     const settings = loadSettings(fs, aiwPath);
@@ -56,8 +88,8 @@ function parseSemanticDocument(text) {
 export function parseSemanticConfig(text) {
     return parseSemanticDocument(text);
 }
-export function createOllamaEmbeddingProvider(config) {
-    const fetchImpl = (url, init) => fetch(url, init);
+const EMBED_BATCH_SIZE = 64;
+export function createOllamaEmbeddingProvider(config, fetchImpl = (url, init) => fetch(url, init)) {
     return {
         async available() {
             try {
@@ -76,18 +108,21 @@ export function createOllamaEmbeddingProvider(config) {
         },
         async embed(texts) {
             const vectors = [];
-            for (const text of texts) {
-                const response = await fetchImpl(`${config.baseUrl}/api/embeddings`, {
+            for (let offset = 0; offset < texts.length; offset += EMBED_BATCH_SIZE) {
+                const batch = texts.slice(offset, offset + EMBED_BATCH_SIZE);
+                const response = await fetchImpl(`${config.baseUrl}/api/embed`, {
                     method: "POST",
                     headers: { "content-type": "application/json" },
-                    body: JSON.stringify({ model: config.model, prompt: text }),
+                    body: JSON.stringify({ model: config.model, input: batch }),
                 });
                 if (!response.ok)
                     throw new Error(`Embedding request failed for model ${config.model}`);
                 const body = (await response.json());
-                if (!Array.isArray(body.embedding) || body.embedding.some((v) => typeof v !== "number"))
-                    throw new Error(`Embedding model ${config.model} returned an invalid vector`);
-                vectors.push(body.embedding);
+                if (!Array.isArray(body.embeddings) ||
+                    body.embeddings.length !== batch.length ||
+                    body.embeddings.some((vector) => !Array.isArray(vector) || vector.some((v) => typeof v !== "number")))
+                    throw new Error(`Embedding model ${config.model} returned invalid vectors`);
+                vectors.push(...body.embeddings);
             }
             return vectors;
         },
@@ -127,6 +162,8 @@ export function cosineSimilarity(a, b) {
 export async function buildSemanticIndex(files, readContent, provider, config) {
     const entries = [];
     for (const file of files) {
+        if (config.excludeLockfiles && isExcludedIndexFile(file))
+            continue;
         const content = await readContent(file);
         if (content === undefined)
             continue;
@@ -173,3 +210,24 @@ export async function querySemanticIndex(index, query, provider, config) {
         .sort((a, b) => b.score - a.score)
         .slice(0, config.topK);
 }
+export async function rerankSemanticMatches(matches, query, reranker) {
+    if (matches.length === 0)
+        return { matches: [], changedPositions: 0 };
+    const candidates = matches.map((match, index) => ({
+        id: `match_${index}`,
+        text: `${match.file}\n${match.excerpt}`,
+    }));
+    const scores = await reranker(query, candidates);
+    const reranked = matches.map((match, index) => {
+        const rerankScore = scores[`match_${index}`];
+        return Number.isFinite(rerankScore)
+            ? { ...match, rerankScore: rerankScore }
+            : { ...match };
+    });
+    reranked.sort((a, b) => (b.rerankScore ?? b.score) - (a.rerankScore ?? a.score));
+    let changedPositions = 0;
+    for (let index = 0; index < reranked.length; index += 1)
+        if (reranked[index].file !== matches[index].file)
+            changedPositions += 1;
+    return { matches: reranked, changedPositions };
+}

package/dist/services.d.ts

@@ -1,12 +1,14 @@
 import type { ProjectProfile } from "./profile.js";
+import type { EmbeddingProvider } from "./semantic.js";
 import type { ProjectScan } from "./scanner.js";
 import type { CapabilityRecommendation } from "./recommendations.js";
-import type { Interpreter } from "./interpreter.js";
+import type { Interpreter, AiProvider } from "./interpreter.js";
 import type { CommandExecutor } from "./vercel-skills.js";
 import type { CommandResult, FileSystem } from "./types.js";
 import type { PackageSourceLoader } from "./providers.js";
 import type { PrivateRegistryClient } from "./team-configuration.js";
 import type { PolicyTracking } from "./policy-gate.js";
+import type { DecisionProvider } from "./decision.js";
 import type { TelemetryClient } from "./telemetry.js";
 import type { DashboardHandle } from "./dashboard.js";
 import type { AgentOrchestrator } from "./orchestration.js";
@@ -35,6 +37,9 @@ export interface WorkflowDependencies {
         start(root: string, port: number): Promise<DashboardHandle>;
     };
     orchestrator?: AgentOrchestrator;
+    embeddingProvider?: EmbeddingProvider;
+    aiProvider?: AiProvider;
+    decisionProvider?: DecisionProvider;
 }
 export interface WorkflowService {
     execute(args: string[], root: string, fs: FileSystem): Promise<CommandResult>;

package/dist/telemetry.d.ts

@@ -14,10 +14,18 @@ export interface TelemetryClient {
     record(event: TelemetryEvent): Promise<void>;
 }
 export declare const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig;
+export declare const TELEMETRY_CONSENT_PROMPT = "Enable anonymous telemetry? Each event contains only the command name and its outcome (success or failure) - never arguments, file paths, or file contents. [y/N] ";
+export declare function offerTelemetryConsent(fs: FileSystem, aiwPath: string, answer: (question: string) => Promise<string>): Promise<boolean>;
 export declare function parseTelemetryMapping(raw: unknown): TelemetryConfig;
 export declare function serializeTelemetryMapping(config: TelemetryConfig): unknown;
 export declare function loadTelemetryConfig(fs: FileSystem, aiwPath: string): TelemetryConfig;
 export declare function parseTelemetryConfig(content: string): TelemetryConfig;
 export declare function serializeTelemetryConfig(config: TelemetryConfig): string;
 export declare function createTelemetryEvent(command: string | undefined, result: CommandResult, config: TelemetryConfig): TelemetryEvent | undefined;
+export declare const TELEMETRY_BUFFER_FILE = "telemetry-buffer.jsonl";
+export declare const TELEMETRY_BUFFER_CAP = 200;
+export declare function telemetryBufferPath(aiwPath: string): string;
+export declare function readTelemetryBuffer(fs: FileSystem, aiwPath: string): TelemetryEvent[];
+export declare function appendTelemetryBuffer(fs: FileSystem, aiwPath: string, event: TelemetryEvent): void;
+export declare function purgeTelemetryBuffer(fs: FileSystem, aiwPath: string): void;
 export declare function recordConfiguredTelemetry(fs: FileSystem, aiwPath: string, client: TelemetryClient | undefined, command: string | undefined, result: CommandResult): Promise<void>;

package/dist/telemetry.js

@@ -1,10 +1,25 @@
-import { loadSettings } from "./settings.js";
+import { loadSettings, saveSettingsSection } from "./settings.js";
 export const DEFAULT_TELEMETRY_CONFIG = {
     schema: 1,
     enabled: false,
     includeCommand: true,
     includeOutcome: true,
 };
+export const TELEMETRY_CONSENT_PROMPT = "Enable anonymous telemetry? Each event contains only the command name and its outcome (success or failure) - never arguments, file paths, or file contents. [y/N] ";
+export async function offerTelemetryConsent(fs, aiwPath, answer) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings !== undefined && "telemetry" in settings)
+        return loadTelemetryConfig(fs, aiwPath).enabled;
+    const response = (await answer(TELEMETRY_CONSENT_PROMPT)).trim().toLowerCase();
+    const enabled = response === "y" || response === "yes";
+    saveSettingsSection(fs, aiwPath, "telemetry", serializeTelemetryMapping({
+        schema: 1,
+        enabled,
+        includeCommand: true,
+        includeOutcome: true,
+    }));
+    return enabled;
+}
 const TELEMETRY_COMMANDS = new Set([
     "adr",
     "audit-package",
@@ -110,9 +125,54 @@ export function createTelemetryEvent(command, result, config) {
         ...(config.includeOutcome ? { outcome: result.exitCode === 0 ? "success" : "failure" } : {}),
     };
 }
+export const TELEMETRY_BUFFER_FILE = "telemetry-buffer.jsonl";
+export const TELEMETRY_BUFFER_CAP = 200;
+export function telemetryBufferPath(aiwPath) {
+    return `${aiwPath}/${TELEMETRY_BUFFER_FILE}`;
+}
+export function readTelemetryBuffer(fs, aiwPath) {
+    const path = telemetryBufferPath(aiwPath);
+    if (!fs.exists(path))
+        return [];
+    return fs
+        .read(path)
+        .split(/\r?\n/)
+        .filter((line) => line.trim().length > 0)
+        .map((line) => {
+        const parsed = JSON.parse(line);
+        if (parsed.schema !== 1)
+            throw new Error("Invalid buffered telemetry event");
+        return parsed;
+    });
+}
+export function appendTelemetryBuffer(fs, aiwPath, event) {
+    const buffered = [...readTelemetryBuffer(fs, aiwPath), event];
+    const rotated = buffered.slice(Math.max(0, buffered.length - TELEMETRY_BUFFER_CAP));
+    fs.write(telemetryBufferPath(aiwPath), `${rotated.map((item) => JSON.stringify(item)).join("\n")}\n`);
+}
+export function purgeTelemetryBuffer(fs, aiwPath) {
+    const path = telemetryBufferPath(aiwPath);
+    if (fs.exists(path) && fs.remove)
+        fs.remove(path);
+}
 export async function recordConfiguredTelemetry(fs, aiwPath, client, command, result) {
-    if (!client)
+    if (!client) {
+        try {
+            const config = loadTelemetryConfig(fs, aiwPath);
+            const settings = loadSettings(fs, aiwPath);
+            const configured = (settings !== undefined && "telemetry" in settings) ||
+                fs.exists(`${aiwPath}/telemetry.yml`);
+            if (configured) {
+                const event = createTelemetryEvent(command, result, config);
+                if (event)
+                    appendTelemetryBuffer(fs, aiwPath, event);
+            }
+        }
+        catch {
+            // Telemetry must never affect the requested workflow operation.
+        }
         return;
+    }
     try {
         const config = loadTelemetryConfig(fs, aiwPath);
         const settings = loadSettings(fs, aiwPath);

package/dist/workflow.d.ts

@@ -3,4 +3,5 @@ import type { WorkflowDependencies } from "./services.js";
 export type WorkflowServices = WorkflowDependencies;
 export declare function runCommand(args: string[], root: string, fs: FileSystem, services?: WorkflowServices): Promise<CommandResult>;
 export type ConfirmQuestion = (question: string) => Promise<string>;
-export declare function configureOptionalModels(fs: FileSystem, aiwPath: string, answer: ConfirmQuestion): Promise<string[]>;
+export type ModelProbe = (baseUrl: string) => Promise<string[] | undefined>;
+export declare function configureOptionalModels(fs: FileSystem, aiwPath: string, answer: ConfirmQuestion, listModels?: ModelProbe): Promise<string[]>;

package/dist/workflow.js

@@ -7,8 +7,8 @@ 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 { 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";
@@ -21,8 +21,8 @@ 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 { buildEvidenceTriageRequest, buildRecommendationRankingRequest, buildSemanticRerankRequest, createOllamaDecisionProvider, DEFAULT_DECISION_CONFIG, loadDecisionConfig, } from "./decision.js";
+import { buildSemanticIndex, createOllamaEmbeddingProvider, DEFAULT_SEMANTIC_CONFIG, 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 +42,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 +331,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 +347,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,9 +441,39 @@ 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;
+            if (!interpreter) {
+                const aiConfig = loadAiProviderConfig(fs, aiw);
+                if (aiConfig?.enabled)
+                    interpreter = createProjectInterpreter(root, services.aiProvider ?? createOpenAiCompatibleProvider(aiConfig));
+            }
+            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));
+                            }
+                        }
+                    }
+                    catch {
+                        // An unreadable index keeps the scan deterministic with alphabetical scoping.
+                    }
+                }
+                const inferred = await interpreter.interpret(createInterpretationRequest(profile, scopedFiles, 4000, priorityFiles));
                 profile.facts = mergeFacts(profile.facts, inferred);
             }
             const overrides = readFactOverrides(fs, aiw);
@@ -442,7 +489,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,
@@ -511,7 +558,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 +577,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 +598,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 +996,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 +1032,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,35 +1899,81 @@ function approvalArtifactPath(aiw, stage) {
     };
     return resolve(aiw, paths[stage]);
 }
-export async function configureOptionalModels(fs, aiwPath, answer) {
+async function defaultModelProbe(baseUrl) {
+    try {
+        const response = await fetch(`${baseUrl}/api/tags`);
+        if (!response.ok)
+            return undefined;
+        const body = (await response.json());
+        const names = [
+            ...new Set((body.models ?? [])
+                .map((entry) => entry.name)
+                .filter((name) => typeof name === "string")),
+        ];
+        return names.length > 0 ? names.sort() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultModelFor(available, fallback) {
+    if (!available || available.length === 0)
+        return fallback;
+    return available.includes(fallback) ? fallback : available[0];
+}
+export async function configureOptionalModels(fs, aiwPath, answer, listModels = defaultModelProbe) {
     const enabled = [];
     const settings = loadSettings(fs, aiwPath) ?? {};
+    let availableModels;
+    if (!("semantic" in settings) || !("decision" in settings))
+        availableModels = await listModels(DEFAULT_SEMANTIC_CONFIG.baseUrl);
     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] `))
+        const defaultEmbedding = defaultModelFor(availableModels, DEFAULT_SEMANTIC_CONFIG.model);
+        const catalog = availableModels && availableModels.length > 0
+            ? ` Available embedding models: ${availableModels.join(", ")}.`
+            : "";
+        const response = (await answer(`Enable semantic mapping with a local embedding model (default: ${defaultEmbedding} at ${DEFAULT_SEMANTIC_CONFIG.baseUrl})?${catalog} [y/N] `))
             .trim()
             .toLowerCase();
         if (response === "y" || response === "yes") {
+            let model = defaultEmbedding;
+            if (availableModels && availableModels.length > 0) {
+                const selection = (await answer(`Use which embedding model? [${defaultEmbedding}] `)).trim();
+                if (selection.length > 0 && availableModels.includes(selection))
+                    model = selection;
+            }
             saveSettingsSection(fs, aiwPath, "semantic", {
                 enabled: true,
-                model: DEFAULT_SEMANTIC_CONFIG.model,
+                model,
                 baseUrl: DEFAULT_SEMANTIC_CONFIG.baseUrl,
                 chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
                 topK: DEFAULT_SEMANTIC_CONFIG.topK,
+                excludeLockfiles: DEFAULT_SEMANTIC_CONFIG.excludeLockfiles,
             });
-            enabled.push(`semantic (${DEFAULT_SEMANTIC_CONFIG.model})`);
+            enabled.push(`semantic (${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] `))
+        const defaultDecision = defaultModelFor(availableModels, DEFAULT_DECISION_CONFIG.model);
+        const catalog = availableModels && availableModels.length > 0
+            ? ` Available decision models: ${availableModels.join(", ")}.`
+            : "";
+        const response = (await answer(`Enable advisory decision triage with a local decision model (default: ${defaultDecision} at ${DEFAULT_DECISION_CONFIG.baseUrl})?${catalog} [y/N] `))
             .trim()
             .toLowerCase();
         if (response === "y" || response === "yes") {
+            let model = defaultDecision;
+            if (availableModels && availableModels.length > 0) {
+                const selection = (await answer(`Use which decision model? [${defaultDecision}] `)).trim();
+                if (selection.length > 0 && availableModels.includes(selection))
+                    model = selection;
+            }
             saveSettingsSection(fs, aiwPath, "decision", {
                 enabled: true,
-                model: DEFAULT_DECISION_CONFIG.model,
+                model,
                 baseUrl: DEFAULT_DECISION_CONFIG.baseUrl,
             });
-            enabled.push(`decision (${DEFAULT_DECISION_CONFIG.model})`);
+            enabled.push(`decision (${model})`);
         }
     }
     return enabled;
@@ -2193,6 +2343,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/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

@@ -34,7 +34,7 @@ Observed behavior on real plans: an evidence-free plan scored `gate: ready` with
 
 ## 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/semantic-mapping.md

@@ -1,6 +1,6 @@
 # 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. During an interactive `aiw install`, the installer probes the configured Ollama endpoint (`GET /api/tags`), lists the models actually available, and offers to create this configuration — the user's selected model is recorded in `.aiw/settings.yml`; when no server or models are found, the installer reports the optional capability and continues with defaults. Answering `n`, or installing non-interactively, leaves the section absent.
 
 ## Configuration
 
@@ -13,6 +13,7 @@ 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)
 ```
 
 - `enabled: false` (or a missing file) disables semantic mapping entirely; scans stay deterministic and make no network request.
@@ -22,18 +23,28 @@ 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.
 
 ## 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.5.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {