@multileaf/ai-workflow 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-08
+
+### Changed
+
+- Unified user-local settings into a single `.aiw/settings.yml` with `semantic`, `decision`, `telemetry`, and `overrides` sections. The file is local user state, not committed project state. Interactive onboarding and the `telemetry`/`confirm` commands write to it, and legacy `.aiw/semantic.yml`, `.aiw/decision.yml`, `.aiw/telemetry.yml`, and `.aiw/overrides.yml` files are still read for backward compatibility. `uninstall` removes `settings.yml` and all four legacy files.
+
+## [0.3.1] - 2026-10-08
+
+### Added
+
+- Interactive optional-model onboarding during `aiw install`: in an interactive terminal, the installer asks whether to enable semantic mapping and advisory decision triage and writes `.aiw/semantic.yml` / `.aiw/decision.yml` with defaults before `/ai-init` runs. Non-interactive installs skip the prompts, and existing configuration files are never overwritten.
+
 ## [0.3.0] - 2026-10-08
 
 ### Added

package/dist/cli.js

@@ -17,7 +17,7 @@ async function runWithTelemetry(args, root, services) {
     const result = await runCommand(args, root, nodeFileSystem, dependencies);
     if (args[0] === "ui" || (args[0] === "telemetry" && result.exitCode !== 0))
         return result;
-    await recordConfiguredTelemetry(nodeFileSystem, join(root, ".aiw/telemetry.yml"), services.telemetry, args[0], result);
+    await recordConfiguredTelemetry(nodeFileSystem, join(root, ".aiw"), services.telemetry, args[0], result);
     return result;
 }
 if (process.argv[1]?.endsWith("cli.js") || process.argv[1]?.endsWith("/aiw")) {

package/dist/decision.d.ts

@@ -42,6 +42,8 @@ export type DecisionProvider = {
 };
 export declare const DECISION_CONFIG_PATH = "decision.yml";
 export declare const DEFAULT_DECISION_CONFIG: DecisionConfig;
+export declare function parseDecisionMapping(raw: unknown): DecisionConfig;
+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;

package/dist/decision.js

@@ -1,19 +1,18 @@
 import { parseDocument } from "yaml";
+import { loadSettings } from "./settings.js";
 export const DECISION_CONFIG_PATH = "decision.yml";
 export const DEFAULT_DECISION_CONFIG = {
     enabled: false,
     model: "clef-flash:latest",
     baseUrl: "http://localhost:11434",
 };
-export function parseDecisionConfig(text) {
-    const document = parseDocument(text);
-    const node = document.get("decision");
-    if (document.errors.length > 0 || !node || typeof node !== "object")
-        throw new Error("Decision configuration must be a YAML object with a `decision` mapping");
-    const raw = node.toJSON();
-    const enabled = raw.enabled;
-    const model = raw.model;
-    const baseUrl = raw.baseUrl;
+export function parseDecisionMapping(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("decision must be a YAML mapping");
+    const record = raw;
+    const enabled = record.enabled;
+    const model = record.model;
+    const baseUrl = record.baseUrl;
     if (typeof enabled !== "boolean")
         throw new Error("decision.enabled must be a boolean");
     if (!enabled)
@@ -24,7 +23,20 @@ export function parseDecisionConfig(text) {
         throw new Error("decision.baseUrl must be an http(s) URL when decision mapping is enabled");
     return { enabled: true, model, baseUrl };
 }
+export function serializeDecisionConfig(config) {
+    return `decision:\n  enabled: ${config.enabled}\n  model: ${config.model}\n  baseUrl: ${config.baseUrl}\n`;
+}
+export function parseDecisionConfig(text) {
+    const document = parseDocument(text);
+    const node = document.get("decision");
+    if (document.errors.length > 0 || !node || typeof node !== "object")
+        throw new Error("Decision configuration must be a YAML object with a `decision` mapping");
+    return parseDecisionMapping(node.toJSON());
+}
 export function loadDecisionConfig(fs, aiwPath) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings !== undefined)
+        return "decision" in settings ? parseDecisionMapping(settings.decision) : undefined;
     const configPath = `${aiwPath}/${DECISION_CONFIG_PATH}`;
     if (!fs.exists(configPath))
         return undefined;

package/dist/semantic.d.ts

@@ -28,8 +28,10 @@ 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 function parseSemanticConfig(text: string): SemanticConfig;
+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;
 export declare function chunkText(content: string, chunkChars: number): string[];
 export declare function cosineSimilarity(a: number[], b: number[]): number;

package/dist/semantic.js

@@ -1,4 +1,5 @@
 import { parseDocument } from "yaml";
+import { loadSettings } from "./settings.js";
 export const SEMANTIC_CONFIG_PATH = "semantic.yml";
 export const SEMANTIC_INDEX_PATH = "semantic/index.json";
 export const DEFAULT_SEMANTIC_CONFIG = {
@@ -8,17 +9,15 @@ export const DEFAULT_SEMANTIC_CONFIG = {
     chunkChars: 1200,
     topK: 8,
 };
-export function parseSemanticConfig(text) {
-    const document = parseDocument(text);
-    const node = document.get("semantic");
-    if (document.errors.length > 0 || !node || typeof node !== "object")
-        throw new Error("Semantic configuration must be a YAML object with a `semantic` mapping");
-    const raw = node.toJSON();
-    const enabled = raw.enabled;
-    const model = raw.model;
-    const baseUrl = raw.baseUrl;
-    const chunkChars = raw.chunkChars;
-    const topK = raw.topK;
+export function parseSemanticMapping(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("semantic must be a YAML mapping");
+    const raw2 = raw;
+    const enabled = raw2.enabled;
+    const model = raw2.model;
+    const baseUrl = raw2.baseUrl;
+    const chunkChars = raw2.chunkChars;
+    const topK = raw2.topK;
     if (typeof enabled !== "boolean")
         throw new Error("semantic.enabled must be a boolean");
     if (!enabled)
@@ -35,12 +34,28 @@ export function parseSemanticConfig(text) {
         throw new Error("semantic.topK must be a positive integer");
     return { enabled: true, model, baseUrl, chunkChars: parsedChunk, topK: parsedTopK };
 }
+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`;
+}
 export function loadSemanticConfig(fs, aiwPath) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings !== undefined)
+        return "semantic" in settings ? parseSemanticMapping(settings.semantic) : undefined;
     const configPath = `${aiwPath}/${SEMANTIC_CONFIG_PATH}`;
     if (!fs.exists(configPath))
         return undefined;
     return parseSemanticConfig(fs.read(configPath));
 }
+function parseSemanticDocument(text) {
+    const document = parseDocument(text);
+    const node = document.get("semantic");
+    if (document.errors.length > 0 || !node || typeof node !== "object")
+        throw new Error("Semantic configuration must be a YAML object with a `semantic` mapping");
+    return parseSemanticMapping(node.toJSON());
+}
+export function parseSemanticConfig(text) {
+    return parseSemanticDocument(text);
+}
 export function createOllamaEmbeddingProvider(config) {
     const fetchImpl = (url, init) => fetch(url, init);
     return {

package/dist/settings.d.ts

@@ -0,0 +1,11 @@
+import type { FileSystem } from "./types.js";
+import type { FactOverride } from "./confirmation.js";
+export declare const SETTINGS_PATH = "settings.yml";
+export declare const LEGACY_SETTINGS_PATHS: readonly ["semantic.yml", "decision.yml", "telemetry.yml", "overrides.yml"];
+export type SettingsDocument = Record<string, unknown>;
+export declare function loadSettings(fs: FileSystem, aiwPath: string): SettingsDocument | undefined;
+export declare function saveSettingsSection(fs: FileSystem, aiwPath: string, section: string, value: unknown): void;
+export declare function serializeSettingOverrides(overrides: FactOverride[]): unknown;
+export declare function readFactOverrides(fs: FileSystem, aiwPath: string): FactOverride[];
+export declare function saveSettingOverrides(fs: FileSystem, aiwPath: string, overrides: FactOverride[]): void;
+export declare function parseSettingOverrides(raw: unknown): FactOverride[];

package/dist/settings.js

@@ -0,0 +1,70 @@
+import { parseDocument, stringify } from "yaml";
+import { parseOverrides } from "./confirmation.js";
+export const SETTINGS_PATH = "settings.yml";
+export const LEGACY_SETTINGS_PATHS = [
+    "semantic.yml",
+    "decision.yml",
+    "telemetry.yml",
+    "overrides.yml",
+];
+export function loadSettings(fs, aiwPath) {
+    const path = `${aiwPath}/${SETTINGS_PATH}`;
+    if (!fs.exists(path))
+        return undefined;
+    const document = parseDocument(fs.read(path));
+    if (document.errors.length > 0)
+        throw new Error(`Settings file ${path} is not valid YAML`);
+    const root = document.toJSON();
+    if (root === null)
+        return {};
+    if (typeof root !== "object" || Array.isArray(root))
+        throw new Error(`Settings file ${path} must contain a YAML mapping`);
+    return root;
+}
+export function saveSettingsSection(fs, aiwPath, section, value) {
+    const path = `${aiwPath}/${SETTINGS_PATH}`;
+    const existing = loadSettings(fs, aiwPath) ?? {};
+    existing[section] = value;
+    const document = parseDocument(stringify(existing));
+    document.set("schema", 1);
+    fs.write(path, document.toString());
+}
+export function serializeSettingOverrides(overrides) {
+    return overrides.map((item) => ({
+        key: item.key,
+        action: item.action,
+        ...(item.value ? { value: item.value } : {}),
+    }));
+}
+export function readFactOverrides(fs, aiwPath) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings !== undefined)
+        return "overrides" in settings ? parseSettingOverrides(settings.overrides) : [];
+    const legacyPath = `${aiwPath}/overrides.yml`;
+    if (!fs.exists(legacyPath))
+        return [];
+    return parseOverrides(fs.read(legacyPath));
+}
+export function saveSettingOverrides(fs, aiwPath, overrides) {
+    saveSettingsSection(fs, aiwPath, "overrides", serializeSettingOverrides(overrides));
+}
+export function parseSettingOverrides(raw) {
+    if (!Array.isArray(raw))
+        throw new Error("Settings overrides section must be a list");
+    return raw.map((item) => {
+        if (!item || typeof item !== "object")
+            throw new Error("Invalid settings override entry");
+        const entry = item;
+        if (typeof entry.key !== "string" || entry.key.trim() === "")
+            throw new Error("Settings override key must be a non-empty string");
+        if (entry.action !== "accept" && entry.action !== "reject" && entry.action !== "edit")
+            throw new Error(`Invalid settings override action for key ${entry.key}`);
+        if (entry.action === "edit" && (typeof entry.value !== "string" || entry.value === ""))
+            throw new Error(`Settings override ${entry.key} requires a value for an edit action`);
+        return {
+            key: entry.key,
+            action: entry.action,
+            ...(typeof entry.value === "string" && entry.value !== "" ? { value: entry.value } : {}),
+        };
+    });
+}

package/dist/telemetry.d.ts

@@ -14,7 +14,10 @@ export interface TelemetryClient {
     record(event: TelemetryEvent): Promise<void>;
 }
 export declare const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig;
+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 function recordConfiguredTelemetry(fs: FileSystem, configPath: string, client: TelemetryClient | undefined, command: string | undefined, result: CommandResult): Promise<void>;
+export declare function recordConfiguredTelemetry(fs: FileSystem, aiwPath: string, client: TelemetryClient | undefined, command: string | undefined, result: CommandResult): Promise<void>;

package/dist/telemetry.js

@@ -1,3 +1,4 @@
+import { loadSettings } from "./settings.js";
 export const DEFAULT_TELEMETRY_CONFIG = {
     schema: 1,
     enabled: false,
@@ -45,6 +46,41 @@ const TELEMETRY_COMMANDS = new Set([
     "verify",
     "verify-package",
 ]);
+export function parseTelemetryMapping(raw) {
+    if (!raw || typeof raw !== "object")
+        throw new Error("telemetry settings must be a mapping");
+    const record = raw;
+    if (typeof record.enabled !== "boolean")
+        throw new Error("telemetry.enabled must be a boolean");
+    if (typeof record.include_command !== "boolean")
+        throw new Error("telemetry.include_command must be a boolean");
+    if (typeof record.include_outcome !== "boolean")
+        throw new Error("telemetry.include_outcome must be a boolean");
+    return {
+        schema: 1,
+        enabled: record.enabled,
+        includeCommand: record.include_command,
+        includeOutcome: record.include_outcome,
+    };
+}
+export function serializeTelemetryMapping(config) {
+    return {
+        enabled: config.enabled,
+        include_command: config.includeCommand,
+        include_outcome: config.includeOutcome,
+    };
+}
+export function loadTelemetryConfig(fs, aiwPath) {
+    const settings = loadSettings(fs, aiwPath);
+    if (settings !== undefined)
+        return "telemetry" in settings
+            ? parseTelemetryMapping(settings.telemetry)
+            : DEFAULT_TELEMETRY_CONFIG;
+    const legacyPath = `${aiwPath}/telemetry.yml`;
+    if (!fs.exists(legacyPath))
+        return DEFAULT_TELEMETRY_CONFIG;
+    return parseTelemetryConfig(fs.read(legacyPath));
+}
 export function parseTelemetryConfig(content) {
     const lines = content.split(/\r?\n/);
     if (lines.at(-1) === "")
@@ -74,11 +110,16 @@ export function createTelemetryEvent(command, result, config) {
         ...(config.includeOutcome ? { outcome: result.exitCode === 0 ? "success" : "failure" } : {}),
     };
 }
-export async function recordConfiguredTelemetry(fs, configPath, client, command, result) {
-    if (!client || !fs.exists(configPath))
+export async function recordConfiguredTelemetry(fs, aiwPath, client, command, result) {
+    if (!client)
         return;
     try {
-        const event = createTelemetryEvent(command, result, parseTelemetryConfig(fs.read(configPath)));
+        const config = loadTelemetryConfig(fs, aiwPath);
+        const settings = loadSettings(fs, aiwPath);
+        const configured = (settings !== undefined && "telemetry" in settings) || fs.exists(`${aiwPath}/telemetry.yml`);
+        if (!configured)
+            return;
+        const event = createTelemetryEvent(command, result, config);
         if (event)
             await client.record(event);
     }

package/dist/workflow.d.ts

@@ -2,3 +2,5 @@ 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 declare function configureOptionalModels(fs: FileSystem, aiwPath: string, answer: ConfirmQuestion): Promise<string[]>;

package/dist/workflow.js

@@ -5,8 +5,7 @@ import { detectTarget, isTarget, renderAiInit, renderAiInitPath, renderResourceP
 import { loadBundledResources } from "./bundled-resources.js";
 import { assertSafeProjectPath, withSafeProjectWrites, writeProjectFilesAtomically, } from "./files.js";
 import { parseProjectProfile, profileProject } from "./profile.js";
-import { serializeOverrides } from "./confirmation.js";
-import { applyOverrides, parseOverrides } from "./confirmation.js";
+import { applyOverrides } from "./confirmation.js";
 import { mergeFacts } from "./intelligence.js";
 import { createInterpretationRequest } from "./interpreter.js";
 import { recommendCapabilities, resourcesForCapabilities, serializeRecommendations, } from "./recommendations.js";
@@ -21,8 +20,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 { buildEvidenceTriageRequest, createOllamaDecisionProvider, loadDecisionConfig, DECISION_CONFIG_PATH, } from "./decision.js";
-import { buildSemanticIndex, createOllamaEmbeddingProvider, loadSemanticConfig, parseSemanticIndex, querySemanticIndex, SEMANTIC_INDEX_PATH, serializeSemanticIndex, } from "./semantic.js";
+import { readFactOverrides, saveSettingOverrides, saveSettingsSection, loadSettings, } from "./settings.js";
+import { buildEvidenceTriageRequest, createOllamaDecisionProvider, DEFAULT_DECISION_CONFIG, DECISION_CONFIG_PATH, loadDecisionConfig, } from "./decision.js";
+import { buildSemanticIndex, createOllamaEmbeddingProvider, DEFAULT_SEMANTIC_CONFIG, loadSemanticConfig, parseSemanticIndex, querySemanticIndex, 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, parseTelemetryConfig, serializeTelemetryConfig, } from "./telemetry.js";
+import { DEFAULT_TELEMETRY_CONFIG, loadTelemetryConfig, parseTelemetryConfig, serializeTelemetryMapping, } 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 = {}) {
@@ -327,9 +327,22 @@ export async function runCommand(args, root, fs, services = {}) {
             pendingWrites.delete(manifestPath);
             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 = [];
+            if (stdin.isTTY) {
+                const terminal = createInterface({ input: stdin, output: stdout });
+                try {
+                    optionalModels = await configureOptionalModels(fs, aiw, (question) => terminal.question(question));
+                }
+                finally {
+                    terminal.close();
+                }
+            }
             return {
                 exitCode: 0,
-                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.`,
+                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.`
+                        : ""),
             };
         }
         if (command === "telemetry") {
@@ -339,13 +352,11 @@ export async function runCommand(args, root, fs, services = {}) {
             const action = args[1];
             if (!action)
                 return { exitCode: 1, error: usage };
-            const path = join(aiw, "telemetry.yml");
+            const telemetryConfig = loadTelemetryConfig(fs, aiw);
             if (action === "status") {
                 if (args.length !== 2)
                     return { exitCode: 1, error: usage };
-                const config = fs.exists(path)
-                    ? parseTelemetryConfig(fs.read(path))
-                    : DEFAULT_TELEMETRY_CONFIG;
+                const config = telemetryConfig;
                 return {
                     exitCode: 0,
                     output: `Telemetry is ${config.enabled ? "enabled" : "disabled"}. Command collection: ${config.includeCommand ? "included" : "excluded"}. Outcome collection: ${config.includeOutcome ? "included" : "excluded"}.`,
@@ -354,7 +365,7 @@ export async function runCommand(args, root, fs, services = {}) {
             if (action === "disable") {
                 if (args.length !== 2)
                     return { exitCode: 1, error: usage };
-                fs.write(path, serializeTelemetryConfig({ ...DEFAULT_TELEMETRY_CONFIG }));
+                saveSettingsSection(fs, aiw, "telemetry", serializeTelemetryMapping(DEFAULT_TELEMETRY_CONFIG));
                 return { exitCode: 0, output: "Telemetry disabled." };
             }
             if (action === "enable") {
@@ -364,7 +375,7 @@ export async function runCommand(args, root, fs, services = {}) {
                         options.length)
                     return { exitCode: 1, error: usage };
                 const privacyValue = (name) => !options.includes(`--${name}=exclude`);
-                fs.write(path, serializeTelemetryConfig({
+                saveSettingsSection(fs, aiw, "telemetry", serializeTelemetryMapping({
                     schema: 1,
                     enabled: true,
                     includeCommand: privacyValue("commands"),
@@ -415,9 +426,7 @@ export async function runCommand(args, root, fs, services = {}) {
                 const inferred = await services.interpreter.interpret(createInterpretationRequest(profile, scan.files));
                 profile.facts = mergeFacts(profile.facts, inferred);
             }
-            const overrides = fs.exists(join(aiw, "overrides.yml"))
-                ? parseOverrides(fs.read(join(aiw, "overrides.yml")))
-                : [];
+            const overrides = readFactOverrides(fs, aiw);
             const rejectedKeys = new Set(overrides
                 .filter((override) => override.action === "reject")
                 .map((override) => override.key));
@@ -902,7 +911,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     exitCode: 1,
                     error: "Usage: aiw confirm --accept key | --reject key | --edit key=value",
                 };
-            fs.write(join(aiw, "overrides.yml"), serializeOverrides(overrides));
+            saveSettingOverrides(fs, aiw, overrides);
             return { exitCode: 0, output: "Fact overrides saved." };
         }
         if (command === "recommend") {
@@ -1116,6 +1125,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     parsePrivateRegistries(fs.read(join(aiw, "registries.yml")));
                 if (fs.exists(join(aiw, "telemetry.yml")))
                     parseTelemetryConfig(fs.read(join(aiw, "telemetry.yml")));
+                loadTelemetryConfig(fs, aiw);
             }
             catch (error) {
                 return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
@@ -1150,6 +1160,7 @@ export async function runCommand(args, root, fs, services = {}) {
                 "profile.yml",
                 "lock.yml",
                 "overrides.yml",
+                "settings.yml",
                 "recommendations.yml",
                 "team-preset.yml",
                 "registries.yml",
@@ -1781,6 +1792,39 @@ function approvalArtifactPath(aiw, stage) {
     };
     return resolve(aiw, paths[stage]);
 }
+export async function configureOptionalModels(fs, aiwPath, answer) {
+    const enabled = [];
+    const settings = loadSettings(fs, aiwPath) ?? {};
+    if (!("semantic" in settings)) {
+        const response = (await answer(`Enable semantic mapping with a local embedding model (default: ${DEFAULT_SEMANTIC_CONFIG.model} at ${DEFAULT_SEMANTIC_CONFIG.baseUrl})? [y/N] `))
+            .trim()
+            .toLowerCase();
+        if (response === "y" || response === "yes") {
+            saveSettingsSection(fs, aiwPath, "semantic", {
+                enabled: true,
+                model: DEFAULT_SEMANTIC_CONFIG.model,
+                baseUrl: DEFAULT_SEMANTIC_CONFIG.baseUrl,
+                chunkChars: DEFAULT_SEMANTIC_CONFIG.chunkChars,
+                topK: DEFAULT_SEMANTIC_CONFIG.topK,
+            });
+            enabled.push(`semantic (${DEFAULT_SEMANTIC_CONFIG.model})`);
+        }
+    }
+    if (!("decision" in settings)) {
+        const response = (await answer(`Enable advisory decision triage with a local decision model (default: ${DEFAULT_DECISION_CONFIG.model} at ${DEFAULT_DECISION_CONFIG.baseUrl})? [y/N] `))
+            .trim()
+            .toLowerCase();
+        if (response === "y" || response === "yes") {
+            saveSettingsSection(fs, aiwPath, "decision", {
+                enabled: true,
+                model: DEFAULT_DECISION_CONFIG.model,
+                baseUrl: DEFAULT_DECISION_CONFIG.baseUrl,
+            });
+            enabled.push(`decision (${DEFAULT_DECISION_CONFIG.model})`);
+        }
+    }
+    return enabled;
+}
 function formatConfidence(confidence) {
     return confidence === undefined ? "unknown" : confidence.toFixed(3);
 }

package/docs/semantic-mapping.md

@@ -1,10 +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.
+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.
 
 ## Configuration
 
-Create `.aiw/semantic.yml`:
+Add a `semantic` section to `.aiw/settings.yml`:
 
 ```yaml
 semantic:

package/docs/telemetry.md

@@ -11,7 +11,7 @@ aiw telemetry enable --commands=exclude --outcomes=include
 aiw telemetry disable
 ```
 
-Preferences are stored in `.aiw/telemetry.yml`. Command and outcome collection can be enabled or excluded independently. Disabling telemetry takes effect before the next event can be recorded.
+Preferences are stored in the local user settings file `.aiw/settings.yml` under the `telemetry` section (the legacy `.aiw/telemetry.yml` file is still read when `settings.yml` does not exist). Command and outcome collection can be enabled or excluded independently. Disabling telemetry takes effect before the next event can be recorded.
 
 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.
 

package/package.json

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