@multileaf/ai-workflow 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-10-13
+
+### Added
+
+- Root context rendering: syncing a non-empty resource selection now writes the generated project context to the active target's root file (`AGENTS.md` for Codex/Cursor, `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI), and `aiw target` migrates it between targets. The file is owned by AI Workflow, listed in the sync preview, and an existing hand-written root context is reported as a conflict instead of being overwritten.
+- Decision-model usage in `aiw recommend` is now recorded in `.aiw/usage.yml` (`recommend.decision`) alongside the scan stages.
+
+### Changed
+
+- Release workflows require a single protected-environment approval: the `github-release` job no longer declares the `npm` environment it did not need.
+
+### Added
+
+- Root context rendering: syncing a non-empty resource selection now writes the generated project context to the active target's root file (`AGENTS.md` for Codex/Cursor, `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI), and `aiw target` migrates it between targets. The file is owned by AI Workflow, listed in the sync preview, and an existing hand-written root context is reported as a conflict instead of being overwritten.
+
+## [0.6.0] - 2026-10-13
+
+### Added
+
+- Guided provider onboarding during interactive `aiw install`: each capability (semantic embedding, then decision triage) asks whether to configure it, offers Ollama or an external OpenAI-compatible provider (external only when Ollama is unreachable), lists the locally available models (embedding-only filtering for semantic), asks permission to run `ollama pull embeddinggemma-2` when no embedding models exist, collects endpoint URL, model name, and an optional token environment variable for external providers, and validates the setup with a live request before saving — with retry or skip on failure.
+- External provider support: `semantic` and `decision` settings accept `apiKeyEnv` (an uppercase environment variable name); the token is read from the environment at call time and never stored. Semantic requests go to `<baseUrl>/v1/embeddings` with bearer authentication and decision requests send `Authorization` headers.
+- Model usage reporting: every `aiw scan` states which models were actually used — embedding (chunks indexed or retrieval queries, batch request count, estimated tokens) and interpreter (model, facts inferred, scoped files, estimated tokens) — or reports `Models used: none (deterministic scan).`
+- Per-stage token estimates recorded in `.aiw/usage.yml` (`scan.embedding`, `scan.interpreter`) and inspectable with `aiw token-usage`. Token counts are local project state; telemetry never carries them.
+
+### Fixed
+
+- Interactive onboarding messages shortened to single-line prompts.
+- Embedding-model classification during onboarding now requires positive evidence (model name contains "embed" or Ollama family "embedding"); the previous heuristic misclassified `gpt-oss:20b` as an embedding model.
+
 ## [0.5.0] - 2026-10-08
 
 ### Added
@@ -20,6 +49,7 @@ All notable changes to this project are documented in this file. The format foll
 ### 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/README.md

@@ -19,7 +19,7 @@ AI-assisted development often relies on implicit prompts, duplicated configurati
 
 ## Installation
 
-The published package supports Node.js 18 or newer. Full development checks require Node.js 20.19 or newer for the current lint and test toolchain; CI runs on Node.js 20 and release validation runs on Node.js 24. Node.js 18 remains the declared runtime floor but is not currently in the release validation matrix.
+The published package supports Node.js 18 or newer. Full development checks require Node.js 20.19 or newer for the current lint and test toolchain; CI and release validation run on Node.js 24. Node.js 18 remains the declared runtime floor but is not currently in the release validation matrix.
 
 ```bash
 npx @multileaf/ai-workflow install --target codex
@@ -27,6 +27,8 @@ npx @multileaf/ai-workflow install --target codex
 
 Then run `/ai-init` in Codex. The bootstrap scans the repository, explains project-specific recommendations, and waits for the user's selections before installing optional resources.
 
+During an interactive install, AI Workflow also offers optional local capabilities after the base installation: it probes the configured Ollama endpoint, offers Ollama or an external OpenAI-compatible provider (endpoint URL plus an optional token environment variable), lists the embedding and decision models actually available, can run `ollama pull` for a default embedding model when none exist, and validates the chosen setup with a live request before recording it in `.aiw/settings.yml`. It then asks for telemetry consent with an explicit default of No (see [Privacy and security](#privacy-and-security)). Non-interactive installs skip every prompt.
+
 Supported targets are `codex`, `claude`, `cursor`, `gemini`, `copilot`, and `universal`. Every command uses the same entry point:
 
 ```bash
@@ -61,7 +63,7 @@ For a Codex installation, the base layout is:
 
 `.aiw/` stores the provider-neutral manifest, profile, lockfile, checkpoints, bootstrap skill, selected resources, and generated working artifacts. ADRs are stored under `.context/adrs/`. The installer intentionally adds only `ai-init` and the base project state.
 
-Run `/ai-init` in the selected coding agent to scan the project and review evidence-based recommendations for skills, rules, agents, hooks, and templates. AI Workflow installs only the resources the user selects, then generates project-specific quality guidance from the detected stack and tools. Existing user files are preserved; conflicts are reported instead of overwritten. Hook resources are rendered according to each adapter's native or compatibility support.
+Run `/ai-init` in the selected coding agent to scan the project and review evidence-based recommendations for skills, rules, agents, hooks, and templates. AI Workflow installs only the resources the user selects, then generates project-specific quality guidance from the detected stack and tools. Syncing a non-empty selection also renders a root context file for the active target — `AGENTS.md` (Codex/Cursor), `CLAUDE.md` (Claude Code), `GEMINI.md` (Gemini CLI) — with the confirmed profile, quality commands, and pointers to `.aiw/` state; `aiw target` migrates it between targets. An existing hand-written root context file is reported as a conflict and never overwritten. Existing user files are preserved; conflicts are reported instead of overwritten. Hook resources are rendered according to each adapter's native or compatibility support.
 
 The installer does not modify `.gitignore`. Add `.aiw/generated/` yourself if generated specifications, plans, and artifacts should remain local. Versioned files under `.aiw/checkpoints/` are designed to remain reviewable project history.
 
@@ -241,6 +243,18 @@ Analysis uses two complementary layers:
 
 Detected facts cannot be replaced by conflicting AI output. Inferred facts remain unconfirmed until the user accepts, rejects, or edits them. Context selection excludes known sensitive filenames, binaries, dependencies, Git internals, generated output, and checkpoints, then applies pattern-based redaction. This is a defense-in-depth filter, not a general secret scanner; review eligible text before enabling an external AI provider.
 
+The interpreter accepts an injected provider from a host application, or a built-in OpenAI-compatible provider configured through an `ai` section in `.aiw/settings.yml` — for example a local Ollama model such as `gpt-oss:20b` — so scans can interpret projects without any host integration. Without the section, scans stay deterministic and offline. See [Project Intelligence](docs/project-intelligence.md).
+
+## Optional local models
+
+AI Workflow can use local models served by an OpenAI-compatible endpoint (Ollama by default) for three opt-in capabilities, all gated by `.aiw/settings.yml` sections and disabled by default:
+
+- **Semantic mapping** (`semantic` section): `aiw scan` builds a versioned chunk index with batched embedding requests, skipping lockfiles and generated vendor manifests; `aiw semantic query` returns ranked matches and can optionally re-rank them with the decision model (`--rerank`). When an index exists, the AI interpreter's context is scoped to deterministic key files plus the top semantically relevant files, reducing token usage. See [Semantic Mapping](docs/semantic-mapping.md).
+- **Advisory decision triage** (`decision` section): `aiw decision triage` returns advisory evidence-completeness and gate decisions with confidence, and `aiw recommend` orders capability recommendations by decision-model relevance to the confirmed profile. Ranking is advisory and never changes evidence states or bypasses human approval. See [Decision Model Evaluation](docs/decision-model-evaluation.md).
+- **Built-in AI interpretation** (`ai` section): the scoped project interpreter works without a host-injected provider.
+
+All model-driven features verify model availability before use and degrade to fully deterministic behavior when unconfigured. Every `aiw scan` reports which models were actually used — embedding (chunks indexed or retrieval queries) and interpreter (facts inferred, estimated tokens) — and records token estimates per stage in `.aiw/usage.yml`, inspectable with `aiw token-usage`. Token accounting is local project state; telemetry never carries token counts or any content.
+
 ## Resource packages and recommendations
 
 Resources are distributed as versioned packages that may contain:
@@ -326,10 +340,10 @@ The typed SDK is available from `@multileaf/ai-workflow/plugin-sdk`. It exports
 
 ## Privacy and security
 
-Telemetry is disabled by default and requires explicit consent. It records only approved aggregate fields through an injectable transport.
+Telemetry is disabled by default and requires explicit consent — offered once during interactive installation with an explicit default of No. Each event contains only the command name and its outcome; never arguments, file paths, or file contents. When telemetry is enabled but no host transport is configured, events accumulate in a rotated local buffer (`.aiw/telemetry-buffer.jsonl`, 200-event cap) that `aiw telemetry status --verbose` can inspect and `aiw telemetry disable` purges.
 
 ```bash
-npx @multileaf/ai-workflow telemetry status
+npx @multileaf/ai-workflow telemetry status --verbose
 npx @multileaf/ai-workflow telemetry enable
 npx @multileaf/ai-workflow telemetry disable
 ```
@@ -364,6 +378,9 @@ npm run release:check
 - [Quality and testing](docs/quality.md)
 - [Token efficiency](docs/token-efficiency.md)
 - [Multi-agent orchestration](docs/orchestration.md)
+- [Semantic mapping](docs/semantic-mapping.md)
+- [Decision model evaluation](docs/decision-model-evaluation.md)
+- [Telemetry and privacy](docs/telemetry.md)
 - [Release process](docs/release-process.md)
 
 ## License

package/dist/decision.d.ts

@@ -3,6 +3,7 @@ export type DecisionConfig = {
     enabled: boolean;
     model: string;
     baseUrl: string;
+    apiKeyEnv?: string;
 };
 export type DecisionQuestion = {
     type: "noul";
@@ -47,7 +48,8 @@ export declare function serializeDecisionConfig(config: DecisionConfig): string;
 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;
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare function createOllamaDecisionProvider(config: DecisionConfig, fetchImpl?: FetchLike, env?: Readonly<Record<string, string | undefined>>): DecisionProvider;
 export type RecommendationRankingCandidate = {
     id: string;
     rationale: string;
@@ -60,3 +62,4 @@ export type SemanticRerankCandidate = {
 };
 export declare function buildSemanticRerankRequest(query: string, candidates: SemanticRerankCandidate[]): DecisionRequest;
 export declare function buildEvidenceTriageRequest(artifact: string): DecisionRequest;
+export {};

package/dist/decision.js

@@ -13,18 +13,22 @@ export function parseDecisionMapping(raw) {
     const enabled = record.enabled;
     const model = record.model;
     const baseUrl = record.baseUrl;
+    const apiKeyEnv = record.apiKeyEnv;
     if (typeof enabled !== "boolean")
         throw new Error("decision.enabled must be a boolean");
     if (!enabled)
         return { ...DEFAULT_DECISION_CONFIG, enabled: false };
+    if (apiKeyEnv !== undefined &&
+        (typeof apiKeyEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(apiKeyEnv)))
+        throw new Error("decision.apiKeyEnv must be an uppercase environment variable name");
     if (typeof model !== "string" || model.trim() === "")
         throw new Error("decision.model must be a non-empty string when decision mapping is enabled");
     if (typeof baseUrl !== "string" || !/^https?:\/\//i.test(baseUrl))
         throw new Error("decision.baseUrl must be an http(s) URL when decision mapping is enabled");
-    return { enabled: true, model, baseUrl };
+    return { enabled: true, model, baseUrl, ...(apiKeyEnv ? { apiKeyEnv } : {}) };
 }
 export function serializeDecisionConfig(config) {
-    return `decision:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}\n`;
+    return `decision:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}${config.apiKeyEnv ? `\n  apiKeyEnv: ${config.apiKeyEnv}` : ""}\n`;
 }
 export function parseDecisionConfig(text) {
     const document = parseDocument(text);
@@ -60,11 +64,19 @@ export function parseDecisionResponse(text) {
         result[key] = parseAnswer(value);
     return { model: parsed.model, answers: result };
 }
-export function createOllamaDecisionProvider(config) {
+export function createOllamaDecisionProvider(config, fetchImpl = (url, init) => fetch(url, init), env = process.env) {
+    const externalToken = config.apiKeyEnv ? env[config.apiKeyEnv] : undefined;
+    const authHeaders = (extra = {}) => externalToken ? { ...extra, authorization: `Bearer ${externalToken}` } : extra;
     return {
         async available() {
             try {
-                const response = await fetch(`${config.baseUrl}/api/tags`);
+                if (config.apiKeyEnv !== undefined) {
+                    const response = await fetchImpl(`${config.baseUrl}/v1/models`, {
+                        headers: authHeaders(),
+                    });
+                    return response.ok;
+                }
+                const response = await fetchImpl(`${config.baseUrl}/api/tags`);
                 if (!response.ok)
                     return false;
                 const body = (await response.json());
@@ -81,9 +93,9 @@ export function createOllamaDecisionProvider(config) {
             const questionCount = Object.keys(request.questions).length;
             if (questionCount === 0 || questionCount > 64)
                 throw new Error("Decision requests must contain between 1 and 64 questions");
-            const response = await fetch(`${config.baseUrl}/v1/systemone`, {
+            const response = await fetchImpl(`${config.baseUrl}/v1/systemone`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: authHeaders({ "content-type": "application/json" }),
                 body: JSON.stringify({
                     model: config.model,
                     state: request.state,

package/dist/generator.js

@@ -23,6 +23,7 @@ export function generateProjectResources(profile, selected, write) {
         write(resolveGeneratedPath("agents/project-context.md"), `# Project Context\n\nThis project uses ${profile.frameworks.map((framework) => (framework === "nextjs" ? "Next.js" : framework)).join(", ")}. Follow the detected project structure and existing framework conventions.\n`);
     if (selected.length > 0) {
         write(resolveGeneratedPath("context/project-profile.md"), `# Confirmed Project Profile\n\n- Languages: ${profile.runtime.languages.join(", ") || "none detected"}\n- Frameworks: ${profile.frameworks.join(", ") || "none detected"}\n- Package manager: ${profile.packageManager}\n- All generated content is in English.\n`);
+        write(resolveGeneratedPath("context/root-context.md"), `# AI Workflow Project Context\n\nThis repository is managed by AI Workflow (\`.aiw/\` holds the neutral project state).\n\n- Languages: ${profile.runtime.languages.join(", ") || "none detected"}\n- Frameworks: ${profile.frameworks.join(", ") || "none detected"}\n- Package manager: ${profile.packageManager}${linterCommand ? `\n- Lint: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Format: \`${formatterCommand}\`` : ""}${uniqueTestCommands.map(({ scope, command }) => `\n- Tests (${scope}): \`${command}\``).join("")}\n\nBefore completing changes, run the project quality commands listed above. Follow installed AI Workflow skills, rules, and agents; the confirmed profile lives in \`.aiw/profile.yml\` and workflow evidence in \`.aiw/checkpoints/\`.\n`);
         write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${uniqueTestCommands.map(({ scope, command }) => `\n- ${scope} tests: \`${command}\``).join("")}\n`);
     }
 }

package/dist/migration.d.ts

@@ -3,7 +3,7 @@ import type { Target } from "./types.js";
 export type ResourceMigration = {
     source: string;
     destination: string;
-    type: ResourceType;
+    type: ResourceType | "context";
     id: string;
     neutralSource: boolean;
 };

package/dist/migration.js

@@ -2,6 +2,7 @@ import { parseDocument } from "yaml";
 import { isAbsolute, join } from "node:path";
 import { renderResourcePath } from "./adapter.js";
 import { RESOURCE_TYPES } from "./package-contract.js";
+const MIGRATABLE_TYPES = [...RESOURCE_TYPES, "context"];
 export function planNeutralResourceMigration(neutralRoot, relativeFiles, target) {
     const migrations = [];
     const diagnostics = [];
@@ -14,9 +15,7 @@ export function planNeutralResourceMigration(neutralRoot, relativeFiles, target)
             diagnostics.push({ path: relative, reason: "path is not normalized and project-relative" });
             continue;
         }
-        if (extra ||
-            parts.length !== 3 ||
-            !RESOURCE_TYPES.includes(candidateType)) {
+        if (extra || parts.length !== 3 || !MIGRATABLE_TYPES.includes(candidateType)) {
             diagnostics.push({ path: relative, reason: "unsupported neutral resource path" });
             continue;
         }
@@ -39,7 +38,9 @@ export function planNeutralResourceMigration(neutralRoot, relativeFiles, target)
         }
         migrations.push({
             source: join(neutralRoot, relative),
-            destination: renderResourcePath(target, type, id),
+            destination: type === "context"
+                ? renderResourcePath(target, type, id)
+                : renderResourcePath(target, type, id),
             type,
             id,
             neutralSource: target === "universal",

package/dist/model-onboarding.d.ts

@@ -0,0 +1,22 @@
+import type { FileSystem } from "./types.js";
+export type ConfirmQuestion = (question: string) => Promise<string>;
+export type OllamaModel = {
+    name: string;
+    embedding: boolean;
+};
+export type OnboardingRuntime = {
+    listOllamaModels(baseUrl: string): Promise<OllamaModel[] | undefined>;
+    pullOllamaModel(model: string): Promise<boolean>;
+    validateEmbedding(config: {
+        baseUrl: string;
+        model: string;
+        apiKeyEnv?: string;
+    }): Promise<boolean>;
+    validateDecision(config: {
+        baseUrl: string;
+        model: string;
+        apiKeyEnv?: string;
+    }): Promise<boolean>;
+};
+export declare const defaultOnboardingRuntime: OnboardingRuntime;
+export declare function configureOptionalModels(fs: FileSystem, aiwPath: string, answer: ConfirmQuestion, runtime?: OnboardingRuntime): Promise<string[]>;

package/dist/model-onboarding.js

@@ -0,0 +1,200 @@
+import { execFile } from "node:child_process";
+import { loadSettings, saveSettingsSection } from "./settings.js";
+import { DEFAULT_SEMANTIC_CONFIG, createOllamaEmbeddingProvider } from "./semantic.js";
+import { DEFAULT_DECISION_CONFIG, createOllamaDecisionProvider } from "./decision.js";
+const OLLAMA_BASE_URL = "http://localhost:11434";
+function isEmbeddingModel(name, families) {
+    if (name.toLowerCase().includes("embed"))
+        return true;
+    return families.some((family) => family.toLowerCase() === "embedding");
+}
+export const defaultOnboardingRuntime = {
+    async listOllamaModels(baseUrl) {
+        try {
+            const response = await fetch(`${baseUrl}/api/tags`);
+            if (!response.ok)
+                return undefined;
+            const body = (await response.json());
+            const models = (body.models ?? [])
+                .filter((entry) => typeof entry?.name === "string")
+                .map((entry) => ({
+                name: entry.name,
+                embedding: isEmbeddingModel(entry.name, entry.details?.families ?? []),
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            return models;
+        }
+        catch {
+            return undefined;
+        }
+    },
+    pullOllamaModel(model) {
+        return new Promise((resolve) => {
+            execFile("ollama", ["pull", model], { timeout: 10 * 60_000 }, (error) => resolve(error === null));
+        });
+    },
+    async validateEmbedding(config) {
+        try {
+            const provider = createOllamaEmbeddingProvider({
+                enabled: true,
+                model: config.model,
+                baseUrl: config.baseUrl,
+                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
+                topK: DEFAULT_SEMANTIC_CONFIG.topK,
+                excludeLockfiles: DEFAULT_SEMANTIC_CONFIG.excludeLockfiles,
+                ...(config.apiKeyEnv ? { apiKeyEnv: config.apiKeyEnv } : {}),
+            });
+            if (!(await provider.available()))
+                return false;
+            const vectors = await provider.embed(["aiw onboarding validation"]);
+            return vectors.length === 1 && vectors[0].length > 0;
+        }
+        catch {
+            return false;
+        }
+    },
+    async validateDecision(config) {
+        try {
+            const provider = createOllamaDecisionProvider({
+                enabled: true,
+                model: config.model,
+                baseUrl: config.baseUrl,
+                ...(config.apiKeyEnv ? { apiKeyEnv: config.apiKeyEnv } : {}),
+            });
+            return await provider.available();
+        }
+        catch {
+            return false;
+        }
+    },
+};
+async function askYesNo(answer, question) {
+    const response = (await answer(question)).trim().toLowerCase();
+    return response === "y" || response === "yes";
+}
+async function pickFromList(answer, label, options, fallback) {
+    const menu = options.map((option, index) => `${index + 1}) ${option}`).join("\n");
+    const response = (await answer(`${menu}\nSelect ${label} [${fallback}]: `)).trim();
+    if (response === "")
+        return fallback;
+    const numeric = Number.parseInt(response, 10);
+    if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length)
+        return options[numeric - 1];
+    return options.includes(response) ? response : fallback;
+}
+function isValidEnvName(value) {
+    return /^[A-Z_][A-Z0-9_]*$/.test(value);
+}
+async function gatherCapabilitySetup(answer, runtime, options) {
+    const models = await runtime.listOllamaModels(OLLAMA_BASE_URL);
+    const ollamaUp = models !== undefined;
+    const provider = ollamaUp
+        ? (await pickFromList(answer, "provider", ["ollama", "external"], "ollama")) === "external"
+            ? "external"
+            : "ollama"
+        : (await answer(`Ollama not reachable at ${OLLAMA_BASE_URL}. Use an external provider. [Enter] `),
+            "external");
+    if (provider === "ollama") {
+        let candidates = (models ?? []).filter((model) => options.onlyEmbedding ? model.embedding : true);
+        if (candidates.length === 0 && options.onlyEmbedding) {
+            const pull = await askYesNo(answer, `No embedding models found. Pull ${options.pullModel}? [y/N] `);
+            if (pull) {
+                await answer(`Pulling ${options.pullModel}... [Enter] `);
+                const pulled = await runtime.pullOllamaModel(options.pullModel);
+                if (pulled) {
+                    const refreshed = await runtime.listOllamaModels(OLLAMA_BASE_URL);
+                    candidates = (refreshed ?? []).filter((model) => model.embedding);
+                }
+                else {
+                    await answer("Pull failed. Enter a model manually. [Enter] ");
+                }
+            }
+            if (candidates.length === 0) {
+                const manual = (await answer(`Model name to use [${options.pullModel}]: `)).trim();
+                if (manual.length === 0)
+                    return undefined;
+                return { baseUrl: OLLAMA_BASE_URL, model: manual };
+            }
+        }
+        const names = candidates.map((candidate) => candidate.name);
+        const fallback = names.includes(options.fallbackModel) ? options.fallbackModel : names[0];
+        const model = await pickFromList(answer, `${options.shortLabel} model`, names, fallback);
+        return { baseUrl: OLLAMA_BASE_URL, model };
+    }
+    const endpoint = (await answer(`Endpoint URL: `)).trim();
+    if (!/^https?:\/\//i.test(endpoint)) {
+        await answer("Invalid URL. [Enter] ");
+        return undefined;
+    }
+    const model = (await answer(`Model name: `)).trim();
+    if (model.length === 0) {
+        await answer("Model name required. [Enter] ");
+        return undefined;
+    }
+    const rawEnv = (await answer(`Token env var (empty for none): `)).trim();
+    if (rawEnv.length > 0 && !isValidEnvName(rawEnv)) {
+        await answer("Invalid env var name. [Enter] ");
+        return undefined;
+    }
+    return { baseUrl: endpoint, model, ...(rawEnv ? { apiKeyEnv: rawEnv } : {}) };
+}
+async function configureCapability(fs, aiwPath, answer, runtime, options) {
+    const wants = await askYesNo(answer, `Configure ${options.label}? [y/N] `);
+    if (!wants)
+        return [];
+    for (;;) {
+        const setup = await gatherCapabilitySetup(answer, runtime, options);
+        if (!setup)
+            return [];
+        const valid = options.section === "semantic"
+            ? await runtime.validateEmbedding(setup)
+            : await runtime.validateDecision(setup);
+        if (valid) {
+            saveSettingsSection(fs, aiwPath, options.section, options.serialize(setup));
+            return [
+                `${options.section} (${setup.model}${setup.apiKeyEnv ? ` via ${setup.baseUrl}` : ""})`,
+            ];
+        }
+        const retry = await askYesNo(answer, `Validation failed for ${setup.model}. Retry? [y/N] (No = skip for now) `);
+        if (!retry)
+            return [];
+    }
+}
+export async function configureOptionalModels(fs, aiwPath, answer, runtime = defaultOnboardingRuntime) {
+    const enabled = [];
+    const settings = loadSettings(fs, aiwPath) ?? {};
+    if (!("semantic" in settings))
+        enabled.push(...(await configureCapability(fs, aiwPath, answer, runtime, {
+            section: "semantic",
+            label: "semantic embedding",
+            shortLabel: "embedding",
+            onlyEmbedding: true,
+            fallbackModel: DEFAULT_SEMANTIC_CONFIG.model,
+            pullModel: DEFAULT_SEMANTIC_CONFIG.model,
+            serialize: (setup) => ({
+                enabled: true,
+                model: setup.model,
+                baseUrl: setup.baseUrl,
+                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
+                topK: DEFAULT_SEMANTIC_CONFIG.topK,
+                excludeLockfiles: DEFAULT_SEMANTIC_CONFIG.excludeLockfiles,
+                ...(setup.apiKeyEnv ? { apiKeyEnv: setup.apiKeyEnv } : {}),
+            }),
+        })));
+    if (!("decision" in settings))
+        enabled.push(...(await configureCapability(fs, aiwPath, answer, runtime, {
+            section: "decision",
+            label: "advisory decision triage",
+            shortLabel: "decision",
+            onlyEmbedding: false,
+            fallbackModel: DEFAULT_DECISION_CONFIG.model,
+            pullModel: DEFAULT_DECISION_CONFIG.model,
+            serialize: (setup) => ({
+                enabled: true,
+                model: setup.model,
+                baseUrl: setup.baseUrl,
+                ...(setup.apiKeyEnv ? { apiKeyEnv: setup.apiKeyEnv } : {}),
+            }),
+        })));
+    return enabled;
+}

package/dist/ownership.d.ts

@@ -5,7 +5,7 @@ export type OwnedFile = {
     checksum: string;
     kind?: "neutral-resource" | "target-resource" | "ai-init" | "supporting-file";
     target?: Target;
-    resourceType?: ResourceType;
+    resourceType?: ResourceType | "context";
     resourceId?: string;
 };
 export type OwnershipMetadata = Omit<OwnedFile, "path" | "checksum">;

package/dist/ownership.js

@@ -49,7 +49,7 @@ export function parseOwnership(content) {
         if (file.target !== undefined && !TARGETS.includes(file.target))
             throw new Error(`Ownership inventory target is invalid: ${file.path}`);
         if (file.resourceType !== undefined &&
-            !RESOURCE_TYPES.includes(String(file.resourceType)))
+            ![...RESOURCE_TYPES, "context"].includes(String(file.resourceType)))
             throw new Error(`Ownership inventory resource type is invalid: ${file.path}`);
         if (file.resourceId !== undefined &&
             (typeof file.resourceId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(file.resourceId)))

package/dist/semantic.d.ts

@@ -6,6 +6,7 @@ export type SemanticConfig = {
     chunkChars: number;
     topK: number;
     excludeLockfiles: boolean;
+    apiKeyEnv?: string;
 };
 export type SemanticIndexChunk = {
     file: string;
@@ -47,7 +48,7 @@ export declare function serializeSemanticConfig(config: SemanticConfig): string;
 export declare function loadSemanticConfig(fs: FileSystem, aiwPath: string): SemanticConfig | undefined;
 export declare function parseSemanticConfig(text: string): SemanticConfig;
 type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
-export declare function createOllamaEmbeddingProvider(config: SemanticConfig, fetchImpl?: FetchLike): EmbeddingProvider;
+export declare function createOllamaEmbeddingProvider(config: SemanticConfig, fetchImpl?: FetchLike, env?: Readonly<Record<string, string | undefined>>): 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>;

package/dist/semantic.js

@@ -40,6 +40,7 @@ export function parseSemanticMapping(raw) {
     const chunkChars = raw2.chunkChars;
     const topK = raw2.topK;
     const rawExclude = raw2.excludeLockfiles;
+    const apiKeyEnv = raw2.apiKeyEnv;
     if (typeof enabled !== "boolean")
         throw new Error("semantic.enabled must be a boolean");
     const excludeLockfiles = rawExclude === undefined ? true : rawExclude;
@@ -47,6 +48,9 @@ export function parseSemanticMapping(raw) {
         return { ...DEFAULT_SEMANTIC_CONFIG, enabled: false, excludeLockfiles };
     if (rawExclude !== undefined && typeof rawExclude !== "boolean")
         throw new Error("semantic.excludeLockfiles must be a boolean");
+    if (apiKeyEnv !== undefined &&
+        (typeof apiKeyEnv !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(apiKeyEnv)))
+        throw new Error("semantic.apiKeyEnv must be an uppercase environment variable name");
     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))
@@ -64,10 +68,11 @@ export function parseSemanticMapping(raw) {
         chunkChars: parsedChunk,
         topK: parsedTopK,
         excludeLockfiles,
+        ...(apiKeyEnv ? { apiKeyEnv } : {}),
     };
 }
 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  excludeLockfiles: ${config.excludeLockfiles}\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}${config.apiKeyEnv ? `\n  apiKeyEnv: ${config.apiKeyEnv}` : ""}\n`;
 }
 export function loadSemanticConfig(fs, aiwPath) {
     const settings = loadSettings(fs, aiwPath);
@@ -89,7 +94,44 @@ export function parseSemanticConfig(text) {
     return parseSemanticDocument(text);
 }
 const EMBED_BATCH_SIZE = 64;
-export function createOllamaEmbeddingProvider(config, fetchImpl = (url, init) => fetch(url, init)) {
+export function createOllamaEmbeddingProvider(config, fetchImpl = (url, init) => fetch(url, init), env = process.env) {
+    const externalToken = config.apiKeyEnv ? env[config.apiKeyEnv] : undefined;
+    const isExternal = config.apiKeyEnv !== undefined;
+    const authHeaders = (extra = {}) => externalToken ? { ...extra, authorization: `Bearer ${externalToken}` } : extra;
+    if (isExternal)
+        return {
+            async available() {
+                try {
+                    const response = await fetchImpl(`${config.baseUrl}/v1/models`, {
+                        headers: authHeaders(),
+                    });
+                    return response.ok;
+                }
+                catch {
+                    return false;
+                }
+            },
+            async embed(texts) {
+                const vectors = [];
+                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}/v1/embeddings`, {
+                        method: "POST",
+                        headers: authHeaders({ "content-type": "application/json" }),
+                        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());
+                    const rows = body.data ?? [];
+                    if (rows.length !== batch.length ||
+                        rows.some((row) => !Array.isArray(row.embedding) || row.embedding.some((v) => typeof v !== "number")))
+                        throw new Error(`Embedding model ${config.model} returned invalid vectors`);
+                    vectors.push(...rows.map((row) => row.embedding));
+                }
+                return vectors;
+            },
+        };
     return {
         async available() {
             try {

package/dist/workflow.d.ts

@@ -2,6 +2,3 @@ import type { CommandResult, FileSystem } from "./types.js";
 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 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

@@ -1,12 +1,13 @@
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { BASE_DIRECTORIES, WORKFLOW_DIRECTORY } from "./constants.js";
-import { detectTarget, isTarget, renderAiInit, renderAiInitPath, renderResourcePath, } from "./adapter.js";
+import { detectTarget, isTarget, renderAiInit, describeResource, renderAiInitPath, renderResourcePath, } from "./adapter.js";
 import { loadBundledResources } from "./bundled-resources.js";
 import { assertSafeProjectPath, withSafeProjectWrites, writeProjectFilesAtomically, } from "./files.js";
 import { parseProjectProfile, profileProject } from "./profile.js";
 import { applyOverrides } from "./confirmation.js";
 import { mergeFacts } from "./intelligence.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";
@@ -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, 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 { 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";
@@ -442,11 +443,17 @@ 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));
             let interpreter = services.interpreter;
+            let interpreterModel;
             if (!interpreter) {
                 const aiConfig = loadAiProviderConfig(fs, aiw);
-                if (aiConfig?.enabled)
+                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));
                 let scopedFiles = scan.files;
@@ -466,6 +473,11 @@ export async function runCommand(args, root, fs, services = {}) {
                                 ];
                                 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`,
+                                });
                             }
                         }
                     }
@@ -473,8 +485,14 @@ export async function runCommand(args, root, fs, services = {}) {
                         // An unreadable index keeps the scan deterministic with alphabetical scoping.
                     }
                 }
-                const inferred = await interpreter.interpret(createInterpretationRequest(profile, scopedFiles, 4000, priorityFiles));
+                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
@@ -507,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`,
+                });
+            }
+            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." };
+            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";
@@ -1006,8 +1050,13 @@ export async function runCommand(args, root, fs, services = {}) {
                         exitCode: 1,
                         error: `Decision model ${rankingConfig.model} is not available at ${rankingConfig.baseUrl}.`,
                     };
+                let decisionTokens = 0;
                 ranked = await rankRecommendations(recommendations, profile, async (scoped, recs) => {
-                    const response = await decisionProvider.decide(buildRecommendationRankingRequest(profileSummaryForRanking(scoped), recs));
+                    const request = buildRecommendationRankingRequest(profileSummaryForRanking(scoped), recs);
+                    decisionTokens += Math.ceil((request.state.length +
+                        Object.values(request.questions).reduce((total, question) => total + question.instructions.length, 0)) /
+                        4);
+                    const response = await decisionProvider.decide(request);
                     const answers = {};
                     for (const [id, answer] of Object.entries(response.answers))
                         answers[id] =
@@ -1021,6 +1070,13 @@ export async function runCommand(args, root, fs, services = {}) {
                                 : {};
                     return answers;
                 });
+                const usagePath = join(aiw, "usage.yml");
+                const entries = fs.exists(usagePath) ? parseTokenUsage(fs.read(usagePath)) : [];
+                fs.write(usagePath, serializeTokenUsage(recordTokenUsage(entries, {
+                    stage: "recommend.decision",
+                    budget: decisionTokens,
+                    used: decisionTokens,
+                })));
                 ordered = ranked.items;
             }
             const selectedOption = args.find((arg) => arg.startsWith("--select="));
@@ -1899,85 +1955,6 @@ function approvalArtifactPath(aiw, stage) {
     };
     return resolve(aiw, paths[stage]);
 }
-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 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,
-                baseUrl: DEFAULT_SEMANTIC_CONFIG.baseUrl,
-                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
-                topK: DEFAULT_SEMANTIC_CONFIG.topK,
-                excludeLockfiles: DEFAULT_SEMANTIC_CONFIG.excludeLockfiles,
-            });
-            enabled.push(`semantic (${model})`);
-        }
-    }
-    if (!("decision" in settings)) {
-        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,
-                baseUrl: DEFAULT_DECISION_CONFIG.baseUrl,
-            });
-            enabled.push(`decision (${model})`);
-        }
-    }
-    return enabled;
-}
 function formatConfidence(confidence) {
     return confidence === undefined ? "unknown" : confidence.toFixed(3);
 }
@@ -2169,6 +2146,25 @@ function syncSelectedResources(fs, root, aiw, profile, selected, apply = false,
         const rule = path.match(/^generated\/rules\/(project-quality|tdd-project-policy)\.md$/);
         if (rule)
             addResource("rules", rule[1], content);
+        const rootContext = path === "generated/context/root-context.md";
+        if (rootContext) {
+            const neutralContextPath = join(root, describeResource("universal", "context", "project").path);
+            addOwned(neutralContextPath, content, {
+                kind: "neutral-resource",
+                target: "universal",
+                resourceType: "context",
+                resourceId: "project",
+            });
+            const targetContextPath = describeResource(target, "context", "project").path;
+            if (targetContextPath !== renderAiInitPath(target)) {
+                addOwned(join(root, targetContextPath), content, {
+                    kind: "target-resource",
+                    target,
+                    resourceType: "context",
+                    resourceId: "project",
+                });
+            }
+        }
     });
     const ownershipPath = join(aiw, "ownership.yml");
     if (fs.pathType?.(ownershipPath) !== "file")

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/decision-model-evaluation.md

@@ -27,7 +27,7 @@ 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.

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 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.
+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
 
@@ -14,6 +18,7 @@ semantic:
   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.
@@ -30,6 +35,19 @@ When semantic mapping is enabled, `aiw scan` additionally:
 
 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>" [--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.

package/package.json

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