docs: add docs/CONFIGURATION.md (env vars, settings.json, provider config reference)

docs/CONFIGURATION.md

@@ -0,0 +1,96 @@
+# Configuration
+
+claw-code configuration reference. For provider details, see [SUPPORTED_PROVIDERS.md](./SUPPORTED_PROVIDERS.md). For architecture, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## Configuration Sources
+
+claw-code reads configuration from multiple sources (in priority order):
+
+1. **CLI flags** — highest priority (e.g., `--model`, `--max-turns`, `--cwd`)
+2. **Environment variables** — `ANTHROPIC_*`, `OPENAI_*`, `XAI_*`, `DASHSCOPE_*`, `CLAW_*`, etc.
+3. **settings.json** — `.claw/settings.json` in the project directory, or `~/.claw/settings.json` as a user-level default
+4. **Hardcoded defaults** — lowest priority
+
+> **Known issue (#283):** Auto-compaction threshold (`CLAUDE_CODE_AUTO_COMPACT_INPUT_TOKENS`) is env-var-only; no `settings.json` key exists yet.
+> **Known issue (#282):** env-vs-config consolidation is incomplete; some settings only work in one source.
+
+## Environment Variables
+
+### Provider Authentication
+
+| Variable | Provider | Notes |
+|----------|----------|-------|
+| `ANTHROPIC_API_KEY` | Anthropic (Claude models) | Primary credential for Claude |
+| `ANTHROPIC_AUTH_TOKEN` | Anthropic | Alternative to `ANTHROPIC_API_KEY` |
+| `ANTHROPIC_BASE_URL` | Anthropic | Custom endpoint (e.g., proxy) |
+| `OPENAI_API_KEY` | OpenAI-compatible | Required for `gpt-*` / `openai/` models |
+| `OPENAI_BASE_URL` | OpenAI-compatible | Custom endpoint (OpenRouter, Ollama, etc.) |
+| `XAI_API_KEY` | xAI (Grok models) | Required for `grok-*` models |
+| `XAI_BASE_URL` | xAI | Custom endpoint |
+| `DASHSCOPE_API_KEY` | DashScope (Qwen/Kimi models) | Required for `qwen-*` / `kimi-*` models |
+| `DASHSCOPE_BASE_URL` | DashScope | Custom endpoint |
+
+### Model Selection
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ANTHROPIC_MODEL` | `claude-sonnet-4-6` | Default model when `--model` flag is not passed |
+
+### Runtime Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_CODE_AUTO_COMPACT_INPUT_TOKENS` | provider-specific | Auto-compaction trigger threshold (see #283) |
+| `CLAW_CONFIG_HOME` | `~/.claw` | Override config directory location |
+| `CLAWD_WEB_SEARCH_BASE_URL` | (built-in) | Custom base URL for web search tool |
+| `CLAWD_TODO_STORE` | `~/.claw/todos` | Override todo storage path |
+| `CLAWD_AGENT_STORE` | `~/.claw/agents` | Override agent store path |
+| `RUST_LOG` | `info` | Log verbosity (`trace`/`debug`/`info`/`warn`/`error`) |
+
+**Related paths also respected:** `CODEX_HOME`, `CLAUDE_CONFIG_DIR` (legacy compatibility).
+
+## settings.json
+
+Located at `.claw/settings.json` (project-local) or `~/.claw/settings.json` (user-level). Project-local takes precedence over user-level.
+
+Example:
+
+```json
+{
+  "model": "claude-sonnet-4-6"
+}
+```
+
+`claw /config` shows the merged, resolved configuration from all sources.
+
+> **Known gap (#285):** No declarative `providers` or `models` block in `settings.json`. Provider selection is currently model-prefix-based via a hardcoded `MODEL_REGISTRY`. See [SUPPORTED_PROVIDERS.md](./SUPPORTED_PROVIDERS.md) for the full provider/model matrix.
+
+## Provider Selection
+
+Provider is auto-selected from model name prefix or the `openai/` namespace prefix:
+
+| Model pattern | Provider | Auth env |
+|--------------|----------|----------|
+| `claude-*` | Anthropic | `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` |
+| `gpt-*`, `openai/*` | OpenAI-compatible | `OPENAI_API_KEY` |
+| `grok-*` | xAI | `XAI_API_KEY` |
+| `qwen-*`, `kimi-*` | DashScope | `DASHSCOPE_API_KEY` |
+
+When `OPENAI_BASE_URL` is set, the OpenAI-compatible provider is preferred for unrecognised model names — useful for Ollama or OpenRouter.
+
+## Session Storage
+
+Sessions are stored in `~/.claw/sessions/<session-id>/` (or under `CLAW_CONFIG_HOME`). Each session contains:
+
+- Conversation history (messages)
+- Session metadata (model, created_at, etc.)
+- Tool execution state
+
+See pinpoints #278 (version-comparison) and #279 (unknown-field policy) for known session persistence caveats.
+
+## Related Documents
+
+- [SUPPORTED_PROVIDERS.md](./SUPPORTED_PROVIDERS.md) — Provider/model matrix and auth details
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — Crate layout and request flow
+- [TROUBLESHOOTING.md](../TROUBLESHOOTING.md) — Failure mitigation
+- [ROADMAP.md](../ROADMAP.md) — Pinpoints by cluster