@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/config.ts

@@ -0,0 +1,970 @@
+import { setPromptDirs } from "./prompts.ts"
+import { qualityConfig, type QualityConfig } from "./quality/budgets.ts"
+import { existsSync, readFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { forgeqeHome, projectDir, renamed } from "./tools.ts"
+
+import YAML from "yaml"
+
+import type { LlmProfile } from "./llm.ts"
+import type { ReplayMode } from "./types.ts"
+import { loadDotEnv } from "./env.ts"
+import { systemLocale } from "./locale.ts"
+import { currencyCode, currencyForLocale } from "./money.ts"
+import { listPrice, pricesDate, type DeploymentType, type ListPrice } from "./prices.ts"
+import { ragConfig, type RagConfig } from "./cases/rag.ts"
+
+export type BrowserConfig = {
+  headless: boolean
+  width: number
+  height: number
+  maxSteps: number
+  timeoutSeconds: number
+  visionDetail: "low" | "high"
+  allowedHosts: string[]
+  startUrl?: string
+  /** ForgeQE overlay in a visible browser: edge glow, a bar with the current step, the person's input locked. */
+  overlay: boolean
+  /** A second model call checks the finished run against the goal, and its verdict can fail a run the agent completed. */
+  judge: boolean
+}
+
+export type MemoryConfig = {
+  enabled: boolean
+  dir: string
+  replay: ReplayMode
+}
+
+function runtimeBin(value: unknown, base: string): string | undefined {
+  if (!value) return undefined
+  const s = String(value)
+  return /[\\/]/.test(s) ? path.resolve(base, s) : s
+}
+
+export type CodeConfig = {
+  /** Repo the coding agent writes the test into. Unset: no coding step after runs. */
+  repo?: string
+  maxAttempts: number
+  testTimeoutSeconds: number
+  /** Scribe's turn stops when one shell command it runs has failed this many times since ForgeQE last ran the test. */
+  stallAfter?: number
+  /** Give Scribe a Playwright-driven browser, set up like the run's, switched on once a step fails. */
+  liveBrowser?: boolean
+  /** Before Scribe starts, replay the run's steps as a Playwright script and hand over what worked and where it failed. */
+  replay?: boolean
+  /** Model for ForgeQE's agent and Scribe as provider/model, instead of the run's llms.json profile. */
+  model?: string
+  /** llms.json profile for the reviewer, which only reads and judges: a smaller, cheaper model is enough. */
+  reviewProfile?: string
+  /** Stop a coding job once it has used this many tokens (cached included), and report how far it got. */
+  maxTokens?: number
+  /** Most tool-calling steps in one of Scribe's turns (code.max_steps, default 50). */
+  maxSteps?: number
+  /** Move an unfinished test to a needs-attention folder (code.needs_attention, default true). */
+  needsAttention?: boolean
+  /** A working test with coding-standard issues gets one round to fix them (code.tidy, default true). */
+  tidy?: boolean
+  /** Agent runtime binary (`code.runtime`, or the older `code.opencode`); default: PATH, then the managed download. */
+  opencode?: string
+  /** Command that runs the repo's tests, for forgeqe heal; unset: the agent works it out. */
+  testCommand?: string
+}
+
+export type SourcesConfig = {
+  /** Post results back to Azure DevOps, Jira, or Xray after a suite. */
+  writeBack: boolean
+  /** Test cases the agent writes from an Azure DevOps or Jira story are saved there, linked to the story (`save_cases`, default true). */
+  saveCases?: boolean
+  /** `mcp`: give ForgeQE's agent Microsoft's Azure DevOps MCP server (default true), loading `mcpDomains`. `project` limits ForgeQE's own test, sprint, and bug calls; omit it and those calls cover every project. The MCP server is the organization either way. */
+  ado?: { orgUrl: string; project?: string; tokenEnv: string; mcp?: boolean; mcpDomains?: string[] }
+  /**
+   * `cloud` (*.atlassian.net): email + API token. Server/Data Center: personal access token.
+   * `mcp`: which Jira MCP server ForgeQE's agent gets (default mcp-atlassian), or false for none.
+   */
+  jira?: { url: string; cloud: boolean; emailEnv: string; tokenEnv: string; mcp?: JiraMcp | false }
+  /** Xray Cloud API; Xray Server/Data Center goes through the jira settings. */
+  xray: { url: string; clientIdEnv: string; clientSecretEnv: string }
+  /** Confluence pages as requirements for ForgeQE's agent. Cloud: email + API token; Server/DC: personal access token. */
+  confluence?: { url: string; cloud: boolean; emailEnv: string; tokenEnv: string; space?: string }
+  /** TestRail: email + API key. */
+  testrail?: { url: string; emailEnv: string; tokenEnv: string; projectId?: number }
+  /** Zephyr Scale Cloud: API access token. */
+  zephyr?: { url: string; tokenEnv: string; projectKey?: string }
+  /** qTest Manager: API bearer token. `statuses` are the automation result names mapped in qTest. */
+  qtest?: { url: string; tokenEnv: string; projectId: number; statuses: { passed: string; failed: string; error: string } }
+  /** File a bug for each failed case, or comment on the open one ForgeQE filed before. */
+  bugs?: BugsConfig
+}
+
+export type BugsConfig = {
+  system: "jira" | "azure_devops"
+  /** Jira project key. Azure DevOps uses this, or sources.azure_devops.project. */
+  project?: string
+  /** Jira issue type or Azure DevOps work item type. */
+  type: string
+  labels: string[]
+  /** Azure DevOps area path. */
+  areaPath?: string
+  /** Also file bugs for cases that could not run (status error). */
+  onError: boolean
+}
+
+/** A site the browser agent can sign in to. Values come from the environment; the agent only sees placeholders. */
+export type LoginConfig = {
+  name: string
+  /** Engine domain patterns, e.g. https://staging.example.com or https://*.example.com. */
+  domains: string[]
+  url?: string
+  usernameEnv?: string
+  passwordEnv?: string
+  /** Authenticator (TOTP) secret, base32. */
+  totpEnv?: string
+  /** Cookies and local storage kept between runs; unset when save_session is false. */
+  sessionFile?: string
+}
+
+export type ReportConfig = {
+  /** Step screenshots in reports: every step, only failed runs, or none. */
+  screenshots: "all" | "failures" | "off"
+  /** Accessibility checks on each page the browser agent visits. */
+  accessibility: boolean
+}
+
+export type ReleaseThresholds = {
+  /** Open bugs of severity 1 (critical) and 2 (high) allowed. */
+  maxCritical: number
+  maxHigh: number
+  /** Executed test cases that must pass, in percent. */
+  minPassRate: number
+  /** A story with no test case is a risk (true) or ignored. */
+  requireTests: boolean
+}
+
+export const DEFAULT_THRESHOLDS: ReleaseThresholds = { maxCritical: 0, maxHigh: 0, minPassRate: 95, requireTests: true }
+
+function releaseThresholds(raw: unknown): ReleaseThresholds {
+  const r = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {}
+  const num = (v: unknown, d: number) => (v === undefined || v === null || v === "" || Number.isNaN(Number(v)) ? d : Number(v))
+  return {
+    maxCritical: num(r.max_critical, DEFAULT_THRESHOLDS.maxCritical),
+    maxHigh: num(r.max_high, DEFAULT_THRESHOLDS.maxHigh),
+    minPassRate: num(r.min_pass_rate, DEFAULT_THRESHOLDS.minPassRate),
+    requireTests: r.require_tests !== false,
+  }
+}
+
+export type FlakyConfig = {
+  /** Runs of a failed test in the same run, to tell a flaky failure from a real one (flaky.retries, default 1). */
+  retries: number
+  /** suggest (default): the agent offers to quarantine a flaky test; auto: ForgeQE does; off: history only. */
+  quarantine: "suggest" | "auto" | "off"
+  /** Flakiness score (passes on retry, plus pairs of flips, in the last 20 runs) from which a test counts as flaky. */
+  flakyAfter: number
+}
+
+export type ApiConfig = {
+  /** Record the application's API calls in every browser run (network.json), for API and contract tests (api.capture, default on). */
+  capture: boolean
+  /** Base URL contracts run against when it is not the one they were recorded or described with. */
+  baseUrl?: string
+  /** Headers every API call sends, with ${NAME} for values from the environment (e.g. Authorization: Bearer ${API_TOKEN}). */
+  headers: Record<string, string>
+  /** Calls to other sites than the page's (CDNs, identity providers) are left out of contracts unless this is on. */
+  thirdParty: boolean
+  timeoutSeconds: number
+}
+
+export type SuiteConfig = {
+  /** Browser runs at the same time. Coding runs one at a time. */
+  parallel: number
+  /** Write a test for each passed case when a repo is set. */
+  code: boolean
+  outDir: string
+  /** Check test cases before running them: warn (show the findings), block (skip cases that cannot run), or off. */
+  caseCheck?: "warn" | "block" | "off"
+}
+
+export type SkillsConfig = {
+  enabled: boolean
+  /** .forgeqe/skills next to forgeqe.yaml (the current folder without one). */
+  projectDir: string
+  /** ~/.forgeqe/skills, or under FORGEQE_HOME. */
+  userDir: string
+  /** `skills.dirs`, resolved against forgeqe.yaml; they win over every other source. */
+  dirs: string[]
+  /** Skill names turned off. */
+  disable: string[]
+  /** Also the skills other tools use: ~/.claude/skills, ~/.agents/skills, and the repository's .claude/.agents skills. */
+  external: boolean
+  /** Cap on the skill text added to the browser agent's prompt. */
+  browserMaxChars: number
+}
+
+export type MonitorConfig = {
+  /** Test case sources checked every round, as forgeqe suite takes them. */
+  checks: string[]
+  /** Time from the start of one round to the start of the next. */
+  everyMs: number
+  replay: ReplayMode
+  parallel: number
+  /** Failing rounds in a row before a check's first alert. */
+  failAfter: number
+  /** Alert again while a check keeps failing; 0: never. */
+  remindMs: number
+  /** Round folders kept in outDir; older ones are deleted. */
+  keep: number
+  writeBack: boolean
+  outDir: string
+  /** Where outDir is served, so alerts can link to each round's report. */
+  reportUrl?: string
+  alerts: MonitorAlerts
+}
+
+export type MonitorAlerts = {
+  /** A Teams incoming webhook or Workflows "when a webhook request is received" URL, from the environment. */
+  teams?: { webhookEnv: string }
+  email?: EmailConfig
+}
+
+/** What a channel is told about without being asked (notify: in forgeqe.yaml). */
+export const NOTIFY_EVENTS = ["suite_failed", "suite_passed", "release", "eval_failed"] as const
+export type NotifyEvent = (typeof NOTIFY_EVENTS)[number]
+
+/** A named place notifications go: a Teams channel's webhook, email, or both, and the events it gets. */
+export type NotifyChannel = MonitorAlerts & { name: string; on: NotifyEvent[] }
+
+export type NotifyConfig = {
+  /** Where the reports folder is published, so cards link to each report; in CI the build's page is linked too. */
+  reportUrl?: string
+  channels: NotifyChannel[]
+}
+
+function notifyConfig(raw: unknown): NotifyConfig | undefined {
+  const n = asRecord(raw)
+  const channels = Object.entries(asRecord(n.channels)).map(([name, value]): NotifyChannel => {
+    const c = asRecord(value)
+    const where = `notify.channels.${name}`
+    const alerts = monitorAlerts(c, where)
+    if (!alerts.teams && !alerts.email) throw new Error(`${where} needs teams (a webhook_env) or email.`)
+    const on = c.on === undefined ? ["suite_failed", "release", "eval_failed"] : (Array.isArray(c.on) ? c.on : [c.on]).map(String)
+    const unknown = on.filter((e) => !(NOTIFY_EVENTS as readonly string[]).includes(e))
+    if (unknown.length) throw new Error(`${where}.on: ${unknown.join(", ")} is not an event. Events: ${NOTIFY_EVENTS.join(", ")}.`)
+    return { name, ...alerts, on: on as NotifyEvent[] }
+  })
+  if (!channels.length) return undefined
+  return { channels, ...(n.report_url ? { reportUrl: trimUrl(n.report_url) } : {}) }
+}
+
+export type EmailConfig = {
+  host: string
+  port: number
+  /** TLS from the start (port 465); otherwise STARTTLS when the server offers it. */
+  secure: boolean
+  usernameEnv: string
+  passwordEnv: string
+  /** Default: the SMTP user name. */
+  from?: string
+  to: string[]
+}
+
+export type JiraMcp = "mcp-atlassian" | "rovo"
+
+/** An extra MCP server for ForgeQE's agent. Values may use {env:NAME}; the agent runtime fills them in. */
+export type ExtraMcpServer =
+  | { type: "local"; command: string[]; environment?: Record<string, string>; cwd?: string; timeout?: number; enabled?: boolean }
+  | { type: "remote"; url: string; headers?: Record<string, string>; timeout?: number; enabled?: boolean }
+
+export type AppConfig = {
+  configPath?: string
+  /** `mcp:` in forgeqe.yaml: more MCP servers for ForgeQE's agent, by name. */
+  mcp?: Record<string, ExtraMcpServer>
+  activeProfile: string
+  profiles: Record<string, LlmProfile>
+  llm: LlmProfile
+  browser: BrowserConfig
+  /**
+   * stepInstruction and guiderails are added to the browser agent's prompt. dirs: where edited prompts are looked for,
+   * highest precedence first (prompts.dir, the project's .forgeqe/prompts, ~/.forgeqe/prompts); see src/prompts.ts.
+   */
+  prompts: { stepInstruction: string; guiderails: string; dirs?: { dir: string; source: string }[] }
+  /** Product knowledge (.forgeqe/knowledge): see src/knowledge.ts. */
+  knowledge?: { dir: string; browserMaxChars: number }
+  export: { outDir: string; format: string }
+  memory: MemoryConfig
+  code: CodeConfig
+  sources: SourcesConfig
+  suite: SuiteConfig
+  logins: LoginConfig[]
+  /** Where saved browser sessions are kept: .forgeqe/sessions next to forgeqe.yaml. */
+  sessionsDir?: string
+  /** Session logs for debugging: .forgeqe/logs next to forgeqe.yaml. */
+  logsDir?: string
+  report: ReportConfig
+  monitor: MonitorConfig
+  skills: SkillsConfig
+  /** An optional requirements search (RAG) the test case check asks for passages: see src/cases/rag.ts. */
+  rag?: RagConfig
+  /** Flaky tests: retries in one run, and what to do with tests that keep flip-flopping (see src/code/history.ts). */
+  flaky?: FlakyConfig
+  /** Thresholds of the release-readiness verdict (release: in forgeqe.yaml). */
+  release?: ReleaseThresholds
+  /** API and contract tests (api: in forgeqe.yaml): see src/api/. */
+  api?: ApiConfig
+  /** Accessibility standard and accessibility/performance budgets (quality: in forgeqe.yaml): see src/quality/. */
+  quality?: QualityConfig
+  /** The product's industry and the regulations in scope (domain: in forgeqe.yaml): see src/domain.ts. */
+  domain?: DomainConfig
+  /** Teams and email notifications for suites, release readiness, and evaluations (notify: in forgeqe.yaml): see src/notify/. */
+  notify?: NotifyConfig
+}
+
+export type DomainConfig = {
+  /** In the team's words, e.g. "retail banking", "property and casualty insurance". */
+  industry: string
+  /** Regulations and standards in scope, e.g. DORA, PSD2, GDPR, ISO 27001. Their applicable controls go in the knowledge folder. */
+  regulations: string[]
+  /** Anything else the agents should know about the domain, in one or two sentences. */
+  notes?: string
+}
+
+function domainConfig(raw: unknown): DomainConfig | undefined {
+  const d = asRecord(raw)
+  const industry = String(d.industry || "").trim()
+  const list = Array.isArray(d.regulations) ? d.regulations : typeof d.regulations === "string" ? d.regulations.split(",") : []
+  const regulations = [...new Set(list.map((r) => String(r).trim()).filter(Boolean))]
+  if (!industry && !regulations.length) return undefined
+  return { industry, regulations, ...(d.notes ? { notes: String(d.notes).trim() } : {}) }
+}
+
+export function replayMode(raw: unknown): ReplayMode {
+  const mode = String(raw || "verify").toLowerCase()
+  if (mode === "trust" || mode === "off") return mode
+  if (mode !== "verify") throw new Error(`Unknown replay mode "${String(raw)}". Use verify, trust or off.`)
+  return "verify"
+}
+
+const MOCK_PROFILE: LlmProfile = { provider: "mock", model: "mock", temperature: 0 }
+const NO_PROFILE: LlmProfile = { provider: "none", model: "" }
+
+export function userConfigDir(): string {
+  return process.env.FORGEQE_CONFIG_DIR || renamed(path.join(os.homedir(), ".config"), "forgeqe", "webpilot")
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {}
+}
+
+function readJson(file: string): Record<string, unknown> {
+  if (!existsSync(file)) return {}
+  const data = JSON.parse(readFileSync(file, "utf8"))
+  return asRecord(data)
+}
+
+function readYaml(file: string): Record<string, unknown> {
+  if (!existsSync(file)) return {}
+  return asRecord(YAML.parse(readFileSync(file, "utf8")))
+}
+
+function visionDetail(raw: unknown): BrowserConfig["visionDetail"] {
+  return String(raw || "low").toLowerCase() === "high" ? "high" : "low"
+}
+
+function profileFromRaw(name: string, raw: Record<string, unknown>): LlmProfile {
+  const provider = String(raw.provider || "openai") as LlmProfile["provider"]
+  return {
+    provider,
+    model: String(raw.model || "gpt-4o"),
+    endpoint: raw.endpoint ? String(raw.endpoint) : undefined,
+    deployment: raw.deployment ? String(raw.deployment) : undefined,
+    apiKey: raw.api_key ? String(raw.api_key) : undefined,
+    apiKeyEnv: raw.api_key_env ? String(raw.api_key_env) : undefined,
+    ...(String(raw.auth || "").toLowerCase() === "entra" ? { auth: "entra" as const } : {}),
+    managedIdentityClientId: raw.managed_identity_client_id ? String(raw.managed_identity_client_id) : undefined,
+    tokenScope: raw.token_scope ? String(raw.token_scope) : undefined,
+    apiVersion: raw.api_version ? String(raw.api_version) : undefined,
+    temperature: typeof raw.temperature === "number" ? raw.temperature : undefined,
+    ...priceFor(name, raw, provider, String(raw.model || "gpt-4o")),
+  }
+}
+
+/**
+ * A profile's price: llms.json's when it sets one (a negotiated rate wins), with the cached-input price filled from
+ * the model's list discount when llms.json leaves it out; otherwise the model's list price. Also a warning when
+ * llms.json's price differs from the list price, which is usually a typo or an old price.
+ */
+function priceFor(name: string, raw: Record<string, unknown>, provider: string, model: string): Pick<LlmProfile, "price" | "priceWarning"> {
+  const deployment: DeploymentType = /data.?zone|^dz$/i.test(String(raw.deployment_type || "")) ? "data_zone" : "global"
+  const list = listPrice(provider, model, deployment)
+  const date = pricesDate()
+  const where = list ? `${list.source}${date ? `, ${date}` : ""}` : ""
+  const own = priceFromRaw(name, raw.price)
+  if (!own) {
+    if (!list) return {}
+    return {
+      price: {
+        input: list.input,
+        output: list.output,
+        currency: "USD",
+        ...(list.cacheRead !== undefined ? { cachedInput: list.cacheRead } : {}),
+        ...(list.cacheWrite !== undefined ? { cacheWrite: list.cacheWrite } : {}),
+        note: `list price of ${model}${provider === "azure" ? (deployment === "data_zone" ? " (Azure Data Zone)" : " (Azure Global)") : ""} from ${where}`,
+      },
+    }
+  }
+  const price = { ...own }
+  // A list in US dollars can only be compared with, or fill in, a price in US dollars.
+  const usable = list && own.currency === "USD" ? list : null
+  if (usable && price.cachedInput === undefined && usable.cacheRead !== undefined && usable.input > 0) {
+    const share = usable.cacheRead / usable.input
+    price.cachedInput = Math.round(price.input * share * 1e6) / 1e6
+    price.estimate = true
+    price.note = `cached input at ${Math.round(share * 100)}% of the input price, ${model}'s cache discount in its list price (${where})`
+  }
+  if (usable && price.cacheWrite === undefined && usable.cacheWrite !== undefined && usable.input > 0) price.cacheWrite = Math.round(price.input * (usable.cacheWrite / usable.input) * 1e6) / 1e6
+  return { price, ...(usable ? priceWarning(name, model, own, usable, where) : {}) }
+}
+
+function priceWarning(name: string, model: string, own: NonNullable<LlmProfile["price"]>, list: ListPrice, where: string): Pick<LlmProfile, "priceWarning"> {
+  const off = (a: number | undefined, b: number | undefined) => a !== undefined && b !== undefined && Math.abs(a - b) > Math.max(0.005, b * 0.01)
+  const diffs = [
+    off(own.input, list.input) ? `input ${money(own.input)} (list ${money(list.input)})` : "",
+    off(own.output, list.output) ? `output ${money(own.output)} (list ${money(list.output)})` : "",
+    off(own.cachedInput, list.cacheRead) ? `cached input ${money(own.cachedInput!)} (list ${money(list.cacheRead!)})` : "",
+  ].filter(Boolean)
+  if (!diffs.length) return {}
+  return {
+    priceWarning: `llms.json prices "${name}" (${model}) at ${diffs.join(", ")} per million tokens; the list price is from ${where}. Keep it for a negotiated rate, or remove the price to use the list price.`,
+  }
+}
+
+const money = (n: number) => `$${n < 1 ? n.toFixed(3).replace(/0+$/, "").replace(/\.$/, "") : n.toFixed(2)}`
+
+function priceFromRaw(profile: string, raw: unknown): LlmProfile["price"] {
+  if (raw === undefined || raw === null) return undefined
+  const p = asRecord(raw)
+  const input = Number(p.input)
+  const output = Number(p.output)
+  if (!Number.isFinite(input) || !Number.isFinite(output) || input < 0 || output < 0) {
+    throw new Error(`llms.json: "${profile}".price needs input and output, the price per million tokens (e.g. { "input": 2, "output": 8 }).`)
+  }
+  const currency = p.currency ? currencyCode(String(p.currency)) : currencyForLocale(systemLocale())
+  if (!currency) throw new Error(`llms.json: "${profile}".price.currency must be an ISO currency code (USD, EUR, GBP, …). Leave it out to use this machine's currency.`)
+  const rawCached = p.cached_input ?? p.cachedInput
+  if (rawCached === undefined || rawCached === null) return { input, output, currency }
+  const cachedInput = Number(rawCached)
+  if (!Number.isFinite(cachedInput) || cachedInput < 0) throw new Error(`llms.json: "${profile}".price.cached_input must be the price per million cached input tokens (e.g. 0.25).`)
+  return { input, output, currency, cachedInput }
+}
+
+/** Profiles from llms.json, without the mock entries older templates wrote; fallback is "" when there are none. */
+function loadProfiles(modelsFile: string | undefined): { profiles: Record<string, LlmProfile>; fallback: string } {
+  if (!modelsFile || !existsSync(modelsFile)) return { profiles: {}, fallback: "" }
+  const doc = readJson(modelsFile)
+  const models = asRecord(doc.models)
+  const profiles: Record<string, LlmProfile> = {}
+  for (const [name, value] of Object.entries(models)) {
+    const profile = profileFromRaw(name, asRecord(value))
+    if (profile.provider !== "mock" && name !== "mock") profiles[name] = profile
+  }
+  const fallback = typeof doc.default === "string" && profiles[doc.default] ? doc.default : Object.keys(profiles)[0] || ""
+  return { profiles, fallback }
+}
+
+function findConfigFile(explicit?: string): string | undefined {
+  if (explicit) {
+    const file = path.resolve(explicit)
+    if (!existsSync(file)) throw new Error(`Config not found: ${file}`)
+    return file
+  }
+  if (process.env.WP_CONFIG) {
+    const file = path.resolve(process.env.WP_CONFIG)
+    if (!existsSync(file)) throw new Error(`Config not found: ${file}`)
+    return file
+  }
+  const local = renamed(process.cwd(), "forgeqe.yaml", "webpilot.yaml")
+  if (existsSync(local)) return local
+  const global = renamed(userConfigDir(), "forgeqe.yaml", "webpilot.yaml")
+  if (existsSync(global)) return global
+  return undefined
+}
+
+/** Tokens one coding job (Scribe and its reviewer) may use when forgeqe.yaml sets no code.max_tokens. */
+export const DEFAULT_CODE_MAX_TOKENS = 1_500_000
+
+/** code.max_tokens: unset is the default budget, 0 (or less) turns the budget off. */
+function codeBudget(raw: unknown): number | undefined {
+  const n = raw === undefined || raw === null || raw === "" ? DEFAULT_CODE_MAX_TOKENS : Number(raw)
+  return n > 0 ? n : undefined
+}
+
+export function loadConfig(opts?: { configPath?: string; profile?: string }): AppConfig {
+  // FORGEQE_CWD_ENV=off: tests never read the .env of the folder they run in (the developer's own keys).
+  if (process.env.FORGEQE_CWD_ENV !== "off") loadDotEnv(process.cwd())
+  const configPath = findConfigFile(opts?.configPath)
+  if (configPath) loadDotEnv(path.dirname(configPath))
+  loadDotEnv(userConfigDir())
+
+  const yaml = configPath ? readYaml(configPath) : {}
+  const base = configPath ? path.dirname(configPath) : process.cwd()
+  const llm = asRecord(yaml.llm)
+  const browser = asRecord(yaml.browser)
+  const viewport = asRecord(browser.viewport)
+  const prompts = asRecord(yaml.prompts)
+  const exp = asRecord(yaml.export)
+  const memory = asRecord(yaml.memory)
+  const code = asRecord(yaml.code)
+  const sources = asRecord(yaml.sources)
+  const suite = asRecord(yaml.suite)
+  const outDir = exp.out_dir ? path.resolve(base, String(exp.out_dir)) : path.join(projectDir(base), "reports")
+
+  const modelsRel = process.env.WP_LLMS_JSON || (llm.models_file ? String(llm.models_file) : "./llms.json")
+  const projectModels = path.resolve(base, modelsRel)
+  const globalModels = path.join(userConfigDir(), "llms.json")
+  const modelsFile = existsSync(projectModels) ? projectModels : existsSync(globalModels) ? globalModels : undefined
+  const { profiles, fallback } = loadProfiles(modelsFile)
+
+  const asked = opts?.profile || process.env.WP_LLM_PROFILE
+  if (asked === "mock") profiles.mock = { ...MOCK_PROFILE }
+  const active = llm.active && String(llm.active) !== "mock" ? String(llm.active) : ""
+  const requested = asked || active || fallback
+  const activeProfile = profiles[requested] ? requested : fallback
+  if (opts?.profile && !profiles[opts.profile]) {
+    throw new Error(`Unknown LLM profile "${opts.profile}". Run: forgeqe models`)
+  }
+  if (code.review_profile && !profiles[String(code.review_profile)]) {
+    throw new Error(`code.review_profile in forgeqe.yaml names "${code.review_profile}", which is not a profile in llms.json. Run: forgeqe models`)
+  }
+
+  const hosts = Array.isArray(browser.allowed_hosts)
+    ? browser.allowed_hosts.map((h) => String(h)).filter(Boolean)
+    : []
+
+  const sessionsDir = configPath ? path.join(projectDir(base), "sessions") : path.join(forgeqeHome(), "sessions")
+  const config: AppConfig = {
+    configPath,
+    mcp: extraMcpServers(yaml.mcp, base),
+    activeProfile,
+    profiles,
+    llm: profiles[activeProfile] || { ...NO_PROFILE },
+    browser: {
+      headless: browser.headless !== false,
+      width: Number(viewport.width || 1280),
+      height: Number(viewport.height || 800),
+      maxSteps: Number(browser.max_steps || 40),
+      timeoutSeconds: Number(browser.timeout_seconds || 600),
+      visionDetail: visionDetail(browser.vision_detail),
+      allowedHosts: hosts,
+      startUrl: browser.start_url ? String(browser.start_url) : undefined,
+      overlay: browser.overlay !== false,
+      judge: browser.judge === true,
+    },
+    prompts: {
+      stepInstruction: String(prompts.step_instruction || ""),
+      guiderails: String(prompts.guiderails || ""),
+      dirs: promptDirsFor(prompts, base, configPath),
+    },
+    knowledge: knowledgeConfig(asRecord(yaml.knowledge), base, configPath),
+    export: {
+      outDir,
+      format: String(exp.format || "playwright"),
+    },
+    memory: {
+      enabled: memory.enabled !== false,
+      dir: memory.dir
+        ? path.resolve(base, String(memory.dir))
+        : configPath
+          ? path.join(projectDir(base), "memory")
+          : path.join(forgeqeHome(), "memory"),
+      replay: replayMode(memory.replay),
+    },
+    code: {
+      repo: code.repo ? path.resolve(base, String(code.repo)) : undefined,
+      maxAttempts: Number(code.max_attempts || 3),
+      testTimeoutSeconds: Number(code.test_timeout_seconds || 600),
+      stallAfter: Math.max(2, Number(code.stall_after || 5)),
+      liveBrowser: code.live_browser !== false,
+      replay: code.replay !== false,
+      model: code.model ? String(code.model) : undefined,
+      ...(code.review_profile ? { reviewProfile: String(code.review_profile) } : {}),
+      ...(codeBudget(code.max_tokens) ? { maxTokens: codeBudget(code.max_tokens) } : {}),
+      maxSteps: Number(code.max_steps) > 0 ? Number(code.max_steps) : 50,
+      needsAttention: code.needs_attention !== false,
+      tidy: code.tidy !== false,
+      opencode: runtimeBin(code.runtime || code.opencode, base),
+      ...(code.test_command ? { testCommand: String(code.test_command) } : {}),
+    },
+    sources: sourcesConfig(sources),
+    ...(ragConfig(yaml.rag) ? { rag: ragConfig(yaml.rag) } : {}),
+    flaky: flakyConfig(asRecord(yaml.flaky)),
+    release: releaseThresholds(yaml.release),
+    api: apiConfig(asRecord(yaml.api)),
+    quality: withBaselineDir(qualityConfig(yaml.quality), base, configPath),
+    domain: domainConfig(yaml.domain),
+    notify: notifyConfig(yaml.notify),
+    suite: {
+      parallel: Math.max(1, Number(suite.parallel || 1)),
+      code: suite.code !== false,
+      caseCheck: suite.case_check === "block" || suite.case_check === "off" || suite.case_check === false ? (suite.case_check === false ? "off" : suite.case_check) : "warn",
+      outDir: suite.out_dir ? path.resolve(base, String(suite.out_dir)) : path.join(outDir, "suites"),
+    },
+    logins: loginsConfig(yaml.logins, sessionsDir),
+    sessionsDir,
+    logsDir: path.join(path.dirname(sessionsDir), "logs"),
+    report: { screenshots: screenshotsMode(asRecord(yaml.report).screenshots), accessibility: asRecord(yaml.report).accessibility !== false },
+    monitor: monitorConfig(asRecord(yaml.monitor), base, outDir),
+    skills: skillsConfig(yaml.skills, base),
+  }
+  // Prompts resolve from these folders from now on (src/prompts.ts).
+  setPromptDirs(config.prompts.dirs || [])
+  return config
+}
+
+function skillsConfig(raw: unknown, base: string): SkillsConfig {
+  const s = asRecord(raw)
+  const list = (v: unknown) => (Array.isArray(v) ? v.map((x) => String(x).trim()).filter(Boolean) : [])
+  return {
+    enabled: raw !== false && s.enabled !== false,
+    projectDir: path.join(projectDir(base), "skills"),
+    userDir: path.join(forgeqeHome(), "skills"),
+    dirs: list(s.dirs).map((d) => path.resolve(base, d)),
+    disable: list(s.disable),
+    external: s.external === true,
+    browserMaxChars: positiveInt(s.browser_max_chars, 6000, "skills.browser_max_chars"),
+  }
+}
+
+/** "90s", "15m", "1h30m", "1d" in milliseconds. */
+export function parseDuration(raw: unknown, where: string): number {
+  const text = String(raw ?? "").trim().toLowerCase()
+  const parts = [...text.matchAll(/(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)/g)]
+  if (!text || !parts.length || parts.map((p) => p[0]).join("").replace(/\s/g, "") !== text.replace(/\s/g, "")) {
+    throw new Error(`${where} must be a duration such as 30s, 15m, 1h or 1h30m; got "${String(raw ?? "")}".`)
+  }
+  const unit = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const
+  return parts.reduce((ms, p) => ms + Number(p[1]) * unit[p[2] as keyof typeof unit], 0)
+}
+
+function positiveInt(raw: unknown, fallback: number, where: string): number {
+  if (raw === undefined || raw === null) return fallback
+  const n = Number(raw)
+  if (!Number.isInteger(n) || n < 1) throw new Error(`${where} must be a whole number of at least 1; got "${String(raw)}".`)
+  return n
+}
+
+function monitorConfig(m: Record<string, unknown>, base: string, outDir: string): MonitorConfig {
+  const checks = Array.isArray(m.checks) ? m.checks.map(String).filter(Boolean) : m.checks ? [String(m.checks)] : []
+  const everyMs = parseDuration(m.every ?? "15m", "monitor.every")
+  if (everyMs < 10_000) throw new Error("monitor.every must be at least 10s.")
+  const remind = m.remind_every
+  return {
+    checks,
+    everyMs,
+    replay: replayMode(m.replay),
+    parallel: positiveInt(m.parallel, 1, "monitor.parallel"),
+    failAfter: positiveInt(m.fail_after, 1, "monitor.fail_after"),
+    remindMs: remind === undefined || remind === null || remind === 0 || remind === false || remind === "0" ? 0 : parseDuration(remind, "monitor.remind_every"),
+    keep: positiveInt(m.keep, 100, "monitor.keep"),
+    writeBack: m.write_back === true,
+    outDir: m.out_dir ? path.resolve(base, String(m.out_dir)) : path.join(outDir, "monitor"),
+    ...(m.report_url ? { reportUrl: trimUrl(m.report_url) } : {}),
+    alerts: monitorAlerts(asRecord(m.alerts)),
+  }
+}
+
+function monitorAlerts(a: Record<string, unknown>, where = "monitor.alerts"): MonitorAlerts {
+  const out: MonitorAlerts = {}
+  if (a.teams !== undefined && a.teams !== null && a.teams !== false) {
+    out.teams = { webhookEnv: String(asRecord(a.teams).webhook_env || "TEAMS_WEBHOOK_URL") }
+  }
+  if (a.email !== undefined && a.email !== null && a.email !== false) {
+    const e = asRecord(a.email)
+    const host = String(e.host || process.env.SMTP_HOST || "").trim()
+    if (!host) throw new Error(`${where}.email needs host (the SMTP server), or SMTP_HOST.`)
+    const to = (Array.isArray(e.to) ? e.to.map(String) : String(e.to || process.env.ALERT_EMAIL_TO || "").split(/[,;]/)).map((s) => s.trim()).filter(Boolean)
+    if (!to.length) throw new Error(`${where}.email needs to: the addresses alerts go to.`)
+    const port = Number(e.port || process.env.SMTP_PORT || 587)
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`${where}.email.port is not a port: ${String(e.port)}`)
+    out.email = {
+      host,
+      port,
+      secure: e.secure === undefined ? port === 465 : e.secure === true,
+      usernameEnv: String(e.username_env || "SMTP_USERNAME"),
+      passwordEnv: String(e.password_env || "SMTP_PASSWORD"),
+      ...(e.from ? { from: String(e.from) } : {}),
+      to,
+    }
+  }
+  return out
+}
+
+function screenshotsMode(raw: unknown): ReportConfig["screenshots"] {
+  const v = raw === false ? "off" : String(raw ?? "all").toLowerCase()
+  if (v === "all" || v === "failures" || v === "off") return v
+  throw new Error(`report.screenshots must be all, failures, or off; got "${String(raw)}".`)
+}
+
+/** Domain pattern for a login URL: scheme and host, without port or path, as the engine matches them. */
+export function loginDomain(url: string): string {
+  const u = new URL(url)
+  return `${u.protocol}//${u.hostname}`
+}
+
+/** Re-read `logins:` from forgeqe.yaml so a login added while ForgeQE runs is found. */
+export function reloadLogins(cfg: AppConfig): LoginConfig[] {
+  if (!cfg.configPath || !existsSync(cfg.configPath)) return cfg.logins
+  const sessionsDir = path.join(projectDir(path.dirname(cfg.configPath)), "sessions")
+  cfg.logins = loginsConfig(readYaml(cfg.configPath).logins, sessionsDir)
+  return cfg.logins
+}
+
+/** `logins:` in forgeqe.yaml, a map of names to { url | domains, username_env, password_env, totp_env, save_session }. */
+function loginsConfig(raw: unknown, sessionsDir: string): LoginConfig[] {
+  if (raw === undefined || raw === null) return []
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("logins: in forgeqe.yaml must be a map of login names.")
+  return Object.entries(raw as Record<string, unknown>).map(([name, value]) => {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error(`Login name "${name}" may only use letters, digits, - and _.`)
+    const l = asRecord(value)
+    const url = l.url ? String(l.url) : undefined
+    let domains: string[]
+    try {
+      domains = Array.isArray(l.domains) ? l.domains.map(String).filter(Boolean) : url ? [loginDomain(url)] : []
+    } catch {
+      throw new Error(`logins.${name}.url is not a URL: ${url}`)
+    }
+    if (!domains.length) throw new Error(`logins.${name} needs a url (or domains) saying which site it signs in to.`)
+    const env = (k: string) => (l[k] ? String(l[k]) : undefined)
+    const login: LoginConfig = {
+      name,
+      domains,
+      ...(url ? { url } : {}),
+      ...(env("username_env") ? { usernameEnv: env("username_env") } : {}),
+      ...(env("password_env") ? { passwordEnv: env("password_env") } : {}),
+      ...(env("totp_env") ? { totpEnv: env("totp_env") } : {}),
+      ...(l.save_session === false ? {} : { sessionFile: path.join(sessionsDir, `${name}.json`) }),
+    }
+    if (!login.usernameEnv && !login.passwordEnv && !login.totpEnv && !login.sessionFile) {
+      throw new Error(`logins.${name} has nothing to use: set username_env, password_env, totp_env, or keep save_session on.`)
+    }
+    return login
+  })
+}
+
+function sourcesConfig(raw: Record<string, unknown>): SourcesConfig {
+  const ado = asRecord(raw.azure_devops)
+  const jira = asRecord(raw.jira)
+  const xray = asRecord(raw.xray)
+  const orgUrl = String(ado.org_url || process.env.ADO_ORG_URL || "").replace(/\/+$/, "")
+  const projectRaw = String(ado.project ?? process.env.ADO_PROJECT ?? "").trim()
+  const project = !projectRaw || projectRaw === "*" || /^all$/i.test(projectRaw) ? undefined : projectRaw
+  const jiraUrl = String(jira.url || process.env.JIRA_URL || "").replace(/\/+$/, "")
+  let cloud = false
+  if (jiraUrl) {
+    try {
+      cloud = jira.cloud === undefined ? new URL(jiraUrl).hostname.endsWith(".atlassian.net") : jira.cloud === true
+    } catch {
+      throw new Error(`sources.jira.url is not a URL: ${jiraUrl}`)
+    }
+  }
+  const domains = Array.isArray(ado.mcp_domains) ? ado.mcp_domains.map(String).filter(Boolean) : undefined
+  const jiraCfg = jiraUrl ? { url: jiraUrl, cloud, emailEnv: String(jira.email_env || "JIRA_EMAIL"), tokenEnv: String(jira.token_env || "JIRA_API_TOKEN") } : undefined
+  return {
+    writeBack: raw.write_back !== false,
+    saveCases: raw.save_cases !== false,
+    ado: orgUrl
+      ? { orgUrl, ...(project ? { project } : {}), tokenEnv: String(ado.token_env || "ADO_PAT"), mcp: ado.mcp !== false, ...(domains?.length ? { mcpDomains: domains } : {}) }
+      : undefined,
+    jira: jiraCfg ? { ...jiraCfg, mcp: jiraMcp(jira.mcp) } : undefined,
+    xray: {
+      url: String(xray.url || process.env.XRAY_URL || "https://xray.cloud.getxray.app").replace(/\/+$/, ""),
+      clientIdEnv: String(xray.client_id_env || "XRAY_CLIENT_ID"),
+      clientSecretEnv: String(xray.client_secret_env || "XRAY_CLIENT_SECRET"),
+    },
+    ...optional("confluence", confluenceConfig(raw.confluence, jiraCfg)),
+    ...optional("testrail", testrailConfig(asRecord(raw.testrail))),
+    ...optional("zephyr", zephyrConfig(raw.zephyr)),
+    ...optional("qtest", qtestConfig(asRecord(raw.qtest))),
+    ...optional("bugs", bugsConfig(raw.bugs)),
+  }
+}
+
+function flakyConfig(f: Record<string, unknown>): FlakyConfig {
+  const q = String(f.quarantine ?? "suggest")
+  return {
+    retries: f.retries === undefined ? 1 : Math.max(0, Math.min(3, Number(f.retries) || 0)),
+    quarantine: q === "auto" || q === "off" || q === "false" ? (q === "false" ? "off" : (q as "auto" | "off")) : "suggest",
+    flakyAfter: Number(f.flaky_after) > 0 ? Number(f.flaky_after) : 2,
+  }
+}
+
+
+/** Where edited prompts are looked for, highest precedence first: prompts.dir, the project's, then the user's. */
+function promptDirsFor(p: Record<string, unknown>, base: string, configPath: string | undefined): { dir: string; source: string }[] {
+  const dirs = [
+    ...(p.dir ? [{ dir: path.resolve(base, String(p.dir)), source: "prompts.dir" }] : []),
+    ...(configPath ? [{ dir: path.join(projectDir(base), "prompts"), source: "project" }] : []),
+    { dir: path.join(forgeqeHome(), "prompts"), source: "user" },
+  ]
+  return dirs.filter((d, i) => dirs.findIndex((x) => path.resolve(x.dir) === path.resolve(d.dir)) === i)
+}
+
+function knowledgeConfig(k: Record<string, unknown>, base: string, configPath: string | undefined): NonNullable<AppConfig["knowledge"]> {
+  const dir = k.dir ? path.resolve(base, String(k.dir)) : configPath ? path.join(projectDir(base), "knowledge") : path.join(forgeqeHome(), "knowledge")
+  const max = Number(k.browser_max_chars)
+  return { dir, browserMaxChars: Number.isFinite(max) && max >= 0 && k.browser_max_chars !== undefined ? max : 1500 }
+}
+
+/** Visual baselines next to forgeqe.yaml (.forgeqe/visual-baselines, to commit), or under ~/.forgeqe without one. */
+function withBaselineDir(q: QualityConfig, base: string, configPath: string | undefined): QualityConfig {
+  const dir = q.visual.baselineDir
+    ? path.resolve(base, q.visual.baselineDir)
+    : configPath
+      ? path.join(projectDir(base), "visual-baselines")
+      : path.join(forgeqeHome(), "visual-baselines")
+  return { ...q, visual: { ...q.visual, baselineDir: dir } }
+}
+
+function apiConfig(a: Record<string, unknown>): ApiConfig {
+  const headers = asRecord(a.headers)
+  return {
+    capture: a.capture !== false,
+    ...(a.base_url || a.baseUrl ? { baseUrl: trimUrl(a.base_url || a.baseUrl) } : {}),
+    headers: Object.fromEntries(Object.entries(headers).map(([k, v]) => [k, String(v ?? "")])),
+    thirdParty: a.third_party === true,
+    timeoutSeconds: Number(a.timeout_seconds) > 0 ? Number(a.timeout_seconds) : 30,
+  }
+}
+
+function optional<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
+  return value === undefined ? {} : ({ [key]: value } as Record<K, V>)
+}
+
+const trimUrl = (s: unknown) => String(s || "").trim().replace(/\/+$/, "")
+
+function isCloud(url: string, explicit: unknown, what: string): boolean {
+  try {
+    return explicit === undefined ? new URL(url).hostname.endsWith(".atlassian.net") : explicit === true
+  } catch {
+    throw new Error(`${what} is not a URL: ${url}`)
+  }
+}
+
+/** `confluence: true` uses the Jira Cloud site's /wiki with the same account; a map sets url, email_env, token_env, space. */
+function confluenceConfig(raw: unknown, jira?: { url: string; cloud: boolean; emailEnv: string; tokenEnv: string }): SourcesConfig["confluence"] {
+  if (raw === false) return undefined
+  const c = asRecord(raw)
+  const url = trimUrl(c.url || process.env.CONFLUENCE_URL || (raw === true && jira?.cloud ? `${jira.url}/wiki` : ""))
+  if (!url) {
+    if (raw === true) throw new Error("sources.confluence: true needs a Jira Cloud site in sources.jira; otherwise give confluence.url.")
+    return undefined
+  }
+  const cloud = isCloud(url, c.cloud, "sources.confluence.url")
+  const sameSite = Boolean(jira?.cloud && cloud && new URL(url).host === new URL(jira.url).host)
+  return {
+    url,
+    cloud,
+    emailEnv: String(c.email_env || (sameSite ? jira!.emailEnv : "CONFLUENCE_EMAIL")),
+    tokenEnv: String(c.token_env || (sameSite ? jira!.tokenEnv : "CONFLUENCE_TOKEN")),
+    ...(c.space ? { space: String(c.space) } : {}),
+  }
+}
+
+function testrailConfig(t: Record<string, unknown>): SourcesConfig["testrail"] {
+  const url = trimUrl(t.url || process.env.TESTRAIL_URL)
+  if (!url) return undefined
+  return {
+    url,
+    emailEnv: String(t.email_env || "TESTRAIL_EMAIL"),
+    tokenEnv: String(t.token_env || "TESTRAIL_API_KEY"),
+    ...(t.project_id ? { projectId: Number(t.project_id) } : {}),
+  }
+}
+
+function zephyrConfig(raw: unknown): SourcesConfig["zephyr"] {
+  if (raw === false) return undefined
+  const z = asRecord(raw)
+  const tokenEnv = String(z.token_env || "ZEPHYR_API_TOKEN")
+  if (raw === undefined && !process.env[tokenEnv]) return undefined
+  return {
+    url: trimUrl(z.url || process.env.ZEPHYR_URL || "https://api.zephyrscale.smartbear.com/v2"),
+    tokenEnv,
+    ...(z.project_key ? { projectKey: String(z.project_key) } : {}),
+  }
+}
+
+function qtestConfig(q: Record<string, unknown>): SourcesConfig["qtest"] {
+  const url = trimUrl(q.url || process.env.QTEST_URL)
+  if (!url) return undefined
+  const projectId = Number(q.project_id || process.env.QTEST_PROJECT_ID)
+  if (!projectId) throw new Error("sources.qtest needs project_id (the number in the project's URL), or QTEST_PROJECT_ID.")
+  const s = asRecord(q.statuses)
+  return {
+    url,
+    tokenEnv: String(q.token_env || "QTEST_TOKEN"),
+    projectId,
+    statuses: { passed: String(s.passed || "PASS"), failed: String(s.failed || "FAIL"), error: String(s.error || "BLOCKED") },
+  }
+}
+
+function bugsConfig(raw: unknown): BugsConfig | undefined {
+  if (raw === undefined || raw === null || raw === false) return undefined
+  const b = asRecord(raw)
+  const system = String(b.system || "").toLowerCase().replace(/[\s-]/g, "_")
+  if (system !== "jira" && system !== "azure_devops") throw new Error(`sources.bugs.system must be jira or azure_devops; got "${String(b.system ?? "")}".`)
+  if (system === "jira" && !b.project) throw new Error("sources.bugs.project is required for Jira: the project key bugs are filed in.")
+  return {
+    system,
+    ...(b.project ? { project: String(b.project) } : {}),
+    type: String(b.type || "Bug"),
+    labels: Array.isArray(b.labels) ? b.labels.map(String).filter(Boolean) : ["forgeqe"],
+    ...(b.area_path ? { areaPath: String(b.area_path) } : {}),
+    onError: b.on_error === true,
+  }
+}
+
+function jiraMcp(raw: unknown): JiraMcp | false {
+  if (raw === false || raw === "false" || raw === "off") return false
+  if (raw === undefined || raw === null || raw === true || raw === "mcp-atlassian") return "mcp-atlassian"
+  if (raw === "rovo") return "rovo"
+  throw new Error(`sources.jira.mcp must be mcp-atlassian, rovo, or false; got "${String(raw)}".`)
+}
+
+function stringMap(raw: unknown, where: string): Record<string, string> | undefined {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${where} must be a map of names to values.`)
+  return Object.fromEntries(Object.entries(raw as Record<string, unknown>).map(([k, v]) => [k, String(v)]))
+}
+
+/** `mcp:` servers: `command` (a list, or a string split on spaces) with `args`, `env`, `cwd`; or `url` with `headers`. */
+function extraMcpServers(raw: unknown, base: string): Record<string, ExtraMcpServer> | undefined {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw !== "object" || Array.isArray(raw)) throw new Error("mcp: in forgeqe.yaml must be a map of server names.")
+  const out: Record<string, ExtraMcpServer> = {}
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new Error(`MCP server name "${name}" may only use letters, digits, - and _.`)
+    if (name === "forgeqe") throw new Error('The MCP server name "forgeqe" is reserved for ForgeQE\'s own tools.')
+    const s = asRecord(value)
+    const common = {
+      ...(s.timeout !== undefined ? { timeout: Number(s.timeout) } : {}),
+      ...(s.enabled === false ? { enabled: false } : {}),
+    }
+    if (s.url) {
+      const headers = stringMap(s.headers, `mcp.${name}.headers`)
+      out[name] = { type: "remote", url: String(s.url), ...(headers ? { headers } : {}), ...common }
+    } else if (s.command) {
+      const command = [...(Array.isArray(s.command) ? s.command.map(String) : String(s.command).split(/\s+/).filter(Boolean)), ...(Array.isArray(s.args) ? s.args.map(String) : [])]
+      const environment = stringMap(s.env ?? s.environment, `mcp.${name}.env`)
+      out[name] = { type: "local", command, ...(environment ? { environment } : {}), ...(s.cwd ? { cwd: path.resolve(base, String(s.cwd)) } : {}), ...common }
+    } else {
+      throw new Error(`mcp.${name} needs a command (local server) or a url (remote server).`)
+    }
+  }
+  return out
+}
+
+export function selectProfile(cfg: AppConfig, name: string): AppConfig {
+  const llm = cfg.profiles[name]
+  if (!llm) throw new Error(`Unknown LLM profile "${name}". Run: forgeqe models`)
+  return { ...cfg, activeProfile: name, llm }
+}