@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/kanban/server/routes/settings.js

@@ -0,0 +1,736 @@
+import express from 'express';
+import fs from 'fs/promises';
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __routeDir = path.dirname(fileURLToPath(import.meta.url));
+const LIB_AGENTS_PATH = path.join(__routeDir, '../../../cli/agents');
+const LIB_CHECKS_PATH = path.join(__routeDir, '../../../cli/checks');
+const customAgentsDir = (root) => path.join(root, '.avc', 'customized-agents');
+const customChecksDir = (root) => path.join(root, '.avc', 'customized-agents', 'checks');
+
+/**
+ * Default model catalogue — mirrors the defaults in src/cli/init.js.
+ * Used as a fallback when a project's avc.json pre-dates model pricing support.
+ */
+const PRICING_SOURCES = {
+  claude: 'https://www.anthropic.com/pricing',
+  gemini: 'https://ai.google.dev/pricing',
+  openai: 'https://openai.com/api/pricing',
+};
+
+const DEFAULT_MODELS = {
+  // Anthropic Claude models (prices per 1M tokens in USD)
+  'claude-opus-4-6':            { provider: 'claude',  displayName: 'Claude Opus 4.6',          pricing: { input: 5.00,  output: 25.00, unit: 'million', source: PRICING_SOURCES.claude, lastUpdated: '2026-02-24' } },
+  'claude-sonnet-4-6':          { provider: 'claude',  displayName: 'Claude Sonnet 4.6',        pricing: { input: 3.00,  output: 15.00, unit: 'million', source: PRICING_SOURCES.claude, lastUpdated: '2026-02-24' } },
+  'claude-haiku-4-5-20251001':  { provider: 'claude',  displayName: 'Claude Haiku 4.5',         pricing: { input: 1.00,  output:  5.00, unit: 'million', source: PRICING_SOURCES.claude, lastUpdated: '2026-02-24' } },
+  // Google Gemini models (prices per 1M tokens in USD)
+  'gemini-3.1-pro-preview':     { provider: 'gemini',  displayName: 'Gemini 3.1 Pro Preview',   pricing: { input: 2.00,  output: 12.00, unit: 'million', source: PRICING_SOURCES.gemini, lastUpdated: '2026-03-05' } },
+  'gemini-3-flash-preview':     { provider: 'gemini',  displayName: 'Gemini 3 Flash Preview',   pricing: { input: 0.50,  output:  3.00, unit: 'million', source: PRICING_SOURCES.gemini, lastUpdated: '2026-03-05' } },
+  'gemini-2.5-pro':             { provider: 'gemini',  displayName: 'Gemini 2.5 Pro',           pricing: { input: 1.25,  output: 10.00, unit: 'million', source: PRICING_SOURCES.gemini, lastUpdated: '2026-02-24' } },
+  'gemini-2.5-flash':           { provider: 'gemini',  displayName: 'Gemini 2.5 Flash',         pricing: { input: 0.30,  output:  2.50, unit: 'million', source: PRICING_SOURCES.gemini, lastUpdated: '2026-02-24' } },
+  'gemini-2.5-flash-lite':      { provider: 'gemini',  displayName: 'Gemini 2.5 Flash-Lite',    pricing: { input: 0.10,  output:  0.40, unit: 'million', source: PRICING_SOURCES.gemini, lastUpdated: '2026-02-24' } },
+  // OpenAI models (prices per 1M tokens in USD)
+  'gpt-5.4':                    { provider: 'openai',  displayName: 'GPT-5.4',                  pricing: { input: 2.50,  output: 15.00, unit: 'million', source: PRICING_SOURCES.openai, lastUpdated: '2026-03-06' } },
+  'gpt-5.4-pro':                { provider: 'openai',  displayName: 'GPT-5.4 Pro',              pricing: { input: 30.00, output: 180.00,unit: 'million', source: PRICING_SOURCES.openai, lastUpdated: '2026-03-06' } },
+  'gpt-5-mini':                 { provider: 'openai',  displayName: 'GPT-5 mini',               pricing: { input: 0.25,  output:  2.00, unit: 'million', source: PRICING_SOURCES.openai, lastUpdated: '2026-02-24' } },
+  'gpt-5-nano':                 { provider: 'openai',  displayName: 'GPT-5 nano',               pricing: { input: 0.05,  output:  0.40, unit: 'million', source: PRICING_SOURCES.openai, lastUpdated: '2026-03-06' } },
+};
+
+/**
+ * Provider preset defaults — mirrors providerPresets in src/cli/init.js.
+ * Injected server-side into ceremony objects that pre-date this feature.
+ */
+const PROVIDER_PRESETS = {
+  'sponsor-call': {
+    claude: {
+      provider: 'claude', defaultModel: 'claude-sonnet-4-6',
+      stages: {
+        suggestions:                   { provider: 'claude', model: 'claude-sonnet-4-6' },
+        documentation:                 { provider: 'claude', model: 'claude-sonnet-4-6' },
+        'architecture-recommendation': { provider: 'claude', model: 'claude-opus-4-6' },
+        'question-prefilling':         { provider: 'claude', model: 'claude-haiku-4-5-20251001' },
+      },
+      validation: {
+        provider: 'claude', model: 'claude-haiku-4-5-20251001',
+        documentation: { provider: 'claude', model: 'claude-haiku-4-5-20251001' },
+        refinement: { provider: 'claude', model: 'claude-sonnet-4-6' },
+      },
+    },
+    gemini: {
+      provider: 'gemini', defaultModel: 'gemini-2.5-flash',
+      stages: {
+        suggestions:                   { provider: 'gemini', model: 'gemini-2.5-flash' },
+        documentation:                 { provider: 'gemini', model: 'gemini-2.5-flash' },
+        'architecture-recommendation': { provider: 'gemini', model: 'gemini-2.5-pro' },
+        'question-prefilling':         { provider: 'gemini', model: 'gemini-2.5-flash-lite' },
+      },
+      validation: {
+        provider: 'gemini', model: 'gemini-2.5-flash-lite',
+        documentation: { provider: 'gemini', model: 'gemini-2.5-flash-lite' },
+        refinement: { provider: 'gemini', model: 'gemini-2.5-flash' },
+      },
+    },
+    openai: {
+      provider: 'openai', defaultModel: 'gpt-5.4',
+      stages: {
+        suggestions:                   { provider: 'openai', model: 'gpt-5.4' },
+        documentation:                 { provider: 'openai', model: 'gpt-5.4' },
+        'architecture-recommendation': { provider: 'openai', model: 'gpt-5.4' },
+        'question-prefilling':         { provider: 'openai', model: 'gpt-5-mini' },
+      },
+      validation: {
+        provider: 'openai', model: 'gpt-5.4',
+        documentation: { provider: 'openai', model: 'gpt-5.4' },
+        refinement: { provider: 'openai', model: 'gpt-5.4' },
+      },
+    },
+    xiaomi: {
+      provider: 'xiaomi', defaultModel: 'mimo-v2-flash',
+      stages: {
+        suggestions:                   { provider: 'xiaomi', model: 'mimo-v2-flash' },
+        documentation:                 { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        'architecture-recommendation': { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        'question-prefilling':         { provider: 'xiaomi', model: 'mimo-v2-flash' },
+      },
+      validation: {
+        provider: 'xiaomi', model: 'mimo-v2-flash',
+        documentation: { provider: 'xiaomi', model: 'mimo-v2-flash' },
+        refinement: { provider: 'xiaomi', model: 'mimo-v2-pro' },
+      },
+    },
+  },
+  'sprint-planning': {
+    claude: {
+      provider: 'claude', defaultModel: 'claude-sonnet-4-6',
+      stages: {
+        decomposition:        { provider: 'claude', model: 'claude-opus-4-6' },
+        validation:           { provider: 'claude', model: 'claude-sonnet-4-6', useContextualSelection: true, epicConcurrency: 2, concurrency: 5, batchSize: 8, maxFixAttempts: 3 },
+        'context-generation': { provider: 'claude', model: 'claude-sonnet-4-6' },
+        'doc-generation':     { provider: 'claude', model: 'claude-sonnet-4-6' },
+        enrichment:           { provider: 'claude', model: 'claude-sonnet-4-6' },
+      },
+    },
+    gemini: {
+      provider: 'gemini', defaultModel: 'gemini-2.5-flash',
+      stages: {
+        decomposition:        { provider: 'gemini', model: 'gemini-2.5-pro' },
+        validation:           { provider: 'gemini', model: 'gemini-2.5-flash', useContextualSelection: true, epicConcurrency: 2, concurrency: 5, batchSize: 8, maxFixAttempts: 3 },
+        'context-generation': { provider: 'gemini', model: 'gemini-2.5-flash' },
+        'doc-generation':     { provider: 'gemini', model: 'gemini-2.5-flash' },
+        enrichment:           { provider: 'gemini', model: 'gemini-2.5-flash' },
+      },
+    },
+    openai: {
+      provider: 'openai', defaultModel: 'gpt-5.4',
+      stages: {
+        decomposition:        { provider: 'openai', model: 'gpt-5.4' },
+        validation:           { provider: 'openai', model: 'gpt-5.4', useContextualSelection: true, epicConcurrency: 2, concurrency: 5, batchSize: 8, maxFixAttempts: 3 },
+        'context-generation': { provider: 'openai', model: 'gpt-5.4' },
+        'doc-generation':     { provider: 'openai', model: 'gpt-5.4' },
+        enrichment:           { provider: 'openai', model: 'gpt-5.4' },
+      },
+    },
+    xiaomi: {
+      provider: 'xiaomi', defaultModel: 'mimo-v2-pro',
+      stages: {
+        decomposition:        { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        validation:           { provider: 'xiaomi', model: 'mimo-v2-flash', useContextualSelection: true, epicConcurrency: 2, concurrency: 5, batchSize: 8, maxFixAttempts: 3 },
+        'context-generation': { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        'doc-generation':     { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        enrichment:           { provider: 'xiaomi', model: 'mimo-v2-pro' },
+      },
+    },
+  },
+  'seed': {
+    claude: {
+      provider: 'claude', defaultModel: 'claude-sonnet-4-6',
+      stages: {
+        decomposition:      { provider: 'claude', model: 'claude-opus-4-6' },
+        'doc-distribution': { provider: 'claude', model: 'claude-sonnet-4-6' },
+      },
+    },
+    gemini: {
+      provider: 'gemini', defaultModel: 'gemini-2.5-flash',
+      stages: {
+        decomposition:      { provider: 'gemini', model: 'gemini-2.5-pro' },
+        'doc-distribution': { provider: 'gemini', model: 'gemini-2.5-flash' },
+      },
+    },
+    openai: {
+      provider: 'openai', defaultModel: 'gpt-5.4',
+      stages: {
+        decomposition:      { provider: 'openai', model: 'gpt-5.4' },
+        'doc-distribution': { provider: 'openai', model: 'gpt-5.4' },
+      },
+    },
+    xiaomi: {
+      provider: 'xiaomi', defaultModel: 'mimo-v2-pro',
+      stages: {
+        decomposition:         { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        'doc-distribution':    { provider: 'xiaomi', model: 'mimo-v2-pro' },
+        'context-generation':  { provider: 'xiaomi', model: 'mimo-v2-pro' },
+      },
+    },
+  },
+};
+
+async function readOAuthStatus(projectRoot, env = {}) {
+  try {
+    const raw = await fs.readFile(path.join(projectRoot, '.avc', 'openai-oauth.json'), 'utf8');
+    const { accountId, expires } = JSON.parse(raw);
+    return { connected: true, accountId, expiresAt: expires,
+             expiresIn: Math.max(0, Math.round((expires - Date.now()) / 1000)),
+             fallback: env.OPENAI_OAUTH_FALLBACK === 'true' };
+  } catch { return { connected: false, fallback: false }; }
+}
+
+/**
+ * Settings Router
+ * Handles GET /api/settings and PUT sub-routes for project configuration.
+ * @param {string} projectRoot - Absolute path to project root
+ */
+export function createSettingsRouter(projectRoot) {
+  const router = express.Router();
+  const avcJsonPath = path.join(projectRoot, '.avc', 'avc.json');
+  const envPath = path.join(projectRoot, '.env');
+
+  const readAvcConfig = async () => {
+    try {
+      return JSON.parse(await fs.readFile(avcJsonPath, 'utf8'));
+    } catch {
+      return {};
+    }
+  };
+
+  const writeAvcConfig = async (config) => {
+    await fs.writeFile(avcJsonPath, JSON.stringify(config, null, 2), 'utf8');
+  };
+
+  // Parse .env into key→value map
+  const readEnv = async () => {
+    try {
+      const lines = (await fs.readFile(envPath, 'utf8')).split('\n');
+      const map = {};
+      for (const line of lines) {
+        const m = line.match(/^([A-Z_]+)\s*=\s*(.*)$/);
+        if (m) map[m[1]] = m[2].replace(/^["']|["']$/g, '');
+      }
+      return map;
+    } catch {
+      return {};
+    }
+  };
+
+  // Update or insert a single key in .env, preserving all other lines
+  const upsertEnvKey = async (key, value) => {
+    let content = '';
+    try { content = await fs.readFile(envPath, 'utf8'); } catch {}
+    const lines = content.split('\n');
+    const idx = lines.findIndex(l => l.match(new RegExp(`^${key}\\s*=`)));
+    const newLine = value ? `${key}=${value}` : '';
+    if (idx >= 0) {
+      if (newLine) {
+        lines[idx] = newLine;
+      } else {
+        lines.splice(idx, 1);
+      }
+    } else if (newLine) {
+      lines.push(newLine);
+    }
+    await fs.writeFile(envPath, lines.join('\n'), 'utf8');
+  };
+
+  // GET /api/settings/local-models — discover running local inference servers
+  router.get('/local-models', async (req, res) => {
+    try {
+      const { discoverLocalServers } = await import('../../../cli/llm-local.js');
+      const servers = await discoverLocalServers();
+      res.json({ servers });
+    } catch (err) {
+      res.status(500).json({ error: err.message, servers: [] });
+    }
+  });
+
+  // GET /api/settings — snapshot of all configurable settings
+  router.get('/', async (req, res) => {
+    try {
+      const [config, env] = await Promise.all([readAvcConfig(), readEnv()]);
+      const oauthStatus = await readOAuthStatus(projectRoot, env);
+      // Migrate existing projects: inject providerPresets if missing or incomplete
+      let configChanged = false;
+      const ceremonies = config?.settings?.ceremonies || [];
+      ceremonies.forEach((ceremony) => {
+        const defaultPresets = PROVIDER_PRESETS[ceremony.name];
+        if (!ceremony.providerPresets && defaultPresets) {
+          ceremony.providerPresets = defaultPresets;
+          configChanged = true;
+        } else if (ceremony.providerPresets && defaultPresets) {
+          for (const [provider, preset] of Object.entries(defaultPresets)) {
+            if (!ceremony.providerPresets[provider]) {
+              ceremony.providerPresets[provider] = preset;
+              configChanged = true;
+            }
+          }
+        }
+        // Migrate sprint-planning: doc-distribution → context-generation + doc-generation
+        if (ceremony.name === 'sprint-planning' && ceremony.stages) {
+          const old = ceremony.stages['doc-distribution'];
+          if (old) {
+            if (!ceremony.stages['context-generation']) ceremony.stages['context-generation'] = { ...old };
+            if (!ceremony.stages['doc-generation'])     ceremony.stages['doc-generation']     = { ...old };
+          }
+        }
+      });
+
+      // Inject missing models for new providers (e.g., xiaomi added after project init)
+      const models = config?.settings?.models || {};
+      const DEFAULT_MODELS = {
+        'mimo-v2-flash': { provider: 'xiaomi', displayName: 'MiMo V2 Flash', pricing: { input: 0.09, output: 0.29, unit: 'million', source: 'https://platform.xiaomimimo.com', lastUpdated: '2026-03-25' } },
+        'mimo-v2-pro':   { provider: 'xiaomi', displayName: 'MiMo V2 Pro',   pricing: { input: 1.00, output: 3.00, unit: 'million', source: 'https://platform.xiaomimimo.com', lastUpdated: '2026-03-25' } },
+        'mimo-v2-omni':  { provider: 'xiaomi', displayName: 'MiMo V2 Omni',  pricing: { input: 0.40, output: 2.00, unit: 'million', source: 'https://platform.xiaomimimo.com', lastUpdated: '2026-03-25' } },
+      };
+      for (const [modelId, modelDef] of Object.entries(DEFAULT_MODELS)) {
+        if (!models[modelId]) {
+          models[modelId] = modelDef;
+          configChanged = true;
+        } else if (!models[modelId].pricing?.source || !models[modelId].pricing?.lastUpdated) {
+          // Backfill missing pricing metadata for existing models
+          models[modelId].pricing = { ...models[modelId].pricing, ...modelDef.pricing };
+          configChanged = true;
+        }
+      }
+      if (config.settings) config.settings.models = models;
+
+      // Auto-switch ceremony providers when configured provider has no API key
+      // but another provider with a valid key is available.
+      const keyAvailable = (provider) => {
+        if (provider === 'local') return true;
+        if (provider === 'claude' || provider === 'anthropic') return !!env.ANTHROPIC_API_KEY;
+        if (provider === 'openai') return !!(env.OPENAI_API_KEY || (env.OPENAI_AUTH_MODE === 'oauth'));
+        if (provider === 'gemini') return !!env.GEMINI_API_KEY;
+        if (provider === 'xiaomi') return !!env.XIAOMI_API_KEY;
+        return false;
+      };
+      const FALLBACK_ORDER = ['claude', 'gemini', 'openai', 'xiaomi'];
+      const FALLBACK_MODELS = { claude: 'claude-sonnet-4-6', gemini: 'gemini-2.5-flash', openai: 'gpt-4.1', xiaomi: 'MiMo-V2-Flash' };
+      const findAvailable = () => FALLBACK_ORDER.find(p => keyAvailable(p)) || null;
+
+      for (const ceremony of ceremonies) {
+        const mainProvider = ceremony.provider || 'claude';
+        if (!keyAvailable(mainProvider)) {
+          const fallback = findAvailable();
+          if (fallback) {
+            console.log(`[settings] auto-switch: ${mainProvider}→${fallback} for ceremony ${ceremony.name}`);
+            const preset = ceremony.providerPresets?.[fallback];
+            const fallbackModel = preset?.defaultModel || FALLBACK_MODELS[fallback];
+
+            ceremony.provider = fallback;
+            ceremony.defaultModel = fallbackModel;
+
+            // Apply preset stage config (model + extra props like concurrency)
+            if (ceremony.stages && typeof ceremony.stages === 'object') {
+              for (const [stageName, stage] of Object.entries(ceremony.stages)) {
+                const presetStage = preset?.stages?.[stageName];
+                if (presetStage) {
+                  Object.assign(stage, presetStage);
+                } else {
+                  stage.provider = fallback;
+                  stage.model = fallbackModel;
+                }
+              }
+            }
+
+            // Apply preset validation models or fall back to default model
+            if (ceremony.validation && typeof ceremony.validation === 'object') {
+              const presetVal = preset?.validation;
+              ceremony.validation.provider = fallback;
+              ceremony.validation.model = presetVal?.model || fallbackModel;
+              for (const [k, v] of Object.entries(ceremony.validation)) {
+                if (v && typeof v === 'object' && typeof v.provider === 'string') {
+                  const presetSub = presetVal?.[k];
+                  v.provider = fallback;
+                  v.model = presetSub?.model || presetVal?.model || fallbackModel;
+                }
+              }
+            }
+            configChanged = true;
+          }
+        }
+      }
+
+      // Re-apply provider presets to repair stale stage models
+      // (handles case where a previous auto-switch set all stages to a single default model)
+      for (const ceremony of ceremonies) {
+        const provider = ceremony.provider || 'claude';
+        const preset = ceremony.providerPresets?.[provider];
+        if (!preset) continue;
+
+        let repaired = false;
+        if (preset.defaultModel && ceremony.defaultModel !== preset.defaultModel) {
+          ceremony.defaultModel = preset.defaultModel;
+          repaired = true;
+        }
+        if (ceremony.stages && preset.stages) {
+          for (const [stageName, stage] of Object.entries(ceremony.stages)) {
+            const ps = preset.stages[stageName];
+            if (ps && stage.model !== ps.model) {
+              Object.assign(stage, ps);
+              repaired = true;
+            }
+          }
+        }
+        if (ceremony.validation && typeof ceremony.validation === 'object' && preset.validation) {
+          if (preset.validation.model && ceremony.validation.model !== preset.validation.model) {
+            ceremony.validation.provider = provider;
+            ceremony.validation.model = preset.validation.model;
+            repaired = true;
+          }
+          for (const [k, v] of Object.entries(ceremony.validation)) {
+            if (v && typeof v === 'object' && typeof v.provider === 'string' && preset.validation[k]) {
+              if (v.model !== preset.validation[k].model) {
+                v.provider = provider;
+                v.model = preset.validation[k].model;
+                repaired = true;
+              }
+            }
+          }
+        }
+        if (repaired) {
+          console.log(`[settings] repaired stage models for ${ceremony.name} using ${provider} preset`);
+          configChanged = true;
+        }
+      }
+
+      // Persist all migrations to avc.json so other endpoints see them
+      if (configChanged) {
+        try { await writeAvcConfig(config); } catch {}
+      }
+
+      res.json({
+        apiKeys: {
+          anthropic: {
+            isSet:   !!env.ANTHROPIC_API_KEY,
+            preview: env.ANTHROPIC_API_KEY ? env.ANTHROPIC_API_KEY.slice(0, 10) + '…' : '',
+          },
+          gemini: {
+            isSet: !!env.GEMINI_API_KEY,
+            preview: env.GEMINI_API_KEY ? env.GEMINI_API_KEY.slice(0, 10) + '…' : '',
+          },
+          openai: {
+            isSet:    !!(env.OPENAI_API_KEY || oauthStatus.connected),
+            preview:  env.OPENAI_API_KEY ? env.OPENAI_API_KEY.slice(0, 10) + '…' : '',
+            authMode: env.OPENAI_AUTH_MODE || 'api-key',
+            oauth:    oauthStatus,
+          },
+          xiaomi: {
+            isSet: !!env.XIAOMI_API_KEY,
+            preview: env.XIAOMI_API_KEY ? env.XIAOMI_API_KEY.slice(0, 10) + '…' : '',
+          },
+          local: {
+            isSet: true,  // No API key needed — availability checked via /local-models
+            preview: 'localhost',
+          },
+        },
+        ceremonies,
+        models: (config?.settings?.models && Object.keys(config.settings.models).length > 0)
+          ? config.settings.models
+          : DEFAULT_MODELS,
+        missionGenerator: config?.settings?.missionGenerator || { validation: { maxIterations: 3, acceptanceThreshold: 95 } },
+        kanbanPort: config?.settings?.kanban?.port || 4174,
+        docsPort: config?.settings?.documentation?.port || 4173,
+        boardTitle: config?.settings?.kanban?.title || 'AVC Kanban Board',
+        costThresholds: config?.settings?.costThresholds || { 'sponsor-call': null, 'sprint-planning': null, 'seed': null },
+      });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/api-keys — only sends keys that are being updated
+  router.put('/api-keys', async (req, res) => {
+    try {
+      const { anthropic, gemini, openai, xiaomi } = req.body;
+      if (anthropic !== undefined) {
+        await upsertEnvKey('ANTHROPIC_API_KEY', anthropic);
+        if (anthropic) process.env.ANTHROPIC_API_KEY = anthropic;
+        else delete process.env.ANTHROPIC_API_KEY;
+      }
+      if (gemini !== undefined) {
+        await upsertEnvKey('GEMINI_API_KEY', gemini);
+        if (gemini) process.env.GEMINI_API_KEY = gemini;
+        else delete process.env.GEMINI_API_KEY;
+      }
+      if (openai !== undefined) {
+        await upsertEnvKey('OPENAI_API_KEY', openai);
+        if (openai) process.env.OPENAI_API_KEY = openai;
+        else delete process.env.OPENAI_API_KEY;
+      }
+      if (xiaomi !== undefined) {
+        await upsertEnvKey('XIAOMI_API_KEY', xiaomi);
+        if (xiaomi) process.env.XIAOMI_API_KEY = xiaomi;
+        else delete process.env.XIAOMI_API_KEY;
+      }
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/ceremonies — also accepts missionGenerator alongside ceremonies
+  router.put('/ceremonies', async (req, res) => {
+    try {
+      const { ceremonies, missionGenerator } = req.body;
+      if (!Array.isArray(ceremonies)) {
+        return res.status(400).json({ error: 'ceremonies must be an array' });
+      }
+      const config = await readAvcConfig();
+      if (!config.settings) config.settings = {};
+      config.settings.ceremonies = ceremonies;
+      // Persist missionGenerator validation params if provided
+      if (missionGenerator?.validation && typeof missionGenerator.validation === 'object') {
+        if (!config.settings.missionGenerator) config.settings.missionGenerator = {};
+        config.settings.missionGenerator.validation = {
+          maxIterations: Number(missionGenerator.validation.maxIterations) || 3,
+          acceptanceThreshold: Number(missionGenerator.validation.acceptanceThreshold) || 95,
+        };
+      }
+      await writeAvcConfig(config);
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/models — update pricing for all models
+  router.put('/models', async (req, res) => {
+    try {
+      const { models } = req.body;
+      if (!models || typeof models !== 'object' || Array.isArray(models)) {
+        return res.status(400).json({ error: 'models must be an object' });
+      }
+      const config = await readAvcConfig();
+      if (!config.settings) config.settings = {};
+      // Seed from defaults if models have never been persisted (migration for old projects)
+      if (!config.settings.models || Object.keys(config.settings.models).length === 0) {
+        config.settings.models = JSON.parse(JSON.stringify(DEFAULT_MODELS));
+      }
+      for (const [modelId, data] of Object.entries(models)) {
+        if (!config.settings.models[modelId]) continue; // only update existing models
+        if (data.pricing && typeof data.pricing === 'object') {
+          const today = new Date().toISOString().split('T')[0];
+          config.settings.models[modelId].pricing = {
+            input: Number(data.pricing.input) || 0,
+            output: Number(data.pricing.output) || 0,
+            unit: data.pricing.unit === 'thousand' ? 'thousand' : 'million',
+            source: typeof data.pricing.source === 'string' ? data.pricing.source.trim() : '',
+            lastUpdated: today,
+          };
+        }
+      }
+      await writeAvcConfig(config);
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/general — board title and/or ports
+  router.put('/general', async (req, res) => {
+    try {
+      const { boardTitle, kanbanPort, docsPort } = req.body;
+      const config = await readAvcConfig();
+      if (!config.settings) config.settings = {};
+      if (!config.settings.kanban) config.settings.kanban = {};
+      if (!config.settings.documentation) config.settings.documentation = {};
+      if (boardTitle !== undefined) config.settings.kanban.title = boardTitle.trim();
+      if (kanbanPort !== undefined) config.settings.kanban.port = Number(kanbanPort);
+      if (docsPort !== undefined) config.settings.documentation.port = Number(docsPort);
+      await writeAvcConfig(config);
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/cost-thresholds — update per-ceremony cost limits
+  router.put('/cost-thresholds', async (req, res) => {
+    try {
+      const { thresholds } = req.body;
+      const config = await readAvcConfig();
+      if (!config.settings) config.settings = {};
+      config.settings.costThresholds = thresholds;
+      await writeAvcConfig(config);
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // GET /api/settings/agents — list all agent names with customization status
+  router.get('/agents', (req, res) => {
+    try {
+      const names = readdirSync(LIB_AGENTS_PATH).filter(f => f.endsWith('.md')).sort();
+      const customDir = customAgentsDir(projectRoot);
+      const agents = names.map(name => ({
+        name,
+        isCustomized: existsSync(path.join(customDir, name)),
+      }));
+      res.json({ agents });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // GET /api/settings/agents/:name — get agent content (customized or default)
+  router.get('/agents/:name', (req, res) => {
+    const { name } = req.params;
+    if (!name.endsWith('.md') || name.includes('/') || name.includes('\\')) {
+      return res.status(400).json({ error: 'Invalid name' });
+    }
+    try {
+      const customPath = path.join(customAgentsDir(projectRoot), name);
+      const libPath = path.join(LIB_AGENTS_PATH, name);
+      if (!existsSync(libPath)) return res.status(404).json({ error: 'Agent not found' });
+      const isCustomized = existsSync(customPath);
+      const content = readFileSync(isCustomized ? customPath : libPath, 'utf8');
+      const defaultContent = readFileSync(libPath, 'utf8');
+      res.json({ name, content, isCustomized, defaultContent });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/agents/:name — save customized agent
+  router.put('/agents/:name', async (req, res) => {
+    const { name } = req.params;
+    const { content } = req.body;
+    if (!name.endsWith('.md') || name.includes('/') || name.includes('\\')) {
+      return res.status(400).json({ error: 'Invalid name' });
+    }
+    if (typeof content !== 'string') return res.status(400).json({ error: 'content must be a string' });
+    try {
+      const dir = customAgentsDir(projectRoot);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, name), content, 'utf8');
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // DELETE /api/settings/agents/:name — reset to library default
+  router.delete('/agents/:name', async (req, res) => {
+    const { name } = req.params;
+    if (!name.endsWith('.md') || name.includes('/') || name.includes('\\')) {
+      return res.status(400).json({ error: 'Invalid name' });
+    }
+    try {
+      const customPath = path.join(customAgentsDir(projectRoot), name);
+      try { await fs.unlink(customPath); } catch {}
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── Micro-Check Definitions API ────────────────────────────────────────────
+
+  // GET /api/settings/checks — list all check files with customization status
+  router.get('/checks', (req, res) => {
+    try {
+      const checks = [];
+      for (const scope of ['epic', 'story', 'code']) {
+        const scopeDir = path.join(LIB_CHECKS_PATH, scope);
+        if (!existsSync(scopeDir)) continue;
+        const files = readdirSync(scopeDir).filter(f => f.endsWith('.json')).sort();
+        for (const file of files) {
+          const perspective = file.replace(/\.json$/, '');
+          const customPath = path.join(customChecksDir(projectRoot), scope, file);
+          const content = JSON.parse(readFileSync(path.join(scopeDir, file), 'utf8'));
+          checks.push({
+            scope,
+            perspective,
+            checkCount: Array.isArray(content) ? content.length : 0,
+            isCustomized: existsSync(customPath),
+          });
+        }
+      }
+      // Cross-refs
+      const crossDir = path.join(LIB_CHECKS_PATH, 'cross-refs');
+      if (existsSync(crossDir)) {
+        for (const file of readdirSync(crossDir).filter(f => f.endsWith('.json')).sort()) {
+          const scope = file.replace(/\.json$/, '');
+          const customPath = path.join(customChecksDir(projectRoot), 'cross-refs', file);
+          const content = JSON.parse(readFileSync(path.join(crossDir, file), 'utf8'));
+          checks.push({
+            scope: 'cross-refs',
+            perspective: scope,
+            checkCount: Array.isArray(content) ? content.length : 0,
+            isCustomized: existsSync(customPath),
+          });
+        }
+      }
+      res.json({ checks });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // GET /api/settings/checks/:scope/:perspective — get check content
+  router.get('/checks/:scope/:perspective', (req, res) => {
+    const { scope, perspective } = req.params;
+    if (!['epic', 'story', 'code', 'cross-refs'].includes(scope) || /[/\\]/.test(perspective)) {
+      return res.status(400).json({ error: 'Invalid scope or perspective' });
+    }
+    try {
+      const libPath = path.join(LIB_CHECKS_PATH, scope, `${perspective}.json`);
+      if (!existsSync(libPath)) return res.status(404).json({ error: 'Check file not found' });
+      const customPath = path.join(customChecksDir(projectRoot), scope, `${perspective}.json`);
+      const isCustomized = existsSync(customPath);
+      const content = readFileSync(isCustomized ? customPath : libPath, 'utf8');
+      const defaultContent = readFileSync(libPath, 'utf8');
+      res.json({ scope, perspective, content, isCustomized, defaultContent });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // PUT /api/settings/checks/:scope/:perspective — save customized check file
+  router.put('/checks/:scope/:perspective', async (req, res) => {
+    const { scope, perspective } = req.params;
+    const { content } = req.body;
+    if (!['epic', 'story', 'code', 'cross-refs'].includes(scope) || /[/\\]/.test(perspective)) {
+      return res.status(400).json({ error: 'Invalid scope or perspective' });
+    }
+    if (typeof content !== 'string') return res.status(400).json({ error: 'content must be a string' });
+    // Validate JSON
+    try { JSON.parse(content); } catch { return res.status(400).json({ error: 'Invalid JSON' }); }
+    try {
+      const dir = path.join(customChecksDir(projectRoot), scope);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, `${perspective}.json`), content, 'utf8');
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // DELETE /api/settings/checks/:scope/:perspective — reset to built-in default
+  router.delete('/checks/:scope/:perspective', async (req, res) => {
+    const { scope, perspective } = req.params;
+    if (!['epic', 'story', 'code', 'cross-refs'].includes(scope) || /[/\\]/.test(perspective)) {
+      return res.status(400).json({ error: 'Invalid scope or perspective' });
+    }
+    try {
+      const customPath = path.join(customChecksDir(projectRoot), scope, `${perspective}.json`);
+      try { await fs.unlink(customPath); } catch {}
+      res.json({ status: 'ok' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  return router;
+}