@multileaf/ai-workflow 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-08
+
+### Fixed
+
+- Approving an SDD stage that never passed its quality gate now reports an actionable `Run aiw gate <stage> before approving` error instead of a misleading stale-approval message.
+- `aiw semantic status` and `aiw decision status` now point to the `.aiw/settings.yml` sections instead of the legacy standalone files.
+
+## [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

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,8 +42,9 @@ export type DecisionProvider = {
 };
 export declare const DECISION_CONFIG_PATH = "decision.yml";
 export declare const DEFAULT_DECISION_CONFIG: DecisionConfig;
-export declare function parseDecisionConfig(text: string): 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;
 export declare function createOllamaDecisionProvider(config: DecisionConfig): DecisionProvider;

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)
@@ -27,7 +26,17 @@ export function parseDecisionConfig(text) {
 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,9 +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)
@@ -39,11 +38,24 @@ 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.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, DEFAULT_DECISION_CONFIG, DECISION_CONFIG_PATH, loadDecisionConfig, serializeDecisionConfig, } from "./decision.js";
-import { buildSemanticIndex, createOllamaEmbeddingProvider, DEFAULT_SEMANTIC_CONFIG, loadSemanticConfig, parseSemanticIndex, querySemanticIndex, SEMANTIC_CONFIG_PATH, SEMANTIC_INDEX_PATH, serializeSemanticConfig, serializeSemanticIndex, } from "./semantic.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 { 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 = {}) {
@@ -161,9 +161,12 @@ export async function runCommand(args, root, fs, services = {}) {
                 if (ledger.stages[workflowStage]?.artifactHash !== artifactHash) {
                     const invalidated = invalidateStageAndDescendants(ledger, workflowStage, new Date().toISOString());
                     fs.write(join(aiw, "approvals.yml"), serializeApprovalLedger(invalidated));
+                    const existing = ledger.stages[workflowStage];
                     return {
                         exitCode: 1,
-                        error: `The ${workflowStage} artifact changed after review; its approval is stale. Rerun the quality gate and request approval again.`,
+                        error: existing
+                            ? `The ${workflowStage} artifact changed after review; its approval is stale. Rerun the quality gate and request approval again.`
+                            : `No passing quality gate recorded for ${workflowStage}. Run aiw gate ${workflowStage} before approving.`,
                     };
                 }
                 const updated = approveStage(ledger, workflowStage, {
@@ -352,13 +355,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"}.`,
@@ -367,7 +368,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") {
@@ -377,7 +378,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"),
@@ -428,9 +429,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));
@@ -472,7 +471,7 @@ export async function runCommand(args, root, fs, services = {}) {
                 if (!config)
                     return {
                         exitCode: 0,
-                        output: `Decision model is not configured. Create .aiw/${DECISION_CONFIG_PATH} to enable it.`,
+                        output: `Decision model is not configured. Add a decision section to .aiw/settings.yml to enable it.`,
                     };
                 return {
                     exitCode: 0,
@@ -519,7 +518,7 @@ export async function runCommand(args, root, fs, services = {}) {
                 if (!config)
                     return {
                         exitCode: 0,
-                        output: `Semantic mapping is not configured. Create .aiw/${"semantic.yml"} to enable it.`,
+                        output: `Semantic mapping is not configured. Add a semantic section to .aiw/settings.yml to enable it.`,
                     };
                 const indexPath = join(aiw, SEMANTIC_INDEX_PATH);
                 const built = fs.exists(indexPath)
@@ -915,7 +914,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") {
@@ -1129,6 +1128,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) };
@@ -1163,6 +1163,7 @@ export async function runCommand(args, root, fs, services = {}) {
                 "profile.yml",
                 "lock.yml",
                 "overrides.yml",
+                "settings.yml",
                 "recommendations.yml",
                 "team-preset.yml",
                 "registries.yml",
@@ -1796,23 +1797,32 @@ function approvalArtifactPath(aiw, stage) {
 }
 export async function configureOptionalModels(fs, aiwPath, answer) {
     const enabled = [];
-    const semanticPath = join(aiwPath, SEMANTIC_CONFIG_PATH);
-    if (!fs.exists(semanticPath)) {
+    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") {
-            fs.write(semanticPath, serializeSemanticConfig({ ...DEFAULT_SEMANTIC_CONFIG, enabled: true }));
+            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})`);
         }
     }
-    const decisionPath = join(aiwPath, DECISION_CONFIG_PATH);
-    if (!fs.exists(decisionPath)) {
+    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") {
-            fs.write(decisionPath, serializeDecisionConfig({ ...DEFAULT_DECISION_CONFIG, enabled: true }));
+            saveSettingsSection(fs, aiwPath, "decision", {
+                enabled: true,
+                model: DEFAULT_DECISION_CONFIG.model,
+                baseUrl: DEFAULT_DECISION_CONFIG.baseUrl,
+            });
             enabled.push(`decision (${DEFAULT_DECISION_CONFIG.model})`);
         }
     }

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. 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 file 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 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.1",
+  "version": "0.4.1",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {