# Configuration

> Global config for the fable-agent system.
> Read by AGENT.md on startup. Edit to change behavior across all sessions.

---

## Model Routing

| Tier | Model | Use Case | Status |
|------|-------|----------|--------|
| Mythos | ~~Fable 5~~ | Orchestration, planning | **BLOCKED** (June 12, 2026) |
| Mythos | ~~Mythos 5~~ | Glasswing-only | **BLOCKED** (June 12, 2026) |
| Opus | Opus 4.8 | Orchestration, vision, planning, routing | Available |
| Sonnet | Sonnet 4.6 | Bounded subtasks, code review, vision | Available |
| Haiku | Haiku | Quick grading, routine edits, file ops | Available |
| Frontier | GPT-4.1 | Alternative orchestrator | Available |
| Frontier | GPT-4o | Vision checks | Available |
| Reasoning | o3-mini | Verification, analysis | Available |
| Local | Local (Ollama/vLLM) | Offline, cheap tasks | Check status |
| Compound | OpenRouter Fusion | Fable-tier compound (draft→critique→fuse) | Available (needs key) |

Routing priority:
1. Never route to blocked models (Fable 5, Mythos 5)
2. Orchestration/planning → Opus 4.8 (or GPT-4.1 fallback)
3. Vision tasks → Opus 4.8 or GPT-4o (vision-capable)
4. Grading/verification → Haiku (cheapest, fast)
5. Code review → Sonnet 4.6
6. Fusion/compound → OpenRouter Fusion (or local panel dispatch)
7. Offline fallback → local model

---

## Data Paths

| Path | Purpose |
|------|---------|
| `~/.fable-agent/` | Persistent state root |
| `~/.fable-agent/sessions/` | Session checkpoints |
| `~/.fable-agent/skills/` | Skill registry (auto-synced with SKILLS/) |
| `~/.fable-agent/knowledge/` | Knowledge base entries |
| `~/.fable-agent/memory/` | Episodic, semantic, procedural memory |
| `~/.fable-agent/safety/` | Model overrides + incident log |
| `~/.fable-agent/scheduler/` | Scheduled task definitions |
| `~/.fable-agent/reviews/` | Skill sharpener reviews |
| `./LOGS/runs/` | Session logs (gitignored) |

---

## Loop Defaults

| Param | Default | Description |
|-------|---------|-------------|
| `maxIterations` | 20 | Max feedback loop iterations per goal |
| `convergenceThreshold` | 0.05 | Min improvement delta to avoid plateau |
| `contextTokenBudget` | 128000 | Max context tokens |
| `dreamInterval` | 3 | Dream every N goals |
| `heartbeatIntervalMs` | 30000 | Session heartbeat frequency |
| `loopDelayMs` | 1000 | Delay between loop iterations |

---

## Self-Validation

| Param | Default | Description |
|-------|---------|-------------|
| `maxRetries` | 2 | Max phase re-executions on validation failure |
| `enforceMinLength` | true | Reject outputs below phase-specific minimums |
| `forbidUncertainty` | true | Reject "maybe", "I don't know", "perhaps" |

---

## Safety

| Param | Default | Description |
|-------|---------|-------------|
| `autoBlockOnAuthError` | true | Block model on 401/403/404 |
| `maxRetriesPerModel` | 3 | Attempts before failing to fallback |
| `preferCheapGrader` | true | Route grading to cheapest available model |

## Runtime bootstrap

Environment values are loaded before command handlers run.

- `loadEnv()` (`src/upgrades/env-loader.ts`) is executed at CLI startup.
- Files loaded in order: `.env`, `.env.<NODE_ENV>`, `.env.local`.
- `NODE_ENV` controls which environment file is read as `.env.<NODE_ENV>`.
- Existing process variables are preserved; env files do not overwrite.

CLI command and docs parity:
- Command additions/removals should update [COMMANDS.md](/C:/Users/Artale/fable-agent/COMMANDS.md) first.
- Any changed runtime preconditions (proxy check, API requirements, auth sources) should be reflected in this config file and [README.md](/C:/Users/Artale/fable-agent/README.md).

## CLI environment matrix

| Variable | Use | Description |
|----------|-----|-------------|
| `EXA_API_KEY` | Exa | Used by `exa search`, `exa company`, `demo` |
| `OPENROUTER_API_KEY` | Fusion | Enables `fusion run --openrouter` |
| `FAL_KEY` | Media | Enables `fal-ai` engine for `generate image|video` |
| `FABLE_DATA_DIR` | Daemon | Overrides persistent storage root (`~/.fable-agent`) for daemon pid/log flow |
| `FABLE_DAEMON` | Daemon | Internal runtime marker used when running detached daemon |
| `HOME`/`USERPROFILE` | Daemon/State | Default fallback for storage and runtime paths |
| `NODE_ENV` | Runtime bootstrap | Selects `.env.<NODE_ENV>` load order |

## Proxy defaults

- Proxy host/port: `127.0.0.1:18901`
- Commands that health-check the proxy first:
  - `plinius godmode --proxy`
  - `pai cert` (unless `--skip-proxy-check`)
  - `pai proxy`


## Plinius + Fable5 behavior notes

- What changed: new diagnostics and upgrade commands now live under plinius (godmode, parseltongue, ultra, autotune, stm, refusal, observatory, liberation, transparency) and fable5 stack --enable-plinius turns on upgraded stack layers.
- Who should use: users who want stronger local diagnostics, refusal analysis, prompt hardening checks, and output transformations in looped execution.
- Risk: new diagnostics can be stricter and noisier; some transformed outputs are intentionally opinionated for safety.
- Defaults: these behaviors are opt-in; standard runs remain backward compatible unless --enable-plinius is explicitly set.

## Docs maintenance guard

Before merging command-facing changes:

1. Update COMMANDS.md for every .command and flag change in src/index.ts.
2. Update CONFIG.md when env vars, bootstrap, or proxy requirements change.
3. Run smoke checks:
   - node dist/index.js --help
   - node dist/index.js plinius --help
   - node dist/index.js fable5 stack smoke test --enable-plinius