Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

docs: refresh FCC architecture and repository guidance (#1667)

Ali Khokhar0917291fb122
diff --git a/AGENTS.md b/AGENTS.md
index 9e7fae7b..c768452e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,109 +1,126 @@
-# AGENTIC DIRECTIVE
-
-> Keep AGENTS.md and CLAUDE.md identical.
-
-## CODING ENVIRONMENT
-
-- Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
-- Install Python 3.14.0 stable using `uv python install 3.14.0` if not already installed (requires uv >=0.9; see `[tool.uv] required-version` in `pyproject.toml`)
-- Always use `uv run` to run files instead of the global `python` command.
-- Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
-- Read `.env.example` for environment variables.
-- All CI checks must pass; failing checks block merge.
-- Add tests for new changes (including edge cases).
-- Before pushing, prefer `./scripts/ci.sh` (macOS/Linux) or `.\scripts\ci.ps1` (Windows) to run the local CI sequence; requires `uv` on PATH. The local scripts run Ruff in repair mode (`ruff format`, then `ruff check --fix`) before type checking and tests.
-- Use `--only` / `--skip` (PowerShell: `-Only` / `-Skip`) to run a subset when iterating; use `--dry-run` to print commands without running them.
-- GitHub CI remains check-only for Ruff (`ruff format --check`, `ruff check`) so branch protection verifies committed code.
-- Fall back to individual repair commands when debugging local failures: `uv run ruff format`, `uv run ruff check --fix`, `uv run ty check`, `uv run pytest -v --tb=short`. Use GitHub-style checks only when verifying enforcement locally: `uv run ruff format --check`, `uv run ruff check`.
-- Do not add `# type: ignore` or `# ty: ignore`; fix the underlying type issue.
-- Do not add `from __future__ import annotations`; Python 3.14 native lazy annotations are the project standard.
-- All 6 check IDs are represented in `scripts/ci.sh` / `scripts/ci.ps1` and enforced by `tests.yml` before each merge (parallel jobs: suppression grep, ruff-format, ruff-check, ty, pytest, playwright).
-- Deterministic rendered Admin UI interactions live under `e2e/` and run separately from ordinary pytest. Install Chromium once with `uv run playwright install chromium`; API and unit contracts remain under `tests/`.
-- GitHub CI runs for every pull request, including stacked PRs targeting non-`main` branches. Head updates trigger fresh checks; strict required checks keep PRs targeting `main` current with `main`, so the tested PR tree is the tree squash-merged without a duplicate post-merge run.
-- A separate trusted `Dependency Cache` workflow runs after pushes to `main` only and is the sole writer for reusable Python and uv dependency caches. Pull-request jobs only restore caches; the maintenance workflow never reruns validation and is not a required status check.
-- Repository protection should use rulesets: a non-bypassable main integrity ruleset requires pull requests and strict required checks, keeps branches current, and blocks direct/force pushes to `main`; a separate review ruleset may allow `Alishahryar1`/admins to bypass review only.
-- Required status checks: set **required status checks** to **all** of those statuses (e.g. **Ban suppressions and legacy annotations**, **ruff-format**, **ruff-check**, **ty**, **pytest**, **playwright**—use the exact labels GitHub shows, which may be prefixed with **CI /**). Remove **ci** from required checks if it was previously added for the old gate job.
-
-## IDENTITY & CONTEXT
-
-- You are an expert Software Architect and Systems Engineer.
-- Goal: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush.
-- Code: Write the simplest code possible. Keep the codebase minimal and modular.
-
-## ARCHITECTURE PRINCIPLES
-
-- **Shared utilities**: Put shared Anthropic protocol logic in neutral `src/free_claude_code/core/anthropic/` modules. Do not have one provider import from another provider's utils.
-- **Failure ownership**: Keep canonical failure semantics and redaction SDK-free in `core/`; providers alone classify SDK/HTTP failures and own retries; protocol/API adapters alone choose wire error types and commit-boundary serialization.
-- **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
-- **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
-- **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
-- **Model-independent reasoning**: Resolve client reasoning intent once at the application boundary; provider adapters translate documented provider capabilities. Never branch on upstream model names or versions to choose reasoning behavior.
-- **Dead code**: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. `settings.provider_type` not `"nvidia_nim"`).
-- **Performance**: Use list accumulation for strings (not `+=` in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
-- **Platform-agnostic naming**: Use generic names (e.g. `PLATFORM_EDIT`) not platform-specific ones (e.g. `TELEGRAM_EDIT`) in shared code.
-- **Precise types**: Avoid `typing.Any`. Use owner-defined domain types for known values, `JsonValue`/`JsonObject` for JSON, and `object` only at genuinely opaque boundaries where the value is narrowed before use. Enforce this through design review and type checking, not a mechanical text ban in CI.
-- **No type ignores**: Do not add `# type: ignore` or `# ty: ignore`. Fix the underlying type issue.
-- **Python 3.14 annotations**: Do not use `from __future__ import annotations`; rely on native lazy annotations and fix circular import boundaries instead of hiding them with annotation stringization.
-- **Imports**: Prefer top-level imports. Avoid `TYPE_CHECKING` and local imports for first-party or required dependencies; if a top-level import creates a cycle, move shared types/protocols to a neutral owner.
-- **Complete migrations**: When moving modules, update imports to the new owner and remove old compatibility shims in the same change unless preserving a published interface is explicitly required.
-- **Maximum Test Coverage**: There should be maximum test coverage for everything, preferably live smoke test coverage to catch bugs early
-
-## COGNITIVE WORKFLOW
-
-1. **ANALYZE**: Read relevant files. Do not guess.
-2. **PLAN**: Map out the logic. Identify root cause or required changes. Order changes by dependency.
-3. **EXECUTE**: Fix the cause, not the symptom. Execute incrementally with clear commits.
-4. **VERIFY**: Run `./scripts/ci.sh` or `.\scripts\ci.ps1`, plus relevant smoke tests when needed. Confirm the fix via logs or output.
-5. **SPECIFICITY**: Do exactly as much as asked; nothing more, nothing less.
-6. **PROPAGATION**: Changes impact multiple files; propagate updates correctly.
-7. **VERSION**: If the commit touches production files on `main`, bump semver in the same commit (see [Versioning](#versioning-main)).
-
-## VERSIONING (MAIN)
-
-Every commit on `main` that changes a **production file** must include a semver bump in **`pyproject.toml`** in the **same commit**. Do not merge or push prod changes without updating the version.
-
-### Production files
-
-These paths count as production (runtime, packaging, or install surface):
-
-- `src/free_claude_code/api/`, `src/free_claude_code/cli/`, `src/free_claude_code/config/`, `src/free_claude_code/core/`, `src/free_claude_code/messaging/`, `src/free_claude_code/providers/`
-- `src/free_claude_code/application/`
-- `.env.example`
-- `pyproject.toml` (dependencies, scripts, packaging)
-- `scripts/install.sh`, `scripts/install.ps1`, `scripts/uninstall.sh`, `scripts/uninstall.ps1`, `scripts/ci.sh`, `scripts/ci.ps1`
-
-These do **not** require a version bump on their own:
-
-- `tests/`, `smoke/`
-- Docs and assets: `README.md`, `assets/`, `AGENTS.md`, `CLAUDE.md`
-- CI and repo config: `.github/`, `.gitignore`
-
-If a single commit mixes production and non-production edits, still bump the version.
-
-### Semver rules
-
-Use `[project].version` as `MAJOR.MINOR.PATCH`:
-
-- **PATCH** (`x.y.Z+1`): bug fixes, refactors with no user-visible behavior change, dependency updates, packaging/install fixes.
-- **MINOR** (`x.Y+1.0`): backward-compatible features—new providers, admin fields, CLI commands, config options, or behavior additions.
-- **MAJOR** (`X+1.0.0`): breaking changes—removed or renamed env vars, incompatible API/CLI/default changes, or migrations users must act on.
-
-When unsure between PATCH and MINOR, prefer PATCH for fixes and MINOR for new capability.
-
-### Required steps
-
-1. Classify the change and choose the bump level.
-2. Update `version` in `pyproject.toml`.
-3. Run `uv lock` so `uv.lock` reflects the new package version.
-4. Include the version and lockfile updates in the same commit as the production change.
-
-Example commit on `main` after a packaging fix: bump `1.2.38` → `1.2.39`, run `uv lock`, commit together with the fix.
-
-## SUMMARY STANDARDS
-
-- Summaries must be technical and granular.
-- Include: [Files Changed], [Logic Altered], [Verification Method], [Residual Risks] (if no residual risks then say none).
-
-## TOOLS
-
-- Prefer built-in tools (grep, read_file, etc.) over manual workflows. Check tool availability before use.
+# FCC Development Instructions
+
+Keep `AGENTS.md` and `CLAUDE.md` byte-for-byte identical.
+
+Free Claude Code is a local Python gateway connecting coding agents to configured
+AI providers. Read [ARCHITECTURE.md](ARCHITECTURE.md) for ownership and request
+flows, [README.md](README.md) for user workflows, and [.env.example](.env.example)
+for documented settings.
+
+## Tooling
+
+- Commands assume the repository root. Unrelated edits and untracked files are
+ outside the change scope; use `git ls-files` for tracked paths and `rg` for search.
+- Use `uv` for Python environments and `uv run` for Python tools/scripts. Follow
+ [.python-version](.python-version), `[tool.uv]` in [pyproject.toml](pyproject.toml),
+ and [uv.lock](uv.lock). Install missing prerequisites as needed; do not upgrade
+ tools or dependencies during unrelated work.
+- `uv sync --locked` prepares the development environment. Optional voice extras
+ are needed only for the corresponding live transcription work.
+- Never use the real `~/.fcc/` configuration, credentials, chat database, or
+ messaging state as disposable test fixtures. Use isolated temporary state.
+
+| Task | Command |
+| --- | --- |
+| Focused deterministic tests | `uv run pytest tests/<area>/test_<feature>.py -n 0 -q` |
+| Format / lint repair | `uv run ruff format <changed-paths>`; `uv run ruff check --fix <changed-paths>` |
+| Read-only format / lint checks | `uv run ruff format --check`; `uv run ruff check` |
+| Type checking | `uv run ty check` |
+| Full deterministic tests | `uv run pytest -v --tb=short` |
+| Browser setup / tests | `uv run playwright install chromium`; `uv run pytest e2e -n 0 -v --tb=short` |
+| Full local CI | Windows: `.\scripts\ci.ps1`; macOS/Linux: `./scripts/ci.sh` |
+
+Use full local CI before pushing code. The scripts run Ruff in repair mode
+before type checking and tests; review their diff. Use PowerShell
+`-Only` / `-Skip` / `-DryRun` or shell `--only` /
+`--skip` / `--dry-run` when iterating. Check IDs are `suppressions`,
+`ruff-format`, `ruff-check`, `ty`, `pytest`, and `playwright`.
+
+## Ownership And Contracts
+
+- `runtime/` composes services and owns process lifecycle and provider generations.
+ `api/` owns HTTP validation, authentication, product handlers, and response
+ commitment. `application/` owns routing, reasoning intent, model fallback, and
+ Chat use cases. Keep these responsibilities separate.
+- `core/` owns shared protocol models/conversion, failure semantics, and redaction.
+ `providers/` alone classifies SDK/HTTP failures and owns upstream attempts,
+ retries, and recovery. Protocol/API boundaries choose wire errors.
+- Provider metadata belongs in `config/provider_catalog.py`; ordinary upstream
+ differences belong in OpenAI Chat profiles. Add a specialized adapter only for
+ behavior/state a profile cannot express. Keep provider-only settings out of
+ shared `ProviderConfig`.
+- Resolve reasoning intent at the application boundary. Providers encode supported
+ controls; never infer reasoning behavior from upstream model names/versions.
+ Keep reasoning replay distinct from controls for the next generation.
+- Preserve each ingress protocol through the application boundary and the four
+ ingress/upstream cells. Do not introduce a lossy universal request model.
+ Preserve tool identity, call/result pairing, images, reasoning, usage, and
+ event order; reject unrepresentable input instead of silently dropping it.
+- Preserve stream commitment and resource ownership: no model fallback after
+ output commits, no duplicate terminal events, and no lease release before its
+ response/stream closes. Cancellation must drain owned work; shutdown must not
+ abandon partially closed resources or overlap replacement runtimes.
+- Keep config loading/provenance in `config/loader.py`, sparse Admin persistence
+ in `config/admin/`, and runtime Apply in `runtime/application.py`. The managed
+ `~/.fcc/.env` is the live file; repository `.env.example` is documentation.
+- Keep Chat revisions, operation settlement, and durable state consistent.
+ Messaging identities include platform/chat scope; stale tasks must not revive
+ cleared branches. Launchers own temporary client overlays, not native user
+ credentials/configuration.
+- Follow the exact dependency/facade policy in
+ [test_import_boundaries.py](tests/contracts/test_import_boundaries.py).
+ Change allowed edges deliberately, never just to silence a failing contract.
+
+## Python And Design
+
+- Use Python 3.14 native annotations. Do not add
+ `from __future__ import annotations`, `# type: ignore`, or `# ty: ignore`.
+- Use owner-defined types; `JsonValue`/`JsonObject` for JSON; narrowed `object`
+ only at opaque boundaries. Avoid `typing.Any`; fix the underlying model.
+- Prefer top-level imports. Resolve cycles through ownership, not
+ `TYPE_CHECKING` or annotation stringization. Preserve deliberate lazy loading
+ at existing optional-dependency, provider-factory, and lightweight CLI owners.
+- Prefer simple composition and shared helpers over duplicated behavior or
+ unnecessary base classes. Use public operations rather than another object's
+ private mutable state; keep platform/provider quirks at their adapters.
+
+## Verification By Change
+
+Changed behavior needs regression coverage, including relevant failure paths.
+
+| Change | Required evidence |
+| --- | --- |
+| Protocol/provider | Relevant core/provider tests; matrix/stream contracts for conversion or event changes |
+| Routing/lifecycle/failure | Application/API/runtime tests, including fallback, disconnect, cancellation, and cleanup paths affected |
+| Settings/Admin | Config/API contracts; deterministic `e2e/` tests for changed browser interactions |
+| Chat/messaging | Persistence, revision/scope isolation, concurrency, and stop/clear tests affected |
+| CLI/install/packaging | Launcher/script/packaging contracts; relevant installed-client smoke when needed |
+| Documentation only | Source accuracy, local links, instruction-file equality, and scoped `git diff --check` |
+
+Live checks are under [smoke/](smoke/README.md), separate from deterministic CI.
+Use `FCC_LIVE_SMOKE=1` and targeted `FCC_SMOKE_TARGETS` only for the relevant
+configured services; prerequisites alone do not prove product behavior. Live
+checks can consume quota or send/delete bot messages: use only authorized
+targets and report skips or missing prerequisites accurately.
+
+GitHub's [CI workflow](.github/workflows/tests.yml) runs Ruff in check-only mode
+and enforces all six checks; failing required checks block merge. The
+dependency-cache workflow is not a validation substitute.
+
+## Versioning And Documentation
+
+Every commit merged to `main` that changes production files must include a semver
+bump in `pyproject.toml` and the matching
+`uv lock` update. Production includes all installed code/assets under
+`src/free_claude_code/` (including `runtime/`), `.env.example`, runtime/dependency/
+packaging metadata, and install/uninstall/CI scripts.
+
+Use **PATCH** for fixes/refactors/dependency or packaging updates, **MINOR** for
+backward-compatible capabilities, and **MAJOR** for breaking API/CLI/configuration
+changes. Docs, tests, smoke tests, and repository workflow changes alone do not
+require a bump.
+
+Update `ARCHITECTURE.md` when ownership, public protocols, lifecycle, configuration,
+or extension paths change; update `README.md` and `.env.example` for user-facing
+setup/configuration changes. Keep volatile defaults and catalogs in their source
+owners, and keep these two instruction files concise and identical.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 3b099b3a..56c28f09 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1,2011 +1,505 @@
# Architecture
-This document is a maintainer-oriented map of Free Claude Code. It explains the
-runtime boundaries, request flows, provider abstraction, configuration model,
-optional messaging bridge, and verification strategy.
-
-For installation, provider setup, and user-facing usage, see
-[README.md](README.md). This file focuses on where behavior lives in the codebase
-and how contributors should extend it.
-
-## System Overview
-
-Free Claude Code is a local proxy for agent clients. It accepts Anthropic
-Messages traffic from Claude Code and Pi clients and OpenAI Responses traffic
-from Codex, OpenCode, Cline, Hermes, DeepSeek Harness, Grok Build, and Muse Code
-clients, routes the request to a configured upstream provider, and preserves
-the wire protocol expected by the caller.
-
-There are three runtime surfaces:
-
-- HTTP proxy: FastAPI routes expose Anthropic-compatible, Responses-compatible,
- health, model-listing, stop, and admin endpoints.
-- CLI launchers: wrapper entrypoints prepare Claude Code, Codex, Pi, OpenCode,
- Cline, Hermes, DeepSeek Harness, Grok Build, and Muse Code sessions so they
- target the local proxy.
-- Messaging bridge: optional Discord or Telegram adapters turn chat messages
- into managed client CLI sessions.
+Free Claude Code (FCC) is a local Python/FastAPI gateway between coding agents
+and configured AI providers. It preserves the client's public protocol while
+routing models, translating requests and streams, and managing upstream failures.
+
+This is the maintainer map. [README.md](README.md) covers installation and user
+workflows; [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) contain identical,
+concise development instructions. Source and executable contracts define current
+behavior; provider catalogs, client version requirements, and tuning constants
+stay with their implementation owners.
+
+## Product Surfaces
+
+- **Inference API:** Anthropic Messages and streaming OpenAI Responses, model
+ discovery, token counting, health checks, and task control.
+- **Server and desktop:** `fcc-server` and the Windows/macOS `fcc-desktop` shell
+ run the same application and expose the local Admin UI.
+- **Client launchers:** wrappers prepare client-specific FCC routing. Claude Code,
+ Pi, and Aider use Messages; Codex, OpenCode, Cline, Hermes, DeepSeek Harness,
+ Grok Build, and Muse Code use Responses.
+- **Chat Sessions:** local browser conversations with persisted history,
+ reasoning, model fallback, and context compaction.
+- **Messaging:** optional Discord/Telegram bridges drive managed Claude Code
+ sessions, including reply branches, task control, persistence, and voice input.
+
+Installed commands and packaged assets are defined in
+[pyproject.toml](pyproject.toml). Launcher support does not imply that a client is
+also available as a messaging-managed backend.
```mermaid
flowchart LR
- ClaudeCode[Claude Code CLI and Extensions] --> ProxyAPI[FastAPI Proxy]
- Codex[Codex CLI, IDE, and App] --> ProxyAPI
- Pi[Pi Coding Agent] --> ProxyAPI
- OpenCode[OpenCode CLI] --> ProxyAPI
- Cline[Cline CLI] --> ProxyAPI
- Hermes[Hermes Agent] --> ProxyAPI
- DSH[DeepSeek Harness] --> ProxyAPI
- Grok[Grok Build] --> ProxyAPI
- Muse[Muse Code] --> ProxyAPI
- AdminUI[Local Admin UI] --> ProxyAPI
- Bots[Discord or Telegram Bots] --> Messaging[Messaging Bridge]
- Messaging --> ClientCLI[Managed Client CLI Sessions]
- ClientCLI --> ProxyAPI
- ProxyAPI --> Handlers[API Product Handlers]
- Handlers --> Router[application ModelRouter]
- Handlers --> Executor[application ProviderExecutor]
- Executor --> Lease[Provider Generation Lease]
- Lease --> Providers[ProviderRuntime]
- Providers --> OpenAIChat[OpenAI Chat Provider Profiles And Specialized Adapters]
- Providers --> OpenAIResponses[Standard OpenAI Responses Transport]
- Providers --> NativeProviders[Native And Private Provider Adapters]
+ Clients[Coding agents] --> API[Messages / Responses API]
+ Admin[Local Admin UI] --> Runtime[Application runtime]
+ ChatUI[Chat Sessions UI] --> Chat[Chat application service]
+ Bots[Discord / Telegram] --> Messaging[Messaging workflow]
+ Messaging --> Managed[Managed Claude CLI]
+ Managed --> API
+ API --> Execution[Routing and provider execution]
+ Chat --> Execution
+ Chat --> Store[SQLite chat store]
+ Execution --> Providers[Provider adapters]
+ Providers --> Upstream[Chat Completions / Responses upstreams]
+ Runtime --> Chat
+ Runtime --> Messaging
+ Runtime --> Generations[Provider generations and model catalog]
+ Generations --> Providers
```
-## Package Boundaries
-
-The installable wheel packages are declared in [pyproject.toml](pyproject.toml):
-
-- [src/free_claude_code/application/](src/free_claude_code/application/) is the dependency-leaf application boundary. It
- owns immutable routing/model-metadata values, model routing, shared provider
- execution, the consumer-facing `ProviderPort`, request-runtime lease ports,
- task control, and deterministic request/readiness errors. It depends only on
- configuration and core protocol-neutral logic.
-- [src/free_claude_code/api/](src/free_claude_code/api/) is the HTTP adapter. It owns the FastAPI app, routes, API product
- handlers, local optimizations, model-catalog responses, HTTP error mapping,
- response commit timing, and Admin-specific ports. It consumes application and
- protocol types instead of defining use cases or wire schemas.
-- [src/free_claude_code/cli/](src/free_claude_code/cli/) owns console entrypoints, client CLI launchers, process/session
- management, and client adapter contracts.
-- [src/free_claude_code/config/](src/free_claude_code/config/) owns settings, provider metadata, filesystem paths,
- logging setup, constants, and provider ID catalogs.
-- [src/free_claude_code/core/](src/free_claude_code/core/) owns provider-neutral protocol logic: wire request and response
- models, Anthropic conversion, SSE construction, OpenAI Responses conversion,
- canonical execution-failure semantics, credential-safe diagnostics, token
- counting, and structured trace helpers. It never classifies provider SDK or
- HTTP client exceptions.
-- [src/free_claude_code/messaging/](src/free_claude_code/messaging/) owns optional platform adapters, incoming message
- handling, tree queues, transcript rendering, persistence, commands, and voice
- support.
-- [src/free_claude_code/providers/](src/free_claude_code/providers/) owns provider construction, the shared OpenAI-chat
- provider, specialized adapters, SDK/HTTP failure classification, retry and
- recovery policy, rate limiting, model listing, and concrete provider adapters.
-- [src/free_claude_code/runtime/](src/free_claude_code/runtime/) is the process composition root. It owns application
- startup and shutdown, provider generations, Admin runtime operations, and the
- concrete wiring between API, providers, messaging, and managed CLI sessions.
-
-[tests/](tests/) contains deterministic unit and contract coverage.
-[smoke/](smoke/) contains local and live product smoke tests that can launch
-subprocesses or touch real services.
-
-Production package imports follow one least-privilege dependency policy. Every
-listed edge is exercised by the current code; removing the last use of an edge
-also removes that permission:
-
-| Package | Exact allowed direct dependencies |
+## Package Ownership
+
+All production Python modules live under `src/free_claude_code/`.
+
+| Package | Responsibility | Allowed direct package dependencies |
+| --- | --- | --- |
+| [core](src/free_claude_code/core/) | Protocol schemas/conversion, canonical failures, diagnostics, shared primitives | None |
+| [config](src/free_claude_code/config/) | Settings, source loading, paths, provider metadata, Admin configuration | `core` |
+| [application](src/free_claude_code/application/) | Routing, reasoning intent, execution/fallback, model metadata, Chat use cases and ports | `config`, `core` |
+| [api](src/free_claude_code/api/) | HTTP adapters, authentication, product handlers, stream commitment, Admin/browser surfaces | `application`, `config`, `core` |
+| [providers](src/free_claude_code/providers/) | Provider construction, upstream I/O, discovery, admission, retries and recovery | `application`, `config`, `core` |
+| [cli](src/free_claude_code/cli/) | Server commands, desktop shell, client launchers and managed processes | `config`, `core` |
+| [messaging](src/free_claude_code/messaging/) | Platform adapters, workflow, conversation trees, rendering and voice orchestration | `core` |
+| [runtime](src/free_claude_code/runtime/) | Process composition, lifecycle, provider generations, concrete storage and cross-package wiring | All packages above |
+
+The exact exception is `cli.commands → runtime.bootstrap`: the installed server
+command must construct the application. The lightweight `cli.entrypoints`
+module handles metadata-only commands without importing the server graph.
+
+[Import-boundary contracts](tests/contracts/test_import_boundaries.py) enforce
+the package matrix, exact exception, acyclic static imports, facade ownership,
+and optional-dependency owners. External consumers use the public facades of
+`core.openai_responses`, `providers.openai_chat`, and `messaging.trees`.
+Internal modules do not import their ancestor facade. Dynamic factory loading
+also has catalog/factory synchronization checks.
+
+Optional local voice imports belong to `messaging.transcription`; NVIDIA Riva
+imports belong to `providers.nvidia_nim.voice`. They are lazy so ordinary
+installation, startup, and metadata commands do not require voice extras.
+
+## HTTP And Protocol Flow
+
+[api/app.py](src/free_claude_code/api/app.py) constructs FastAPI around an explicit
+`ApiServices` value. Runtime services are published through `app.state.services`;
+the app factory does not construct provider resources or load global settings.
+
+| Surface | Current behavior | Owner |
+| --- | --- | --- |
+| `POST /v1/messages` | Anthropic JSON response or SSE when `stream=true` | [Messages handler](src/free_claude_code/api/handlers/messages.py) |
+| `POST /v1/responses` | Responses SSE; omitted/true `stream` accepted, false rejected | [Responses handler](src/free_claude_code/api/handlers/responses.py) |
+| `POST /v1/messages/count_tokens` | Local pre-generation token estimate | [Token-count handler](src/free_claude_code/api/handlers/token_count.py) |
+| `GET /v1/models` | Claude, direct Messages, and direct Responses catalog views | [Model catalog](src/free_claude_code/api/model_catalog.py) |
+| `GET /muse-code/models` | Authenticated compatibility alias for the Responses model view | [Routes](src/free_claude_code/api/routes.py) |
+| `GET /`, `GET /health`, `POST /stop` | Status, liveness, and managed-task control; supported endpoints also expose probes | [Routes](src/free_claude_code/api/routes.py) |
+| `/admin`, `/admin/api/...` | Local configuration, provider/account operations, diagnostics | [Admin routes](src/free_claude_code/api/admin_routes.py) |
+| `/admin/chat`, `/admin/api/chat/...` | Local Chat UI, sessions, operations, preferences and event feed | [Chat routes](src/free_claude_code/api/chat_routes.py) |
+
+The inference path is:
+
+1. HTTP middleware establishes request correlation and disconnect ownership.
+2. The route acquires a provider-generation lease and builds its protocol handler.
+3. The handler validates the request and applies any protocol-specific product
+ policy. `ModelRouter` resolves the public model and reasoning intent.
+4. `ProviderExecutor` uses the application-owned `ProviderPort` to preflight and
+ stream the selected candidate, applying model fallback when eligible.
+5. The provider translates to its upstream transport and returns the ingress
+ protocol's SSE. The API owns final HTTP/error framing; non-streaming Messages
+ aggregates the same internal stream into JSON.
+6. Response finalization closes the body chain before releasing the lease.
+
+The application keeps concrete `MessagesRequest` and `OpenAIResponsesRequest`
+types. There is no universal intermediate request schema or
+Responses-to-Messages-to-Responses round trip.
+
+| Client ingress | Chat Completions upstream | Responses upstream |
+| --- | --- | --- |
+| Anthropic Messages | Anthropic-to-Chat conversion; Chat output presented as Anthropic SSE | Messages-to-Responses conversion; Responses output presented as Anthropic SSE |
+| OpenAI Responses | Direct Responses-to-Chat conversion; Chat output presented as Responses SSE | Native Responses forwarding with FCC routing/stateless-streaming policy |
+
+[core/anthropic](src/free_claude_code/core/anthropic/) owns Anthropic schemas,
+conversion, token estimation, and stream ledgers.
+[core/openai_responses](src/free_claude_code/core/openai_responses/) owns direct
+Responses conversion, native forwarding, and event/identity helpers.
+[Protocol-matrix tests](tests/contracts/test_protocol_matrix.py) exercise all
+four cells; [stream contracts](tests/contracts/test_stream_contracts.py) protect
+public event lifecycles.
+
+Translation preserves message order, tool declarations and call/result pairing,
+images, reasoning replay, public model identity, and usage semantics. Tool-name
+encoding is reversible and belongs to
+[core/openai_tool_names.py](src/free_claude_code/core/openai_tool_names.py).
+Rich tool results are translated into target-representable content while keeping
+their call association. Unsupported cross-protocol input, such as an image
+represented only by an upstream file ID, is rejected rather than silently lost.
+Native Responses forwarding preserves upstream item/call IDs, event order,
+extensions, and usage within FCC's supported streaming contract.
+
+## Routing, Reasoning, And Failures
+
+[ModelRouter](src/free_claude_code/application/routing.py) accepts direct
+`provider/model` references, encoded gateway IDs, and Claude-family names.
+Family overrides fall back to `MODEL`; `MODEL_FALLBACKS` supplies ordered
+alternate targets. Routed requests carry the upstream model separately from the
+original public model. A fallback on the same provider is valid if it selects a
+different model.
+
+[application/reasoning.py](src/free_claude_code/application/reasoning.py) combines
+client input and configured preferences into the immutable
+[ReasoningPolicy](src/free_claude_code/core/reasoning.py): control, named effort,
+and an optional exact token budget. Providers translate documented capabilities;
+they do not parse upstream model names or versions to select reasoning behavior.
+History replay is independent of the next generation's compute controls.
+Output limits are not reasoning budgets. Discovered thinking support informs
+model presentation, not request-policy inference.
+
+Failure ownership is deliberately split:
+
+| Owner | Decision |
| --- | --- |
-| `config` | none |
-| `core` | none |
-| `application` | `config`, `core` |
-| `messaging` | `core` |
-| `providers` | `application`, `config`, `core` |
-| `api` | `application`, `config`, `core` |
-| `cli` | `config`, `core` |
-| `runtime` | `api`, `application`, `cli`, `config`, `core`, `messaging`, `providers` |
-
-There is one exact exception:
-`free_claude_code.cli.entrypoints` imports
-`free_claude_code.runtime.bootstrap` because the installed server executable
-delegates construction to the process composition root. The exception does not
-permit any broader dependency from `cli` to `runtime`. Every new top-level
-package or cross-package edge must be added to the policy deliberately.
-
-Internal modules do not import an ancestor package facade; package initializers
-may import dependency leaves to publish supported exports. Code outside
-`core.openai_responses` and `messaging.trees` consumes those owners through their
-package facades. The supported top-level messaging extension surface is
-`IncomingMessage`, `MessageScope`, `ManagedClaudeSessionProtocol`,
-`ManagedClaudeSessionManagerProtocol`, and `OutboundMessenger`; workflow,
-persistence, parsing, and mutable tree implementations remain internal.
-
-Optional voice dependencies also have exact lazy owners:
-
-| Dependency | Owner |
+| [core/failures.py](src/free_claude_code/core/failures.py), [core/diagnostics.py](src/free_claude_code/core/diagnostics.py) | Canonical `ExecutionFailure` semantics and safe diagnostics, without transport SDKs |
+| [Provider failure policy](src/free_claude_code/providers/failure_policy.py) and specialized adapters | Classify upstream SDK/HTTP errors and qualify retries |
+| [Admission](src/free_claude_code/providers/admission.py) and [stream recovery](src/free_claude_code/providers/stream_recovery.py) | Physical attempt budget, coordinated admission/recovery, replay/continuation and commit holdback |
+| [ProviderExecutor](src/free_claude_code/application/execution.py) | Ordered model fallback and provider-progress deadline |
+| [API response streams](src/free_claude_code/api/response_streams.py) and protocol serializers | HTTP commitment and terminal error serialization |
+
+An executor candidate may advance on a canonical `ExecutionFailure` before its
+first non-empty protocol chunk. It closes the abandoned stream and opens the
+next target with a fresh request copy, retaining public identity and reasoning.
+Provider-local `retryable` metadata does not govern this model transition.
+Once a candidate emits output, fallback stops. Ordinary validation errors,
+unexpected exceptions, cancellation, and the application progress deadline do
+not become additional model retries.
+
+`PROVIDER_PROGRESS_TIMEOUT` bounds waiting for non-empty provider output,
+including admission, retries and fallback. Changing attempts/candidates does not
+reset the current wait; emitted output renews it. Downstream backpressure is
+outside that timer. Provider HTTP timeouts and client deadlines remain separate.
+
+Before HTTP commitment, final inference failures can use non-2xx JSON; after
+commitment they must terminate the existing protocol lifecycle. Messages emits
+an Anthropic error event; Responses uses `response.failed` with the existing
+response ID. Pre-commit execution-error responses include
+`x-should-retry: false`. Providers raise canonical failures rather than invent
+client error envelopes. Context-window exhaustion is a canonical failure kind;
+the Anthropic serializer owns Claude's compaction-trigger wording.
+
+See [execution failure contracts](tests/api/test_execution_failure_contract.py),
+[model fallback tests](tests/api/test_model_fallback.py), and
+[request lifetime tests](tests/api/test_request_lifetime.py).
+
+## Provider Construction And Discovery
+
+[config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py)
+owns provider IDs, authentication/readiness metadata, endpoint defaults, setting
+references and proxy metadata. It does not import provider implementations.
+
+[providers/runtime/factory.py](src/free_claude_code/providers/runtime/factory.py)
+assigns each provider exactly one construction owner:
+
+- An immutable [OpenAI Chat profile](src/free_claude_code/providers/openai_chat/profiles.py)
+ for ordinary request/reasoning/replay policy.
+- A specialized adapter for actual provider state, discovery, stream, or retry
+ algorithms that profile data cannot describe.
+- An injected factory for process-lifetime dependencies, such as connected-account
+ authentication.
+
+The construction-owner union must equal the catalog. Within a generation,
+[ProviderRuntime](src/free_claude_code/providers/runtime/runtime.py) lazily owns
+one provider and admission controller per provider ID.
+[ProviderConfig](src/free_claude_code/providers/base.py) contains resolved shared
+configuration; provider-specific fields remain in their adapter constructors.
+
+[OpenAIChatProvider](src/free_claude_code/providers/openai_chat/provider.py)
+implements the common Chat transport with explicit request policy, reasoning,
+tool assembly, usage and recovery collaborators.
+[OpenAIResponsesTransport](src/free_claude_code/providers/openai_responses/transport.py)
+borrows the owning provider's client/admission resources for standard Responses
+execution. It owns neither authentication nor model discovery.
+
+Specialized boundaries include
+[OpenCode catalog-selected transports](src/free_claude_code/providers/opencode/),
+[NIM tool/retry handling](src/free_claude_code/providers/nvidia_nim/),
+[shared Google wire behavior](src/free_claude_code/providers/google_openai/),
+[Vertex credentials/catalogs](src/free_claude_code/providers/vertex/), and
+[Codex subscription auth/private transport](src/free_claude_code/providers/openai_codex/).
+Codex's process-lifetime auth manager owns credentials and refresh; generation
+adapters borrow it. Public Responses conversion remains provider-neutral.
+
+Provider admission separates the generation controller, one logical execution,
+and each physical attempt. Rate/concurrency admission and coordinated recovery
+are shared within that generation. Opening, corrections, replay, continuation,
+and repair consume one logical attempt budget; SDK retries do not add a hidden
+second budget. [ProviderAttemptScope](src/free_claude_code/providers/http.py)
+retains the physical stream/resource and releases its attempt exactly once.
+Already-accepted stream recovery stays request-local.
+
+[Discovery](src/free_claude_code/providers/runtime/discovery.py) is provider-owned;
+it is not assumed to be an OpenAI `/models` request. The runtime manager owns the
+application-lifetime catalog of
+[ProviderModelInfo](src/free_claude_code/application/model_metadata.py) values.
+Startup warms referenced routing providers, then discovery fills the remaining
+configured catalog in the background. Hot replacement retains useful cached
+metadata. Catalog membership is not a prerequisite for upstream execution.
+
+[runtime/codex_catalog.py](src/free_claude_code/runtime/codex_catalog.py) projects
+the neutral inventory through the Codex launcher adapter and atomically publishes
+the managed model-catalog file. Publication failures are nonfatal; the launcher
+also synchronizes at launch. Client-side catalog caching remains client-owned.
+
+## Runtime And Resource Lifecycle
+
+[cli.commands.ServerSupervisor](src/free_claude_code/cli/commands.py) owns the
+server run/restart loop.
+[runtime/bootstrap.py](src/free_claude_code/runtime/bootstrap.py) constructs the
+provider manager, connected-account auth, Chat service/store, optional
+transcriber, `ApplicationRuntime`, `ApiServices`, and ASGI application.
+[runtime/asgi.py](src/free_claude_code/runtime/asgi.py) drives runtime startup and
+shutdown through lifespan events.
+
+[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py)
+alone publishes, retires, and closes provider generations. Each inference request
+holds a settings/provider snapshot through a lease. Provider-only Admin Apply
+prepares a candidate, commits configuration, then publishes it for new requests.
+Existing requests finish on the retired generation, which closes after its last
+lease. Failed cleanup remains owned and retryable.
+
+[Request correlation](src/free_claude_code/api/request_ids.py) covers the full
+wire send. [Inference lifetime middleware](src/free_claude_code/api/request_lifetime.py)
+owns disconnect reception and cancels unfinished inference even before the first
+frame or during a silent stream. Response finalization closes the entire body
+chain before releasing its generation on success, failure, cancellation or send
+failure. Middleware does not use `BaseHTTPMiddleware` to proxy stream bodies.
+
+[ApplicationRuntime](src/free_claude_code/runtime/application.py) shuts down
+messaging ingress/work/delivery, Chat work/storage, transcription, providers,
+then connected-account resources. Each dependency gate must close before the
+next one is released. Failed cleanup retains the ownership graph; ASGI reports
+incomplete shutdown, and the supervisor does not start an overlapping replacement.
+The supervisor owns force-termination deadlines, not arbitrary inner cleanup
+timeouts.
+
+[cli/desktop.py](src/free_claude_code/cli/desktop.py) wraps the same supervisor.
+A process lock admits one desktop host, the native tray stays on the main thread,
+and a worker runs the server. Tray restart/quit use the shared lifecycle.
+Installation and uninstallation own only their documented managed artifacts;
+client executables and native client state have separate owners.
+
+Lifecycle behavior is covered by
+[runtime tests](tests/runtime/test_application_runtime.py),
+[provider-manager tests](tests/runtime/test_provider_manager.py), and
+[response-stream tests](tests/api/test_response_streams.py).
+
+## Configuration, Admin Apply, And Authentication
+
+| Owner | Contract |
| --- | --- |
-| `torch`, `transformers`, `librosa` | `messaging.transcription` |
-| `riva.client` | `providers.nvidia_nim.voice` |
-
-They must be imported below a function boundary so importing the application or
-server does not require an optional extra. Static AST enforcement cannot observe
-dynamic imports. Deliberate provider factory loading is instead protected by the
-provider catalog, supported-ID, and factory synchronization contract.
-
-[core/version.py](src/free_claude_code/core/version.py) is the sole runtime owner
-of the FCC release version. It reads installed distribution metadata for
-FastAPI/OpenAPI, FCC-owned CLI `--version` output, and the outbound web-tools
-user agent. A source-only checkout without installed metadata reports the
-explicit `0+unknown` fallback; runtime code never parses `pyproject.toml` or
-duplicates a release literal. Client launcher arguments remain transparent to
-their wrapped clients except for FCC-owned ephemeral provider configuration.
-
-The main ownership rule is that Anthropic and Responses protocol schemas and
-shared protocol behavior belong in [src/free_claude_code/core/](src/free_claude_code/core/), while request routing and
-provider execution belong in [src/free_claude_code/application/](src/free_claude_code/application/). Routes use core schemas
-directly for wire validation and call application use cases. Provider modules use
-the same concrete request types and neutral helpers instead of importing the API
-adapter or another provider.
-Protocol consumers use the public `core.anthropic` and
-`core.openai_responses` facades. Low-level Anthropic core and provider modules
-may import the dependency-leaf Anthropic `models.py` module directly so their
-type dependency is explicit; Responses consumers outside its owner remain
-facade-only. Package initialization and those leaves must remain import-order safe.
-The model-list schema stays beside its API-owned construction policy in
-`api/model_catalog.py`; there is no generic API model package.
-
-Type annotations follow the same ownership boundaries. Known values use the
-domain types owned by their package, and JSON wire values use `JsonValue` or
-`JsonObject` from `core.json_types`. `object` is reserved for genuinely opaque
-integration boundaries and is narrowed before use. Explicit `typing.Any` is
-avoided because it disables checking, but this remains a semantic design-review
-rule rather than a mechanical text ban in CI.
-
-## Customer-Facing Contract
-
-FCC optimizes for installed user workflows, not internal compatibility. The
-behavior that must be preserved is that these user-facing surfaces run correctly
-for real prompts against supported providers:
-
-- `fcc-server`, the Windows/macOS FCC Desktop shell, and the local Admin UI for
- configuring supported providers, model routing, auth, server tools, messaging,
- and diagnostics.
-- `fcc-claude`, Claude Code, and the Anthropic-compatible proxy behavior Claude
- Code relies on, including streaming text, native/interleaved thinking, tool
- use/results, model discovery, token counting, retries/recovery, and supported
- local server-tool behavior.
-- `fcc-codex`, Codex CLI/extensions, and the streaming OpenAI Responses behavior
- Codex relies on, including native/interleaved reasoning, function and custom
- tool calls, generated `/model` catalog support, Responses stream lifecycle
- events, and Responses-to-Anthropic conversion at the adapter boundary.
-- `fcc-pi`, Pi, and the Anthropic-compatible proxy behavior Pi relies on,
- including an FCC-scoped model catalog, streaming text and reasoning, and tool
- use/results.
-- `fcc-opencode`, stable OpenCode V1, and the OpenAI Responses behavior it
- relies on, including an FCC-scoped model catalog and process-local provider
- configuration.
-- `fcc-cline`, stable Cline CLI, and the OpenAI Responses behavior it relies
- on, including an FCC-scoped model catalog, attached local sessions, and
- process-local provider configuration.
-- `fcc-hermes`, Hermes Agent 0.20.4 or newer, and the OpenAI Responses behavior
- it relies on for attached terminal sessions, including an FCC-scoped model
- catalog and process-local managed configuration.
-- `fcc-dsh`, DeepSeek Harness 0.1.0-rc.8, and the OpenAI Responses behavior it
- relies on for attached Web and headless sessions, including an FCC-scoped
- model catalog and process-local configuration.
-- `fcc-grok`, Grok Build 1.0.5 or newer, and the OpenAI Responses behavior it
- relies on for attached terminal, headless, and ACP sessions, including an
- FCC-scoped model catalog and process-local configuration.
-- `fcc-muse`, Muse Code 0.2.1 or newer, and the OpenAI Responses behavior it
- relies on for attached TUI, exec, and resume sessions, including an
- FCC-scoped model catalog and process-local routing.
-- Configured Discord and Telegram messaging bridges, including command handling,
- reply-based conversation branches, status updates, transcript rendering,
- managed Claude/Codex task execution where configured, task stop/clear flows,
- persistence, and optional voice-note transcription.
-- Installation, update, and uninstall scripts insofar as they make the
- above workflows available on a user's machine.
-
-Internal modules, class designs, helper APIs, route implementations, and tests
-are not stable contracts. Refactors may replace or remove them when doing so
-simplifies the system, improves correctness, or better matches these
-architecture boundaries. When tests primarily encode an obsolete internal shape,
-update the tests to assert the customer-facing behavior instead. Features,
-compatibility shims, endpoints, or helper paths that do not serve one of the
-surfaces above are not product requirements and should be removed rather than
-preserved.
-
-The supported messaging extension surface consists of transport ingress values,
-platform ports, and managed-session protocols. Tree aggregates, processors,
-repositories, transition values, and package-level re-exports of those
-implementation types are internal; they are not a versioned Python SDK surface.
-
-## Design Pressure And Refactor Targets
-
-The current package boundaries are intentional, but several modules still carry
-large orchestration responsibilities. Treat these as refactor targets, not as
-new places to add unrelated behavior:
-
-- [api/handlers/](src/free_claude_code/api/handlers/) owns customer-facing API product flows:
- Claude Messages, OpenAI Responses, and token counting. Keep route handlers
- thin, keep Claude-only behavior in the Messages handler, and use
- [application/execution.py](src/free_claude_code/application/execution.py) only for shared
- provider resolution, preflight, tracing, token counting, and streaming.
-- [providers/openai_chat/](src/free_claude_code/providers/openai_chat/) owns the common upstream provider
- behavior. It separates immutable vendor profiles from per-request stream
- execution, recovery, request policy, and tool-call assembly. Within one
- request, the runner owns logical orchestration, a replaceable stream assembler
- owns one replay epoch's ledger and parser state, the shared
- `ProviderAttemptScope` owns each returned physical stream and attempt, and
- `RecoveryController` alone owns downstream commit policy. Shared protocol
- rules belong in [src/free_claude_code/core/](src/free_claude_code/core/).
-- [messaging/workflow.py](src/free_claude_code/messaging/workflow.py) coordinates messaging runtime
- dependencies. Inbound turn intake, queued node execution, slash command
- dependencies, and tree queue internals live in separate modules so new
- behavior has one owner instead of growing the workflow object.
-- [config/admin/](src/free_claude_code/config/admin/) owns Admin UI config behavior. Keep
- provider fields catalog-driven, and keep manifest, source loading, validation,
- env rendering, value presentation, and status metadata in their package owners.
-
-## Runtime Startup And Lifecycle
-
-Console scripts are registered in [pyproject.toml](pyproject.toml):
-
-- `fcc-server` calls `free_claude_code.cli.entrypoints:serve`.
-- `fcc-desktop` is a GUI script calling
- `free_claude_code.cli.desktop_entrypoint:launch` on Windows and macOS.
-- `fcc-claude` calls `free_claude_code.cli.launchers.claude:launch`.
-- `fcc-codex` calls `free_claude_code.cli.launchers.codex:launch`.
-- `fcc-pi` calls `free_claude_code.cli.launchers.pi:launch`.
-- `fcc-opencode` calls `free_claude_code.cli.launchers.opencode:launch`.
-- `fcc-cline` calls `free_claude_code.cli.launchers.cline:launch`.
-- `fcc-hermes` calls `free_claude_code.cli.launchers.hermes:launch`.
-- `fcc-dsh` calls `free_claude_code.cli.launchers.dsh:launch`.
-- `fcc-grok` calls `free_claude_code.cli.launchers.grok:launch`.
-- `fcc-muse` calls `free_claude_code.cli.launchers.muse:launch`.
-
-[scripts/install.sh](scripts/install.sh) and [scripts/install.ps1](scripts/install.ps1)
-install or update the uv tool plus optional voice extras. On Windows the
-installer owns the FCC desktop and Start-menu shortcuts; on macOS it owns the
-per-user application bundle and desktop link. [scripts/uninstall.sh](scripts/uninstall.sh)
-and [scripts/uninstall.ps1](scripts/uninstall.ps1) remove those exact desktop
-artifacts, the FCC uv tool, and the managed `~/.fcc/` tree from
-[config/paths.py](src/free_claude_code/config/paths.py); they do not remove
-uv, Claude Code, Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, Grok
-Build, Muse Code, or uv-managed Python runtimes. On native Windows,
-[scripts/install-muse.ps1](scripts/install-muse.ps1) owns only FCC's fixed Muse
-executable, ownership record, and exact user-PATH entry; its independent
-[scripts/uninstall-muse.ps1](scripts/uninstall-muse.ps1) removes only those
-managed assets and is never called by FCC's general uninstaller.
-[scripts/ci.sh](scripts/ci.sh) and
-[scripts/ci.ps1](scripts/ci.ps1) mirror [.github/workflows/tests.yml](.github/workflows/tests.yml)
-for local pre-push verification.
-
-[cli/entrypoints.py](src/free_claude_code/cli/entrypoints.py) starts the FastAPI server with Uvicorn.
-The shared `ServerSupervisor` migrates legacy env files when needed, loads cached
-settings, runs one server instance, and can restart it after Admin config changes.
-An Admin restart constructs the next instance only when the prior
-`ApplicationRuntime` reports that its complete ownership graph closed. An
-incomplete ASGI shutdown therefore exits the supervisor instead of overlapping
-old and replacement graphs. On final shutdown it best-effort kills registered
-child processes.
-
-[cli/desktop.py](src/free_claude_code/cli/desktop.py) owns the platform-neutral
-desktop lifecycle. An operating-system file lock admits one desktop host, the
-tray remains on the process main thread for native event-loop compatibility, and
-one worker runs the same in-process `ServerSupervisor` with console output and
-automatic browser launch disabled. A second desktop launch waits for health,
-opens the existing Admin page, and exits. Tray restart delegates to the canonical
-supervisor; tray quit requests the same graceful ASGI and application-runtime
-shutdown as `fcc-server`. [cli/desktop_tray.py](src/free_claude_code/cli/desktop_tray.py)
-owns only native status-area presentation and callbacks.
-
-[runtime/bootstrap.py](src/free_claude_code/runtime/bootstrap.py) is the single production composition function. The CLI
-supervisor supplies one settings snapshot and its restart callback; bootstrap
-configures logging, constructs the runtime owners and the configured voice
- transcriber, constructs the explicit `ApiServices` composition value, and
- returns the ASGI application. Provider request leases and task control satisfy
- the consumer-owned ports in [application/ports.py](src/free_claude_code/application/ports.py); Admin operations retain
- their inbound-adapter port in [api/ports.py](src/free_claude_code/api/ports.py).
-
-[api/app.py](src/free_claude_code/api/app.py) registers routers and exception
-handlers around an explicit `ApiServices` value, then composes pure ASGI
-correlation and inference-lifetime boundaries. Correlation surrounds the
-complete wire send. The inner lifetime boundary owns `http.disconnect` for
-Messages and Responses, cancelling the request application whether abandonment
-occurs during request processing, first-frame prefetch, non-streaming
-aggregation, or a silent committed stream. Neither boundary proxies streaming
-responses through `BaseHTTPMiddleware`. The API does not read global settings or
-construct runtime resources.
-`app.state.services` is the only runtime state published to FastAPI.
-
-[runtime/application.py](src/free_claude_code/runtime/application.py) owns process startup and shutdown, optional messaging,
-the selected transcriber, the managed CLI session manager, Admin pending state,
-connected-account use cases, and the injected restart callback. Shutdown is
-serialized and ordered: quiesce
-messaging ingress, cancel and drain workflow/CLI work, flush persistence, close
-delivery, close transcription, close providers, then close connected-account
-login and HTTP resources. An owner reference is
-released only after its cleanup succeeds; cancellation or failure leaves the
-incomplete graph retryable. Teardown stops at a failed dependency gate rather
-than closing resources that still-live upstream work may need, and the ASGI
-adapter reports that incomplete graph as lifespan shutdown failure. Cleanup is
-completion-driven: generic timeouts do not cancel half-closed external resources;
-the process supervisor owns any force-termination deadline. Optional messaging
-startup remains nonfatal only when every partially constructed messaging owner
-was successfully cleaned; incomplete startup cleanup fails the application
-startup and retains the graph for the next close attempt.
-[runtime/asgi.py](src/free_claude_code/runtime/asgi.py) drives that owner from ASGI lifespan messages and preserves
-the concise startup-failure contract.
-
-[runtime/provider_manager.py](src/free_claude_code/runtime/provider_manager.py) is the only owner that constructs, publishes,
-retires, and closes provider generations. Each request acquires a generation
-lease before routing. Non-streaming responses release it after aggregation;
-streaming responses bind it to FCC's response owner, which first closes the
-entire body chain and then releases the lease on completion, failure,
-cancellation, disconnect, or a response-start send failure. A provider-only
-Admin Apply prepares a candidate and commits configuration before publication.
-New requests then use the candidate while old streams finish on the retired
-generation; its last lease closes it exactly once. Final shutdown rejects new
-acquisition and replacement, waits every lease, and awaits the same
-manager-owned cleanup task even if the initiating request or lease release is
-cancelled. Failed generation or unpublished-candidate cleanup remains owned and
-retryable; the manager does not become terminal or clear its model catalog until
-every owned runtime closes.
-
-The manager also owns one application-lifetime provider model catalog and its
-single best-effort discovery task. The catalog survives provider replacement.
-Settings-configured providers and currently connected accounts contribute to
-the same availability set. Account connect/disconnect performs a targeted model
-refresh or eviction; it does not mutate settings or replace a provider
-generation.
-Runtime integrations may observe those lifecycle events through one neutral
-catalog publisher supplied by the composition root. Publication is fail-open
-and occurs only after settings or cache changes; provider adapters remain the
-sole owners of upstream discovery. Claude and Codex clients may independently
-retain the model list they loaded at startup.
-
-## Configuration Model
-
-[config/settings.py](src/free_claude_code/config/settings.py) is a pure Pydantic
-schema. It owns field types, canonical defaults, normalization, and cross-field
-validation, but it never reads process state or files. Required strings are
-always non-empty. Optional strings have exactly one absent state, `None`; blank
-input is normalized to that state before validation.
-
-[config/loader.py](src/free_claude_code/config/loader.py) owns external source
-composition and provenance. The live precedence is Settings defaults, then the
-managed `~/.fcc/.env`, then process environment. The one intentional exception
-is `ANTHROPIC_AUTH_TOKEN`: a non-empty managed value wins over an inherited stale
-process token so FCC-launched clients and the server cannot disagree. Every
-entrypoint uses this loader, and cached settings are invalidated only through
-its public cache accessor.
-
-[config/env_migrations.py](src/free_claude_code/config/env_migrations.py) owns a
-locked, atomic schema-1 consolidation before the first load. When the managed
-file is not yet schema 1, migration selects one base source: existing managed
-state, otherwise a legacy home file, otherwise a verified FCC source-checkout
-file. A legacy `FCC_ENV_FILE` may overlay that base once. Recognized effective
-values are written to the managed file; imported files remain untouched. Once
-the managed schema marker exists, checkout files and `FCC_ENV_FILE` are inert
-and are not live configuration sources.
-
-[config/paths.py](src/free_claude_code/config/paths.py) defines the managed
-config, lock, model catalog, messaging workspace, and log locations under
-`~/.fcc`. Arbitrary current-working-directory `.env` files are never read.
-
-Proxy authentication has two independent settings:
-
-- `PROXY_AUTH_ENABLED` controls whether FCC validates incoming bearer tokens;
-- `ANTHROPIC_AUTH_TOKEN` is a retained, non-empty client credential, exposed
- internally as `proxy_auth_token`.
-
-Disabling authentication does not erase or replace the token. Claude, Codex,
-Pi, managed messaging, and local model-catalog calls all receive the retained
-token. The API boundary checks the boolean first and uses constant-time token
-comparison only when enforcement is enabled.
-
-Model routing remains tiered: `MODEL` is the fallback route;
-`MODEL_FABLE`, `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` are optional
-overrides. [config/model_refs.py](src/free_claude_code/config/model_refs.py) owns
-model-ref parsing, while [config/reasoning.py](src/free_claude_code/config/reasoning.py)
-owns the typed reasoning vocabulary.
-
-[config/admin/](src/free_claude_code/config/admin/) owns the Admin manifest,
-presentation, validation, and sparse managed-file persistence. Settings
-metadata supplies runtime defaults; provider and smoke fields are generated
-from [config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py).
-Admin requests are partial updates: omitted keys stay unchanged, `null` removes
-an optional assignment, and required/defaulted values reject `null` or blank
-input. False and zero remain real values. Masked or blank secret submissions
-mean unchanged; an explicit remove action is available only for optional
-secrets. Apply validates the prospective Settings snapshot before atomically
-writing only configured values plus preserved unknown managed assignments.
-Process-owned fields are visible but locked.
-
-[config/admin/status.py](src/free_claude_code/config/admin/status.py) owns
-provider configuration readiness and exposes ordered Admin field keys for each
-catalog descriptor. The browser uses those keys to navigate directly from a
-provider card to its first missing field; it never parses presentation text.
-Explicit remote model-list checks and local reachability probes are separate,
-ephemeral results. They render in their own live region and never overwrite the
-stable `Configured`/`Missing` badge or configuration description. Runtime and
-API owners return stable guidance for failed checks and keep all exception text
-out of the browser response; server logs record only safe failure metadata.
-
-The provider composition root narrows optional Settings into provider-ready
-state. Static-key providers receive a non-empty key, Vertex receives renewable
-ADC with `api_key=None`, and optional proxies remain `None` until configured.
-Resolved [ProviderConfig](src/free_claude_code/providers/base.py) has no second
-set of Settings defaults.
-
-[.env.example](.env.example) is documentation only. It is neither packaged nor
-read at runtime. Admin routes call `require_loopback_admin()`, which rejects
-non-loopback clients and non-local origins.
-
-## HTTP Request Flow
-
-[api/routes.py](src/free_claude_code/api/routes.py) exposes the public proxy routes:
-
-- `POST /v1/messages`: Anthropic Messages-compatible streaming requests.
-- `POST /v1/responses`: OpenAI Responses-compatible requests.
-- `POST /v1/messages/count_tokens`: Anthropic token counting.
-- `GET /v1/models`: gateway and Claude-compatible model listing.
-- `GET /muse-code/models`: authenticated Muse compatibility alias for the
- direct Responses model view.
-- `GET /health`: health check.
-- `POST /stop`: stop CLI sessions and pending tasks.
-- `HEAD` and `OPTIONS` probes for compatibility on supported endpoints.
-
-Admin routes live beside these in [api/admin_routes.py](src/free_claude_code/api/admin_routes.py).
-
-Authentication is handled by `require_proxy_auth()` in
-[api/dependencies.py](src/free_claude_code/api/dependencies.py). If `ANTHROPIC_AUTH_TOKEN` is blank,
-proxy auth is disabled. Otherwise FCC accepts exactly `Authorization: Bearer
-<token>`. Other credential headers are ignored, so a stale provider API key
-cannot mask valid proxy authorization. The complete bearer token is compared
-in constant time; no model suffix or other token mutation is accepted.
-
-HTTP request correlation is owned at ingress. A pure ASGI boundary creates one
-opaque FCC request ID before routing, places it in log context and request state,
-and adds `request-id` while forwarding the actual `http.response.start` message.
-OpenAI-compatible Responses and the shared model catalog also expose the same
-value as `x-request-id`. Provider execution and trace events receive that
-existing ID; they do not create a second identifier. Keeping the context around
-the complete inner ASGI call preserves correlation during streaming and leaves
-response lifetime finalization under the concrete response owner. Starlette's
-outer server-error boundary bypasses user middleware for its catch-all 500, so
-that one handler explicitly attaches the same ingress-owned headers.
-
-Inference client lifetime is also owned at the HTTP boundary. One bounded
-receive pump is the sole reader of the server's ASGI `receive` channel while the
-application consumes the relayed request body. The complete application task is
-raced against `http.disconnect`; application completion wins a simultaneous
-race, while disconnect cancels and drains unfinished work. Existing route,
-response-body, provider-stream, and request-generation owners then perform their
-normal cancellation cleanup. FCC sends no synthetic timeout or terminal event
-to a client that has already left. Non-inference routes bypass this machinery.
-
-[api/handlers/](src/free_claude_code/api/handlers/) owns the public API product flows.
-`MessagesHandler` validates non-empty messages, resolves models, applies
-Claude-only safety-classifier and local optimization policy, handles local web
-server tools, then streams Anthropic SSE. `ResponsesHandler` owns streaming-only
-OpenAI Responses validation for Codex clients and passes the concrete Responses
-request into the shared executor. `TokenCountHandler` owns Anthropic token
-counting. Shared provider execution lives in
-[application/execution.py](src/free_claude_code/application/execution.py). `ProviderExecutor` resolves the narrow
-consumer-owned `ProviderPort`, synchronously preflights the concrete ingress
-protocol, emits trace events, counts input tokens, and returns an SSE iterator
-in that same public protocol. It also owns application-level model fallback
-after provider-owned retries are exhausted; providers do not select alternate
-models.
-It receives only a provider resolver and the few scalar collaborators it needs;
-it does not depend on FastAPI, provider implementations, or the full settings
-object. The executor also owns FCC's provider-progress deadline: every wait for
-the next non-empty provider chunk is limited by the Settings-owned
-`PROVIDER_PROGRESS_TIMEOUT`, which defaults to 600 seconds and is projected into
-the executor as a validated scalar. Admission, retries, backoff, recovery, and
-any pre-output fallback transitions all consume that same wait; switching
-candidates never resets it. A non-empty emitted chunk renews the next window,
-while empty keepalives do not. The timeout context ends before the
-executor yields, so downstream response backpressure is not mistaken for
-stalled provider work and cannot receive cancellation from the generator's
-timer. Expiry becomes a protocol-neutral, non-retryable 504 `ExecutionFailure`;
-cancellation and provider-originated timeouts retain their existing meanings.
-This progress deadline is independent of provider `HTTP_READ_TIMEOUT` and of any
-client-owned deadline: provider HTTP adapters own read failures, the application
-owns visible-progress failure, and the API boundary owns actual client
-abandonment.
-
-[core/token_estimation.py](src/free_claude_code/core/token_estimation.py) owns
-process-wide best-effort plain-text token estimation. It acquires the shared
-encoder once and degrades to a deterministic character estimate when encoder
-data is unavailable, so a cold cache or blocked network cannot prevent FCC from
-starting. Anthropic request counting and the Anthropic/Responses stream ledgers
-retain ownership of their protocol-specific block and structural overhead.
-
-[api/response_streams.py](src/free_claude_code/api/response_streams.py) owns public streaming egress
-commit timing. It waits for the first protocol chunk before returning a
-successful FCC-owned `StreamingResponse`. Its explicit replay iterator owns the
-prefetched stream even before replay begins. The response itself owns one
-idempotent finalization task: close the body transitively, then release the
-provider-generation lease. This finalizer surrounds the real ASGI send and runs
-to completion even when sending headers or the first body frame fails. A provider
-execution failure before that commit boundary remains a real typed non-2xx JSON
-response. Once FCC has finalized the failure, the response includes
-`x-should-retry: false` so FCC retains ownership of upstream retry/recovery
-without causing a second client retry loop. After the first chunk has escaped,
-HTTP status is committed; Messages emits an Anthropic `event: error` and closes
-without a synthetic `message_stop`; Responses emits `response.failed` with the
-original response ID. Messages are non-streaming unless the client explicitly
-sets `stream: true`. Non-streaming Messages aggregate internally and return
-non-2xx JSON for any terminal stream error, discarding incomplete content rather
-than presenting a partial success.
-
-The public response chain follows a transitive close-ownership rule. A response
-owns its prefetched replay iterator; replay owns the traced executor body;
-tracing owns the provider-execution iterator; and the provider runner owns its
-upstream stream. Provider-owned conversion and presentation iterators stay
-inside their concrete transport chain and close their direct inputs. Each
-response-chain owner closes its direct input on normal completion, failure,
-cancellation, and early consumer close. Failures from those explicit cleanup
-calls are trace metadata and cannot replace an established wire outcome; a
-generation lease is released only after the body chain has finished closing.
-
-Ingress authentication, request validation, model routing, and deterministic
-preflight failures remain ordinary HTTP errors and do not receive the terminal
-provider-execution retry header. Missing provider configuration and a shutting
-down request runtime are application-readiness errors: Messages serializes them
-as Anthropic JSON, Responses serializes them as OpenAI JSON, and neither is
-misclassified as an already-finalized provider execution failure.
-
-```mermaid
-sequenceDiagram
- participant Client
- participant Route as FastAPIRoute
- participant Handler as ProductHandler
- participant Router as ModelRouter
- participant Exec as ProviderExecutor
- participant Manager as ProviderRuntimeManager
- participant Lease as ProviderGenerationLease
- participant Runtime as ProviderRuntimeGeneration
- participant Provider
-
- Client->>Route: POST /v1/messages
- Route->>Route: require_proxy_auth
- Route->>Manager: acquire current generation
- Manager-->>Route: Lease(settings, provider resolver)
- Route->>Handler: create message
- Handler->>Router: resolve model and reasoning intent
- Handler->>Handler: server tools or optimizations
- Handler->>Exec: stream routed request
- Exec->>Lease: resolve provider
- Lease->>Runtime: cached or new provider
- Runtime->>Provider: cached or new provider
- Exec->>Provider: preflight_messages
- Exec->>Provider: stream_messages
- Provider-->>Client: Anthropic SSE events
- Route->>Lease: release after complete body
-```
-
-OpenAI Responses uses the same provider execution primitive without importing
-Claude-only message intercepts. `ResponsesHandler` calls
-`ProviderExecutor.stream_responses`, and the concrete `OpenAIResponsesRequest`
-remains a Responses request across the application boundary. The selected
-provider transport then owns one explicit matrix cell: Messages-to-Chat,
-Messages-to-Responses, Responses-to-Chat, or native Responses-to-Responses.
-There is no compatibility facade and no Responses-to-Messages-to-Responses
-round trip.
-
-## Model Routing
-
-[application/routing.py](src/free_claude_code/application/routing.py) resolves incoming client model names.
-It supports two forms:
-
-- Direct provider model refs such as `nvidia_nim/nvidia/model-name`.
-- Gateway model IDs decoded by [core/gateway_model_ids.py](src/free_claude_code/core/gateway_model_ids.py).
-
-If the incoming model is not direct, `ModelRouter` maps it by Claude tier. Names
-containing `fable`, `opus`, `sonnet`, or `haiku` use the matching tier override
-when set, otherwise they use the Default Model in `MODEL`.
-
-The router also selects the applicable reasoning preference. Direct provider
-refs use the root policy; Claude tier routes use a non-inherited tier override
-or the root fallback; the no-thinking gateway variant forces `off`.
-[application/reasoning.py](src/free_claude_code/application/reasoning.py) then
-combines that preference with the concrete client request exactly once. The
-resulting `ReasoningPolicy` preserves independent control, named effort, and an
-exact client token budget without guessing provider behavior.
-`ResolvedModelRoute` owns the public model, one canonical primary
-`ProviderModelTarget`, the ordered canonical targets from `MODEL_FALLBACKS`, and
-the reasoning preference. It omits only a fallback exactly equal to the resolved
-primary; another model on the same provider remains valid.
-`RoutedMessagesRequest` owns the final request-scoped policy passed to execution.
-
-Routing keeps model identity split at the application boundary. The routed
-request carries the provider model sent upstream, while
-`ResolvedModelRoute.original_model` remains the stable gateway model exposed in
-Anthropic responses and traces. `ProviderExecutor` passes both identities
-explicitly; providers, local optimizations, and local server tools must never
-publish the private upstream model as the response model.
-
-Fallback execution is a bounded first-frame state machine in
-[application/execution.py](src/free_claude_code/application/execution.py). The
-executor opens the primary first and resolves each later provider lazily. It
-advances when the current provider has finalized any `ExecutionFailure` before
-emitting a non-empty protocol chunk and another configured target exists.
-`retryable` remains provider-local recovery metadata; it does not control the
-application's forward transition to a different target. The executor closes the
-abandoned iterator before resolving the next provider and deep-copies the
-original routed request for every candidate, changing only the upstream model.
-Deterministic preflight or validation failures, unexpected exceptions, the
-application-owned progress deadline, cancellation, disconnect, and empty
-completion remain terminal. Once any protocol frame is emitted, the candidate
-is committed and existing terminal-error behavior is authoritative; this
-prevents duplicate lifecycles and output. Final exhaustion re-raises the last
-exact failure.
-
-Every candidate keeps the original request ID, public response model, input
-token count, reasoning policy, messages, system prompt, tools, and generation
-metadata. One request-generation lease therefore snapshots both the primary and
-fallback list: Admin hot apply affects only requests that acquire the next
-generation. Safe `model_fallback.started` and `model_fallback.selected` trace
-events expose canonical route refs, candidate positions, failure kind, status,
-wire API, and generation without prompt or raw upstream error content.
-
-`GET /v1/models` owns one neutral inventory with three typed views:
-
-- the default `claude` view preserves configured and cached provider models,
- no-thinking variants, and built-in Claude compatibility IDs;
-- the `messages` view exposes one direct routable ID per model for
- Messages-native clients; and
-- the `responses` view exposes those direct IDs plus Responses transport,
- retry, reasoning, and timeout metadata for Responses-native clients.
-
-Provider model discovery and optional thinking metadata live in the
-application-level catalog owned by `ProviderRuntimeManager`.
-[providers/runtime/discovery.py](src/free_claude_code/providers/runtime/discovery.py)
-is the sole owner of provider model-list queries and cache population. Startup
-synchronously warms the providers referenced by primary and fallback routing
-before clients can perform their one-time model fetch, then a background pass fills the remaining
-configured provider catalogs without querying successful warm-ups again.
-Discovery is an adapter operation, not an assumption that every upstream has an
-OpenAI `/models` route. For example, Vertex translates that operation to
-Google's paginated `publishers/google/models` API and converts publisher resource
-names into the exact model IDs accepted by its OpenAI-compatible endpoint.
-Catalog contents are discovery metadata, not execution validation; the provider
-request remains authoritative when an upstream accepts a model absent from its
-list or rejects a listed model.
-`ProviderModelInfo.supports_thinking` alone owns discovered per-model thinking
-support for model-list presentation; it does not select request behavior.
-Provider adapters must never branch on upstream model names or versions to
-translate reasoning. The catalog is not part of an individual provider
-generation, so a hot replacement does not erase the last useful model list.
-Discovery failures retain prior entries.
-
-Codex-specific model picker shaping stays outside the neutral inventory.
-[runtime/codex_catalog.py](src/free_claude_code/runtime/codex_catalog.py) is the
-composition bridge: it asks this route's pure builder for the exact application
-inventory, passes that response to the existing Codex adapter, and writes
-`~/.fcc/codex-model-catalog.json` without making a loopback HTTP request.
-`ProviderRuntimeManager` invokes the bridge after authoritative settings,
-discovery, provider-test, or connected-account changes. Startup creates a
-missing file after routed-provider warming but preserves an existing
-last-known-good catalog until the background discovery pass publishes the
-complete accumulated inventory. Writes are atomic and identical bytes are not
-rewritten. Projection or filesystem failures emit only a concise warning and do
-not fail server startup, Admin operations, discovery, or inference. Shutdown
-never publishes the cleared in-memory cache.
-
-The Codex App reads `model_catalog_json` at startup, so it must restart to see a
-later catalog publication. `fcc-codex` remains an additional launch-time
-synchronizer: it fetches the same `/v1/models` response, uses the same adapter
-and writer, and passes the path as an ephemeral override. Codex users open the
-native picker with `/model`; FCC does not implement a proxy-level `/models`
-alias.
-
-## Provider Architecture
-
-Provider metadata is neutral and centralized in
-[config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py). Each
-`ProviderDescriptor` declares provider ID, display name, authentication kind, locality, credential env
-var, default base URL, settings attribute names, configuration readiness, and
-proxy support. Readiness may require multiple ordinary settings or a non-secret
-project ID; it is not inferred exclusively from API-key presence. The catalog
-does not select a concrete adapter.
-
-[providers/runtime/](src/free_claude_code/providers/runtime/) owns construction details for one
-closable provider generation: construction policy, resolved provider
-configuration, lazy provider instances, provider-owned admission controllers, and
-cleanup. [providers/runtime/factory.py](src/free_claude_code/providers/runtime/factory.py)
-constructs ordinary provider IDs from `OPENAI_CHAT_PROFILES`, keeps a sparse
-factory mapping for adapters with real state or algorithms, and accepts explicit
-composition-root factories for providers with process-lifetime dependencies.
-The union of those construction owners must exactly equal the neutral provider
-catalog.
-`ProviderRuntime` directly guarantees one provider and admission controller per
-provider ID within a generation; there is no pass-through cache object, process
-singleton, or second admission registry.
-
-[providers/admission.py](src/free_claude_code/providers/admission.py) owns the
-complete shared upstream-admission lifecycle for that provider generation. Its
-three scopes are explicit:
-
-- `ProviderAdmissionController` owns the provider-generation sliding window,
- concurrency bulkhead, recovery episode, backoff, and probe election;
-- `ProviderExecution` owns one logical provider operation, its correlation ID,
- single five-attempt budget, active-attempt identity, last raw failure, and
- terminal state;
-- `ProviderAttempt` owns one physical provider HTTP/generation call, including
- its opaque execution claim, admission permit, concurrency lease, acceptance
- state, one idempotent outcome, and exact-once close.
-
-[providers/http.py](src/free_claude_code/providers/http.py) composes one
-`ProviderAttempt` with at most one retained transport resource through the
-idempotent `ProviderAttemptScope`. Resource cleanup is diagnostic-only: a close
-failure emits redacted type metadata but cannot replace established success,
-retry, terminal failure, or cancellation. Attempt cleanup remains authoritative
-and always runs in the scope's `finally`, releasing the execution claim and
-concurrency lease even when transport cleanup fails.
-
-Only `ProviderExecution.open_attempt()` can enter physical provider I/O. A
-strict sliding window admits the call before the concurrency bulkhead; the
-bulkhead is held only while that call or stream is active, never during retry
-backoff. Every physical call emits one metadata-only
-`provider.attempt.started`/`provider.attempt.resolved` pair with execution ID,
-operation kind, and attempt ordinal. Prompts, credentials, bodies, and raw
-errors are not part of those events.
-
-The first retryable failure before upstream acceptance opens one recovery
-episode and elects that logical execution as leader. The leader alone waits and
-sends half-open probes. Concurrent failures coalesce into the same episode,
-later callers wait, and already active streams continue. A stale in-flight
-success or failure cannot close or extend the episode, while leader cancellation
-transfers ownership to a waiter.
-
-A successful probe closes the episode and releases waiters through ordinary
-rate and concurrency admission. A non-retryable probe response also closes it
-because the provider has responded; only that request receives the rejection.
-If the leader exhausts its attempt budget, that terminal outcome stays attached
-to every coalesced logical execution, even if a later recovery generation starts.
-New work fails fast during the provider-directed cooldown; once it expires,
-exactly one new caller becomes the next probe. There is no background retry
-worker, copied request queue, or second scheduling system.
-
-The one-call helper on `ProviderExecution` accepts only a callback that performs
-one quota-bearing provider call. Higher-level orchestration remains with its
-protocol owner: every model-catalog page receives a separate logical execution,
-while a Codex catalog GET followed by credential refresh and another catalog GET
-uses two attempts in one execution. OAuth refresh itself remains auth-owned and
-does not hold or consume a provider-attempt lease. Discovery and generation use
-distinct operation kinds and budgets but intentionally share the same
-provider-generation health episode.
-
-Retired generations retain their own synchronization state until request leases
-drain, while new generations and separate server instances never reuse it. Hot
-replacement therefore begins with fresh quota and recovery state; an old and new
-generation enforce independent budgets while old request leases drain.
-Application-level generation publication, request leases, model metadata,
-and discovery orchestration belong to `ProviderRuntimeManager` in the runtime
-package. This separates a single generation's resources from process-lifetime
-state.
-
-[application/model_metadata.py](src/free_claude_code/application/model_metadata.py) owns the immutable
-`ProviderModelInfo` value consumed by the application catalog. Provider-specific
-model-list modules retain response parsing and construct that value directly;
-there is no provider-layer alias for the former owner.
-
-[application/ports.py](src/free_claude_code/application/ports.py) defines the
-four protocol-specific provider operations consumed by request execution:
-synchronous `preflight_messages()` and `preflight_responses()`, followed by
-lazy `stream_messages()` and `stream_responses()`. API handlers and application
-execution depend on that structural port, never on a provider base class.
-Providers implement it without registration or a compatibility layer.
-
-[providers/base.py](src/free_claude_code/providers/base.py) defines provider-internal construction and lifecycle contracts:
-
-- `ProviderConfig`: shared provider settings such as API key, base URL, rate
- limits, timeouts, proxy, and logging flags. It is a frozen internal
- value whose base URL has already been resolved from the catalog.
-- `BaseProvider`: the abstract implementation base for cleanup, explicit
- Messages and Responses preflight/stream operations, and the sole provider
- catalog operation, `list_model_infos()`. Providers return application-owned
- `ProviderModelInfo` values directly; there is no parallel IDs-only catalog
- contract.
-
-Provider execution is organized around explicit protocol owners.
-[providers/openai_chat/](src/free_claude_code/providers/openai_chat/) implements the concrete
-`OpenAIChatProvider` used by every OpenAI-compatible `/chat/completions`
-upstream. `OpenAIChatProfile` contains immutable request policy, an explicit
-reasoning encoder, an explicit history replay mode, its standard
-streamed-reasoning field, postprocessors, and base-URL normalization for
-ordinary vendors. Configuration differences therefore remain data rather than
-empty subclasses. The package also
-owns the exactly typed private per-request runner, recovery operations, tool-call
-assembly, and streamed usage handling. No obsolete generic transport namespace
-or untyped provider backchannel remains.
-
-[providers/openai_responses/](src/free_claude_code/providers/openai_responses/)
-owns standard API-key `/responses` execution. Its transport borrows the owning
-provider's configured SDK client and admission controller, builds and parses the
-public protocol through `core.openai_responses`, and owns stream attempts,
-failure classification, recovery holdback, cancellation, and exact closure. It
-owns no credentials, model discovery, provider configuration, or client
-lifecycle. This boundary is deliberately separate from the Codex subscription
-adapter's OAuth and private-backend contract.
-
-[providers/opencode/](src/free_claude_code/providers/opencode/) is specialized
-because OpenCode Zen and Go advertise heterogeneous per-model transports. Each
-provider instance owns a separately proxied, admitted rich-catalog client and
-an immutable last-good route snapshot. The model selector remains the public
-FCC ID while the catalog record's `id` is sent upstream. Exact effective package
-metadata selects standard Responses only for `@ai-sdk/openai`; every other
-accepted package uses the inherited OpenAI Chat path. Listing and direct
-generation resolve from the same status-filtered snapshot, a cold load is
-coalesced, and missing route metadata fails before generation rather than
-probing endpoints or treating HTTP 500 as transport discovery. Both branches
-share the one provider-generation admission controller.
-
-[providers/groq/](src/free_claude_code/providers/groq/) is a specialized
-`OpenAIChatProvider` because Groq exposes incompatible `reasoning_effort`
-vocabularies without publishing that capability in model metadata. The Groq
-adapter owns a generation-local vocabulary cache keyed by the exact opaque model
-ID; model names and versions are never parsed to select behavior. A narrowly
-recognized pre-stream 400 can teach the adapter the accepted known vocabulary
-and trigger one request-body correction through the shared provider attempt
-budget. Later requests apply the same pure rewrite proactively. Unknown values
-are never echoed, unrelated errors retain their normal failure path, and no
-separate retry loop or persisted capability registry exists. Groq rejects
-structured assistant reasoning fields in replayed Chat Completions history, so
-the same provider policy preserves prior reasoning as ordinary tagged assistant
-content; this replay rule is provider-wide and never selected by model name.
-
-[providers/openai_codex/](src/free_claude_code/providers/openai_codex/) owns
-ChatGPT subscription authentication and the Codex backend's OpenAI Responses
-transport. Its process-lifetime auth manager owns FCC's credential file,
-browser/device authorization, refresh, and revocation; provider generations
-borrow it and resolve fresh headers for each operation. The provider owns HTTP
-failure classification, model discovery, admission, and commit-boundary retry.
-Neutral Anthropic-to-Responses input and Responses-to-Anthropic stream
-conversion remain in
-[core/openai_responses/](src/free_claude_code/core/openai_responses/), which
-never imports OAuth, account IDs, or provider endpoints. That neutral converter
-preserves the public Responses contract; the subscription provider owns the
-private Codex request projection and omits fields that backend does not accept,
-such as the public `max_output_tokens` cap and `metadata`. Successful private
-responses can omit `Content-Type`, so the provider accepts an absent media type
-for its always-streaming request and parses the body as SSE. An explicitly
-declared non-SSE media type retains the bounded diagnostic failure path. The
-Admin API exposes only safe connected-account state and never serializes token
-objects.
-
-[providers/google_openai/](src/free_claude_code/providers/google_openai/) owns the
-Google-specific protocol behavior shared by AI Studio and Vertex AI: literal
-Google `extra_body` construction, exclusive reasoning serialization, and
-thought-signature replay. Each concrete profile selects one Google reasoning
-encoder, and that encoder is the sole writer of `reasoning_effort` or
-`extra_body.google.thinking_config` for its request. Caller-provided Google
-thinking configuration is preserved only for provider-default reasoning;
-combining it with FCC reasoning controls fails during deterministic preflight.
-Thought-signature replay is a separate component and never mutates reasoning
-controls. Neither concrete provider imports from the other. AI Studio owns its
-API-key endpoint; [providers/vertex/](src/free_claude_code/providers/vertex/)
-owns project/location endpoint composition, renewable Application Default
-Credentials, and translation of Google's native publisher-model catalog. The
-OpenAI transport receives a callable credential source, so access-token refresh
-does not require rebuilding provider generations or persisting ephemeral tokens.
-
-`OpenAIChatProvider` explicitly implements preflight by constructing the same
-upstream request body it will later stream. `BaseProvider` makes that operation
-abstract, so a new provider cannot silently omit the commit-boundary validation.
-LM Studio composes the OpenAI-chat conversion first and its context-budget probe
-second; conversion failure therefore cannot open a stream or run the probe.
-Provider classifiers and preflights report context exhaustion as the neutral
-`CONTEXT_WINDOW_EXCEEDED` execution failure. The Anthropic serializer alone adds
-Claude's `prompt is too long` compaction trigger; providers never encode a
-client-specific recovery phrase.
-
-Providers call the OpenAI request policy for Anthropic-to-OpenAI conversion,
-reasoning replay selection, `extra_body`, and chat-completion field normalization.
-The SDK-free `OpenAIToolNameCodec` in
-[core/openai_tool_names.py](src/free_claude_code/core/openai_tool_names.py) owns
-reversible translation from client tool identities to OpenAI's portable
-function-name grammar. OpenAI Chat and upstream Responses converters apply that
-codec only to their explicit declaration, forced-choice, and replay fields,
-then restore the original identity before Anthropic tool state or schema
-validation. Valid names remain unchanged, while deterministic aliases keep
-retries, replay, and append-only prompt prefixes stable. This is target-protocol
-conversion, never a provider or model capability switch.
-When an Anthropic request declares tools but omits `tool_choice`, the conversion
-boundary resolves Anthropic's implicit `auto` intent once. Both upstream OpenAI
-Chat and OpenAI Responses encoders materialize that value explicitly, while
-preserving every client-supplied choice. OpenAI-origin `/v1/responses` ingress
-retains its own omission semantics; providers and models never choose this
-default.
-Some OpenAI-compatible upstreams expose their documented function-tag protocol
-through ordinary content instead of structured tool deltas. The shared
-Anthropic tool boundary recognizes that protocol only when tools were declared
-and the client did not explicitly choose `none`, and only when the response ends
-with one or more exact, schema-valid control blocks with no suffix. Any preceding
-content remains visible; all malformed or non-terminal lookalikes remain text.
-Native structured tool calls disable textual recovery and remain authoritative.
-This normalization is driven by the response grammar rather than provider or
-model identity; harness permissions remain the final authority for execution.
-Specialized provider packages remain only for true upstream quirks such as
-Gemini thought signatures, Groq reasoning-vocabulary negotiation, NIM
-tool-schema aliases, retry downgrades, and NVCF deployment-failure
-classification, or DeepSeek attachment/tool/thinking compatibility. Local
-Ollama, Ollama Cloud, llama.cpp, and LM Studio all use the
-same OpenAI-compatible Chat Completions provider family;
-Ollama's standard `reasoning` delta and history field are profile data rather
-than a specialized adapter. DeepSeek intentionally uses its
-OpenAI-compatible Chat Completions endpoint because that is the endpoint that
-reports prompt-cache hit/miss counters; the provider translates those native
-counters into Anthropic usage semantics. DeepSeek reasoning
-history is serialized per assistant turn: non-tool reasoning is omitted from
-its first replay, while tool-call reasoning is retained independently of the
-next generation's thinking mode. Append-only conversations therefore keep an
-identical message prefix without violating DeepSeek's tool-call replay contract.
-Cloudflare uses its
-account-scoped Workers AI OpenAI-compatible Chat Completions endpoint for
-`@cf/...` model IDs, while account ID composition, model search, and
-Cloudflare-specific reasoning deltas stay in the Cloudflare provider client.
-OpenRouter and Kilo remain specialized for capability-aware model filtering and
-structured reasoning-detail stream events. Kilo excludes image-output and
-Responses-only models from Chat Completions discovery while keeping direct model
-execution upstream-authoritative. Amazon Bedrock Mantle uses an ordinary profile with a region-specific,
-configurable OpenAI base URL and bearer API key; AWS SigV4 and native
-Converse/Invoke transports are outside that provider contract. Wafer, Kimi API,
-Kimi Code, MiniMax, Fireworks, and both Z.ai surfaces use ordinary
-declarative profiles for their thinking, token, and `extra_body` policy. Kimi
-Code remains distinct from Kimi API because its subscription key and base URL
-are a separate customer contract; its profile maps provider-neutral reasoning
-to Kimi's named efforts and identifies FCC through the upstream user agent.
-QwenCloud Coding Plan likewise remains distinct from QwenCloud Token Plan
-because its subscription key, quota, endpoint, and personal interactive-use
-contract are separate. It uses the ordinary OpenAI Chat transport, preserves
-reasoning history through `reasoning_content`, and does not impose one reasoning
-control or output-token default across its heterogeneous model catalog.
-ClinePass is a distinct subscription provider using Cline's programmatic
-`CLINE_API_KEY` and fixed OpenAI Chat Completions endpoint. Its declarative
-profile discovers only the dynamic `clinePass` catalog collection, consumes
-plaintext `reasoning`, preserves documented opaque `reasoning_details`, and
-sends no invented catalog-wide reasoning control. General Cline usage billing,
-CLI account authentication, and Cline-native tools remain separate product
-decisions.
-Z.ai Coding Plan (`zai`) and Z.ai API (`zai_api`) are distinct provider
-identities because their fixed endpoints select Coding Plan quota versus
-pay-as-you-go balance. They share the upstream `ZAI_API_KEY` and one declarative
-wire policy, while retaining separate proxies, provider instances, admission
-state, learned output caps, model caches, status rows, and model prefixes. FCC
-never probes or falls back between the two billing endpoints.
-Mistral La Plateforme keeps its native `reasoning_effort` and thinking-chunk
-request/stream mapping inside
-[providers/mistral/reasoning.py](src/free_claude_code/providers/mistral/reasoning.py), including its
-fallback retry when an upstream request rejects reasoning fields.
-NIM reasoning budget control is also treated as a provider-owned best-effort
-downgrade: if an upstream NIM deployment rejects explicit budget control, FCC
-retries without the budget while preserving thinking enablement.
-NIM also owns response normalization for model-native tool markup exposed in
-chat-completion text. The normalizer recognizes the native protocol signature
-only when tools are declared, validates one complete tool block against the
-request schemas, and converts it into ordinary OpenAI tool-call deltas before
-the shared stream runner can commit visible text. Native structured tool-call
-deltas remain authoritative when both forms appear; incomplete or invalid
-native markup is a retryable upstream protocol failure rather than user-visible
-assistant text. NIM argument-property aliases remain keyed by the original tool
-identity: shared OpenAI output restores the tool name first, then NIM restores
-arguments and validates the original schema.
-
-### Reasoning Ownership
-
-[core/reasoning.py](src/free_claude_code/core/reasoning.py) owns the immutable,
-provider-neutral `ReasoningPolicy`. It represents three distinct facts:
-
-- `control`: provider default, explicitly off, or explicitly on;
-- `effort`: the client's named effort when one was supplied;
-- `budget_tokens`: an exact positive client budget when one was supplied.
-
-When a numeric-budget provider needs a budget, `ReasoningPolicy` expresses named
-effort through FCC's single product scale: `minimal`/`low=512`, `medium=1024`,
-`high=2048`, `xhigh=4096`, and `max=8192`. Exact client budgets take precedence.
-
-The application layer resolves configuration and client input into this value;
-the API layer may replace it for a product policy such as the safety classifier;
-providers receive it unchanged. Provider adapters alone translate the subset
-their documented wire API can represent. The shared OpenAI-chat implementation
-uses small encoder objects for named effort, reasoning objects, thinking
-objects, chat-template booleans, numeric llama.cpp budgets, and split reasoning
-output. Specialized providers keep only translations that cannot be expressed
-by those encoders.
-
-Reasoning history replay is a separate request-conversion decision. Every
-profile explicitly chooses native `reasoning_content`, native `reasoning`,
-`<think>` tags, provider-specific chunks, or no replay. Turning off computation
-for the next generation does not silently erase prior assistant state required
-for a valid continuation.
-
-The boundary has five hard rules:
-
-1. Never inspect an upstream model name or version to select reasoning behavior.
-2. Prefer a provider's named effort vocabulary; use FCC's documented numeric
- scale only when the provider exposes a numeric budget rather than named effort.
-3. Never use the output-token limit as a reasoning budget. Forward exact or
- FCC-mapped budgets only through documented numeric fields; otherwise translate
- a supported named or boolean control and leave unsupported precision upstream.
-4. Provider-default intent emits no compute-control field. Explicit off requests
- an upstream disable where supported and always suppresses reasoning output at
- the FCC protocol boundary.
-5. Each provider profile has exactly one reasoning encoder. That encoder alone
- writes the provider's computation and reasoning-output request fields;
- unrelated request postprocessors never add, repair, or remove those fields.
-
-Shared provider responsibilities include upstream rate limiting, model listing,
-SDK/HTTP failure classification, safe diagnostic construction, HTTP resource
-cleanup, thinking/tool handling, retry or recovery where supported, and
-returning successful Anthropic SSE strings to the service layer. Final failures
-cross that boundary as `ExecutionFailure`, not as provider-authored wire events.
-Every provider receives the same concrete
-`MessagesRequest` owned by the Anthropic protocol package. Known wire fields are
-accessed through that model; `Any` and dynamic attribute lookup are reserved for
-SDK response objects and genuinely open-ended nested extension payloads.
-Provider-specific inputs that do not apply to other upstreams, such as
-Cloudflare's account ID, stay in that provider's factory/client instead of being
-added to shared `ProviderConfig`.
-Gateway providers such as Vercel AI Gateway, Hugging Face, and Cohere are
-profiles because their documented behavior is expressible as request policy.
-GitHub Models remains specialized because it owns API headers, a separate model
-catalog client, and capability filtering. The OpenAI-chat provider owns standard
-streamed usage handling: it requests
-`stream_options.include_usage`, consumes provider `prompt_tokens` and
-`completion_tokens` when present, and falls back to local estimates when
-providers omit or reject optional usage metadata. Provider modules only own true
-usage quirks: DeepSeek validates a complete hit/miss partition, maps misses to
-ordinary input and hits to cache reads, and never reports a miss as an
-Anthropic cache creation. The Messages-to-Responses presenter likewise
-partitions a valid cached-token detail from the upstream total. The
-Chat-to-Responses presenter recombines disjoint Chat input categories into its
-single `input_tokens` total, while the native Responses relay preserves the
-upstream usage object unchanged.
-
-### Adding A Provider
-
-1. Add provider metadata to [config/provider_catalog.py](src/free_claude_code/config/provider_catalog.py).
-2. Add credentials and related settings to [config/settings.py](src/free_claude_code/config/settings.py)
- and [.env.example](.env.example) when user configurable.
-3. Let Admin UI provider credential, configurable base URL, and proxy fields come from the
- catalog. Add admin-only help text or provider-specific fields under
- [config/admin/](src/free_claude_code/config/admin/) only when the generated manifest is
- insufficient.
-4. Add an `OpenAIChatProfile` under [providers/openai_chat/](src/free_claude_code/providers/openai_chat/) when
- request policy fully describes the upstream.
-5. Add a specialized provider package and sparse factory entry only when the
- upstream owns state, model-list behavior, stream events, or retry algorithms
- that a profile cannot express.
-6. Add deterministic tests under [tests/providers/](tests/providers/) and any
- relevant contract tests.
-7. Add smoke coverage or smoke config in [smoke/](smoke/) when the provider can
- be exercised live.
-8. Update user-facing provider docs in [README.md](README.md) when users need new
- setup instructions.
-
-## Protocol Conversion And Streaming Contracts
-
-[src/free_claude_code/core/anthropic/](src/free_claude_code/core/anthropic/) owns Anthropic-side protocol behavior:
-
-- `models.py` defines the permissive Messages and token-count wire requests,
- content/tool/thinking blocks, and Anthropic response envelopes;
-- trace-safe request snapshots stay beside those models so the generic trace
- module remains protocol-independent and import-order safe;
-- text, image, and message conversion for OpenAI-compatible upstreams;
-- request serialization primitives shared by provider request policies;
-- tool schema and tool-result handling;
-- thinking block handling;
-- stream lifecycle through `src/free_claude_code/core/anthropic/streaming`, including the neutral
- stream ledger, Anthropic SSE emitter, continuation-body construction, and tool repair;
-- Anthropic structural token counting and Anthropic-owned failure-kind-to-wire
- mapping.
-
-`MessagesRequest` is an ingress model; no current provider sends Anthropic wire
-requests downstream. Anthropic request models validate transcript data without
-merging, hoisting, or reordering semantically meaningful message roles.
-Top-level `system` content stays distinct from inline `system` messages.
-Target-protocol conversion owns their representation: neutral OpenAI Chat
-conversion emits top-level `system` content as the sole leading system message
-and maps inline `system` content into ordered `user` turns. After tool-result
-dependencies are ordered, a neutral whitespace-only assistant boundary closes
-any completed tool round before subsequent user input. Adjacent user content
-is then coalesced into one turn so strict chat templates receive neither
-`tool → user` nor consecutive user roles. Conversion preserves content order
-and rejects unrepresentable blocks instead of dropping them. Provider policies
-do not reinterpret this role mapping.
-
-Image conversion is a pure protocol operation. Core validates and normalizes
-supported Anthropic base64/data-URL and remote URL image sources without
-fetching remote content, then maps them to ordered OpenAI image parts. The same
-rules apply to direct user images and images nested in `tool_result` content.
-Because a Chat Completions `tool` message cannot carry multimodal content, the
-Chat translation closes every parallel tool call first and moves each rich tool
-result, with an explicit call-ID label, into the immediately following ordered
-multimodal user content. Text-only tool results keep the ordinary tool-message
-shape. Provider adapters do not gate image conversion behind a provider-wide
-vision flag; the selected upstream model owns image capability, while any
-deliberate provider-specific attachment removal remains explicit compatibility
-policy.
-
-Shared stream behavior lives under
-[src/free_claude_code/core/anthropic/streaming/](src/free_claude_code/core/anthropic/streaming/). The shared layer owns the
-Anthropic content-block ledger, SSE serialization, continuation request
-transformations, and tool JSON repair. It does not import `httpx` or the OpenAI
-SDK and does not decide whether an upstream failure is retryable.
-
-[core/failures.py](src/free_claude_code/core/failures.py) defines the immutable,
-protocol-neutral `FailureKind` and `ExecutionFailure`. The exception is the
-value propagated through async iterators; its semantic fields are immutable,
-while Python remains free to attach traceback/cause metadata during unwinding.
-[core/diagnostics.py](src/free_claude_code/core/diagnostics.py) owns bounded error
-body/cause extraction, credential redaction, safe traceback formatting, and
-copyable request-ID diagnostics. Anthropic and Responses packages independently
-map the canonical kind and status to their wire error types.
-
-[providers/failure_policy.py](src/free_claude_code/providers/failure_policy.py)
-owns generic raw OpenAI SDK and `httpx` exception classification,
-transient status/body inference, stable provider wording, and final diagnostic
-construction for those failures. It also owns phase-specific retry
-qualification: admission classifies failures while opening an operation, while
-an already-open stream uses the narrower stream-failure policy.
-Concrete adapters may supply one narrow semantic override for an upstream quirk
-that the shared SDK cannot express correctly. The concrete adapter owns the
-exact upstream marker, while the shared failure policy owns its canonical
-meaning and wording. Admission uses that meaning for retry qualification while
-retaining the raw exception, so exhausted retries still receive the original
-HTTP status/body through the shared redaction and diagnostic path. For NVCF's
-function-scoped failure this deliberately keeps the simple
-one-controller-per-provider policy; a degraded NIM function can therefore
-briefly pause other NIM models during shared recovery. No provider-specific
-marker enters `core/`, another provider, or an API adapter.
-
-[providers/stream_recovery.py](src/free_claude_code/providers/stream_recovery.py)
-owns only the 0.75-second/65,536-byte commit holdback and the choice between
-transparent replay, request-local continuation/tool salvage, and final failure.
-It consumes an explicit retryability decision and does not import provider
-transport SDKs or classify exceptions.
-`ProviderExecution` owns one five-attempt budget for the whole logical
-operation: initial opening, deterministic request-shape corrections, early
-replay, continuation, and tool repair all consume that same budget through
-separate `ProviderAttempt` leases. There are no nested retry counters or
-controller-owned callback loop. Deterministic corrections retry immediately;
-transient failures use exponential backoff with jitter and honor `Retry-After`
-as a minimum. When partial output exists, the last available attempt is reserved
-for continuation or repair instead of replaying the full request again.
-Completed tool calls can be salvaged without an upstream attempt. The
-application-owned progress window is an outer no-progress bound, not another
-retry counter: opening a new attempt never resets it, while a real emitted
-provider chunk does. Fast transient failures can therefore still use all five
-attempts, but repeated fully-stalled operations cannot outlive the downstream
-harness.
-
-For streams, upstream acceptance is the first received chunk. Retryable failure
-before that point participates in provider-wide coordinated recovery. Failure
-after that point remains request-local so one interrupted connection does not
-freeze healthy parallel streams, but any continuation still consumes the same
-execution budget. The OpenAI SDK's internal retries remain disabled so FCC is
-the only retry owner. `ExecutionFailure.retryable` records provider-policy
-eligibility; it never tells the client to retry after FCC has finalized the
-failure.
-
-The OpenAI-chat provider remains an upstream adapter: it converts OpenAI chat
-chunks into ledger operations. After retry, continuation, and tool salvage are
-exhausted, it discards uncommitted output or flushes committed output, closes
-open content blocks, and raises `ExecutionFailure`. It never synthesizes a
-terminal Anthropic error event.
-
-The public HTTP commit boundary solely decides whether a final failure can use
-non-2xx JSON or must use a terminal protocol event; the protocol packages own
-envelope and event serialization. Before the first public frame the boundary
-returns typed non-2xx JSON with `x-should-retry: false`; after the first frame
-Messages appends one Anthropic `event: error`, while Responses emits
-`response.failed` with the original response ID. Non-streaming Messages catches
-the same failure and discards its partial aggregate. Unexpected failures use the
-same commit-state split but do not acquire provider retry semantics.
-
-[src/free_claude_code/core/openai_responses/](src/free_claude_code/core/openai_responses/) owns OpenAI Responses support:
-
-- the permissive `OpenAIResponsesRequest` ingress model used directly by the
- FastAPI route, application executor, and provider ports;
-- direct Responses-to-Chat request translation in `chat_request.py`;
-- Messages-to-Responses request and stream translation in
- `provider_input.py` and `provider_stream.py`;
-- native Responses request shaping and event relay in `native.py`;
-- Responses event, block, tool-identity, reasoning, token-estimation, ID, and
- error-envelope helpers used by the transport-owned presenters.
-
-The package intentionally does not implement the full OpenAI Responses surface.
-FCC accepts omitted `stream` or `stream: true`; `stream: false` is rejected with
-an OpenAI-shaped client error because installed FCC/Codex workflows only need
-streaming. The application port exposes separate Messages and Responses
-preflight/stream methods; providers choose the upstream transport without
-changing the public request type. This produces exactly three translations:
-Messages-to-Chat, Messages-to-Responses, and Responses-to-Chat. Native
-Responses-to-Responses is an identity relay, not a fourth translation. FCC does
-not maintain a universal canonical inference schema between these boundaries.
-
-The direct Responses-to-Chat cell preserves text, direct images,
-function/custom tool identity, call IDs, reasoning replay data, supported
-request options, and usage, then writes one coherent Responses lifecycle from
-Chat stream semantics. Image-bearing `function_call_output` content and
-`computer_call_output` screenshots use the same Chat tool-round rule: required
-tool messages are emitted first, followed by labeled multimodal user content in
-source order. The Messages-to-Responses cell preserves direct and nested
-tool-result images while writing Anthropic SSE from Responses events. Native
-Responses forwarding keeps nested request extensions—including file-ID image
-references—and upstream response/item/call IDs, event order, reasoning
-payloads, and exact usage; it rewrites only FCC-owned routing fields such as the
-public model and enforces stateless streaming. Cross-protocol image references
-that only contain an upstream file ID cannot be represented without fetching
-or storage, so the owning translator rejects them before upstream I/O instead
-of silently dropping the image.
-
-Application-resolved reasoning controls remain on the immutable source request.
-Provider adapters consume the resolved `ReasoningPolicy`; each cross-protocol
-translator maps the replay material its target supports, while the native cell
-passes Responses reasoning through unchanged. Tool-name flattening is likewise
-limited to OpenAI-compatible cross-protocol boundaries and is reversed at the
-public edge. Output presenters own provider-attempt event construction and
-terminal failure framing. If an application-owned failure occurs after the
-public stream commits, the API wire boundary closes that same public lifecycle;
-providers continue to own HTTP classification, retry policy, admission, and
-physical stream cleanup.
-
-Provider code should delegate protocol details to these modules. Avoid copying
-conversion code into individual providers, and avoid provider-to-provider imports
-for shared Anthropic behavior.
-
-## Local Optimizations And Server Tools
-
-[api/optimization_handlers.py](src/free_claude_code/api/optimization_handlers.py) short-circuits
-common low-value client requests before they reach a provider:
-
-- quota probes;
-- command prefix detection;
-- title generation;
-- suggestion mode;
-- filepath extraction.
-
-Detection derives a read-only semantic view: inline `system` messages contribute
-system context but are not counted as conversational turns. The original
-request remains ordered and unchanged for provider execution.
-
-The Messages handler runs these only after model routing and after local server-tool
-handling. Each optimization is controlled by settings flags.
-
-Claude Code auto-mode safety-classifier requests are a message-only routing
-policy, not a short-circuit response. After routing, the Messages handler detects
-the exact current severity or legacy Boolean classifier shape, forces reasoning
-off, and consumes only that classifier's optional `</severity>` or `</block>`
-terminator before provider execution. Claude accepts the parser-readable verdict
-when the provider completes normally with `end_turn`; FCC does not fabricate a
-stop reason or truncate the output. Unrecognized and non-classifier stop
-sequences remain on the request so a target converter can preserve them or reject
-the request as lossy. This policy belongs to the Claude Messages boundary, never
-to an OpenAI provider or model-specific adapter.
-
-Local `web_search` and `web_fetch` compatibility lives under
-[api/web_tools/](src/free_claude_code/api/web_tools/). It is enabled by default
-and can be disabled with `ENABLE_WEB_SERVER_TOOLS=false`. Forced
-`web_search_20250305` and `web_fetch_20250910` requests bypass the provider and
-retain the existing local result lifecycle. [api/web_tools/egress.py](src/free_claude_code/api/web_tools/egress.py)
-continues to own URL-scheme and private-network restrictions for forced
-`web_fetch`.
-
-Current Claude Code uses a separate subordinate Messages request when its outer
-`WebSearch` tool is available. For the exact request containing only
-`web_search_20250305` with omitted or automatic tool choice, the Messages
-boundary translates that server tool into one private ordinary search function.
-`ProviderExecutor` runs and buffers one normal provider decision, preserving its
-retry, fallback, timeout, and failure behavior. If the model declines the tool,
-FCC replays the buffered stream unchanged. If the model selects one valid query,
-FCC discards the private function frames, searches the fixed DuckDuckGo backend,
-and emits the existing Anthropic `server_tool_use` and
-`web_search_tool_result` lifecycle. Claude Code owns the outer continuation; FCC
-does not run a second provider round or persist hidden transcript state.
-
-Other Anthropic server-tool shapes remain fail-closed before provider execution:
-automatic WebFetch, mixed tool lists, newer unverified versions, prior hosted
-server-tool history, and extra choice semantics are not generalized. This keeps
-the compatibility exception at the Messages/API boundary rather than leaking
-server-tool semantics into providers or the executor.
-
-## CLI Launchers And Managed Claude
-
-[cli/local_http.py](src/free_claude_code/cli/local_http.py) owns the direct
-agent-to-FCC connection boundary. Launcher health checks and local model-catalog
-requests never inherit environment or operating-system forward proxies. Every
-spawned agent environment preserves the user's outbound proxy configuration but
-adds the configured FCC host and standard loopback names to both `NO_PROXY` and
-`no_proxy`. Provider-specific upstream proxies remain provider-owned and do not
-participate in this local boundary.
-
-[cli/claude_env.py](src/free_claude_code/cli/claude_env.py) owns the canonical
-Claude Code proxy environment used by every FCC-launched Claude process. It
-strips inherited `ANTHROPIC_*` variables, sets `ANTHROPIC_BASE_URL`, enables
-gateway model discovery, configures the auto-compact window, disables
-nonessential Anthropic traffic, and always sets the retained non-empty
-`ANTHROPIC_AUTH_TOKEN`. Server-side authentication enablement does not alter the
-client environment.
-
-[cli/launchers/claude.py](src/free_claude_code/cli/launchers/claude.py) owns the installed
-`fcc-claude` launcher:
-
-- `fcc-claude` applies the shared proxy environment without changing the user's
- Claude command arguments.
-
-[cli/launchers/codex.py](src/free_claude_code/cli/launchers/codex.py) owns the installed
-`fcc-codex` launcher:
-
-- `fcc-codex` strips official OpenAI and Codex credential variables.
-- It strips parent-only Codex thread, shell, permission, and origin context so
- each launched client owns an independent runtime identity.
-- It creates an ephemeral `fcc` model provider with `wire_api = "responses"` and
- a base URL pointing at the local proxy `/v1` path.
-- After proxy health succeeds, it fetches `/v1/models`, writes a generated Codex
- `model_catalog_json` file under `~/.fcc/`, and injects that path so Codex's
- native `/model` picker lists FCC provider slugs. Catalog generation is
- fail-open: launch continues with a warning if the catalog cannot be prepared.
-- When the catalog projects the configured provider reference under a different
- wire slug, `fcc-codex` selects that advertised slug. Failed, empty, or
- incomplete discovery leaves the configured provider reference unchanged.
-- The server lifecycle independently keeps that same file synchronized for
- Codex App and IDE processes that are not launched through `fcc-codex`.
-- Launcher-side catalog discovery authenticates directly with the canonical proxy
- token.
-- Inference through `fcc-codex`, Codex App, and IDE integrations uses the same
- command-backed provider authentication. Codex invokes
- `fcc-codex --print-proxy-auth-token`, which reads the canonical FCC settings,
- prints only the shared proxy-auth token (or the no-auth sentinel), and exits
- without a proxy preflight, model request, or client process. This gives every
- Codex surface one credential owner instead of competing with Codex's signed-in
- OpenAI authorization.
-
-[cli/launchers/model_catalog.py](src/free_claude_code/cli/launchers/model_catalog.py)
-consumes the direct Responses view, validates its nested `provider/model`
-references, and is shared by Codex, OpenCode, Cline, Hermes, DeepSeek Harness,
-Grok Build, and Muse Code. The API owns compatibility filtering and direct wire
-identity; each launcher owns only translation into its client's configuration
-format.
-
-[cli/launchers/pi.py](src/free_claude_code/cli/launchers/pi.py) owns the installed
-`fcc-pi` launcher and [cli/launchers/pi_extension.ts](src/free_claude_code/cli/launchers/pi_extension.ts)
-is its bundled Pi adapter:
-
-- Session commands load the extension from its absolute installed path and
- scope Pi to the ephemeral `free-claude-code/**` provider, whose model IDs
- retain FCC's nested `provider/model` routing reference.
-- The extension fetches FCC's `/v1/models` catalog before registration, projects
- the direct Messages view, and registers an `anthropic-messages`
- provider targeting the local proxy. Catalog failure is fail-closed so Pi never
- silently falls back to a different provider.
-- Catalog discovery and provider inference use HTTP bearer authorization. Pi's
- provider API-key field remains its process-local credential carrier.
-- FCC connection values live only in child-process `FCC_PI_*` variables. Native
- Pi credentials and persistent configuration remain untouched.
-- Pi package-management, configuration, help, and version commands pass through
- unchanged because they do not create an FCC-backed session.
-
-[cli/launchers/opencode.py](src/free_claude_code/cli/launchers/opencode.py) and
-[cli/launchers/opencode_config.py](src/free_claude_code/cli/launchers/opencode_config.py)
-own the installed `fcc-opencode` launcher for stable OpenCode V1:
-
-- Inference commands require OpenCode V1 1.18.18 or newer, a reachable FCC
- server, and a non-empty routable `/v1/models` snapshot. Preparation is
- fail-closed so OpenCode cannot fall back to a native provider.
-- The launcher creates a temporary, secret-free `free-claude-code` provider
- catalog and a protected process overlay. The provider uses `@ai-sdk/openai`
- against FCC's `/v1` Responses surface, and bearer material is carried only in
- the child environment.
-- Existing `OPENCODE_CONFIG` or `OPENCODE_CONFIG_CONTENT` overrides are rejected
- because their precedence would make FCC routing ambiguous. Persistent OpenCode
- config, data, credentials, plugins, and sessions remain OpenCode-owned and are
- never rewritten.
-- Native help, version, authentication, upgrade, uninstall, and completion
- commands pass through without requiring FCC. Other arguments are forwarded
- unchanged after the FCC process configuration is ready.
-
-[cli/launchers/cline.py](src/free_claude_code/cli/launchers/cline.py) and
-[cli/launchers/cline_config.py](src/free_claude_code/cli/launchers/cline_config.py)
-own the installed `fcc-cline` launcher for Cline CLI 3.0.55 or newer:
-
-- Attached inference sessions require a reachable FCC server and a non-empty
- routable `/v1/models` snapshot. Preparation is fail-closed, and the launcher
- prepends Cline's built-in `openai-native` provider while leaving an explicit
- caller `--model` selection intact.
-- The launcher creates protected temporary `providers.json` and `models.json`
- files. For that child only, they retarget Cline's existing OpenAI Responses
- transport to FCC's `/v1` surface, rename it to Free Claude Code, replace its
- catalog with nested FCC model slugs, and carry the canonical proxy token.
- Cline 3.0.55's session gateway cannot instantiate user-defined provider IDs,
- so this built-in transport seam is required even though its startup picker can
- read custom providers.
-- `CLINE_PROVIDER_SETTINGS_PATH` points only that child at the generated
- settings, and `CLINE_SESSION_BACKEND_MODE=local` keeps attached sessions in
- the launcher lifecycle. Native Cline config, data, credentials, plugins, and
- sessions remain Cline-owned.
-- Native configuration and package-management commands pass through without
- requiring FCC. Hub, dashboard, schedule, connection, hook, kanban, and Zen
- surfaces are rejected because they can outlive the temporary credential and
- must be run with ordinary `cline`.
-- Cline sandbox data overrides are also rejected: released Cline rewrites its
- provider-settings path in that mode, which would displace FCC's ephemeral
- credential file. Ordinary Cline remains the owner of sandboxed runs.
-- Cline's provider picker can still expose its native providers. Startup and
- command-line routing remain FCC-owned; deliberately switching providers
- inside the running Cline process is an explicit opt-out for that process.
-
-[cli/launchers/hermes.py](src/free_claude_code/cli/launchers/hermes.py) and
-[cli/launchers/hermes_config.py](src/free_claude_code/cli/launchers/hermes_config.py)
-own the installed `fcc-hermes` launcher for Hermes Agent 0.20.4 or newer:
-
-- Attached sessions require a reachable FCC server, a canonical proxy token,
- and a non-empty routable `/v1/models` snapshot. The launcher rejects caller
- provider overrides and validates explicit model choices against that snapshot.
-- Each invocation gets a private, secret-free Hermes managed overlay containing
- a uniquely named custom provider. Hermes uses its `codex_responses` transport
- against FCC's `/v1`; the proxy token exists only in a unique child-process
- environment variable.
-- Hermes itself verifies that the overlay is active before inference begins.
- Existing administrator-managed scopes are rejected rather than shadowed, and
- failures in version, health, catalog, temporary configuration, or activation
- all stop before the attached session starts.
-- The overlay clears Hermes's main fallback formats and pins the audited built-in
- auxiliary tasks to the live FCC route while preserving same-route retries.
- Native profiles, sessions, memory, skills, plugins, credentials, and
- `HERMES_HOME` remain Hermes-owned.
-- Help, version, and ordinary management commands pass through without FCC.
- Detached services are rejected because they can outlive the temporary route.
- A deliberate in-session `/model` switch is an explicit opt-out; Hermes has no
- process-wide provider lock for every plugin or future subsystem.
-
-[cli/launchers/dsh.py](src/free_claude_code/cli/launchers/dsh.py) and
-[cli/launchers/dsh_config.py](src/free_claude_code/cli/launchers/dsh_config.py)
-own the installed `fcc-dsh` launcher for DeepSeek Harness 0.1.0-rc.8:
-
-- Only the shipped attached Web and headless profiles route through FCC. Bare
- `fcc-dsh` selects Web; native help, version, profile dumps, and plugin
- management pass through without requiring FCC.
-- Routed sessions require an exact audited DSH version, a reachable FCC server,
- a canonical proxy token, and a non-empty routable `/v1/models` snapshot.
- Preparation is fail-closed.
-- Each invocation writes private temporary settings, credentials, and patch
- files. The patch configures DSH's existing `openai-responses` transport for
- FCC's `/v1` endpoint and explicit model snapshot; the bearer token remains in
- a child-only environment variable. `DSH_HOME`, sessions, presets, attachments,
- and plugins remain DSH-owned.
-- The native DeepSeek model adapter, native model-backed Web search, and bundled
- Web tool are disabled for the FCC session. DSH provider retries are set to
- zero so `ProviderExecutor` alone owns retries and ordered model fallback. The
- DSH stream-idle timeout is derived from FCC's provider progress timeout with
- a shutdown margin.
-- The exact pre-release gate is intentional because DSH declares breaking
- preview changes. Third-party DSH plugins remain capable of their own network
- activity; `fcc-dsh` owns the configured model route, not a general plugin
- sandbox.
-
-[cli/launchers/grok.py](src/free_claude_code/cli/launchers/grok.py) owns the
-installed `fcc-grok` launcher for Grok Build 1.0.5 or newer:
-
-- Attached TUI, headless, and `agent stdio` sessions require a reachable FCC
- server, a canonical proxy token, and a non-empty direct Responses catalog.
- Model overrides are validated before Grok starts; preparation is fail-closed.
-- A child-only environment points Grok's native Responses backend and model
- picker at FCC, sets client retries to zero through catalog metadata, and
- derives its idle timeout from FCC's provider-progress boundary. Native Grok
- configuration, credentials, sessions, plugins, skills, and telemetry remain
- Grok-owned and are never rewritten.
-- The wrapper prevents native leader or endpoint overrides for attached
- sessions. Detached modes pass through or fail explicitly according to their
- lifecycle, rather than outliving FCC's process-only route.
-- Grok's built-in web search and fetch are disabled because they use a distinct
- Responses-side service contract FCC does not implement. Ordinary `grok`
- remains unchanged.
-
-[cli/launchers/muse.py](src/free_claude_code/cli/launchers/muse.py) owns the
-installed `fcc-muse` launcher for Muse Code 0.2.1 or newer:
-
-- Attached TUI, `exec`, and `resume` sessions require a reachable FCC server,
- a canonical proxy token, and a non-empty direct Responses catalog. Caller
- provider and base-URL overrides are rejected, and explicit model choices are
- validated before Muse starts.
-- A child-only environment replaces Muse's Meta bearer token and removes
- inherited model, custom-header, and routing controls. Grammar-correct
- `--provider meta`, FCC `/v1`, and model flags route the native Muse Responses
- transport through FCC without writing Muse configuration or account state.
-- Muse fetches `/muse-code/models`; that authenticated route is a fixed alias
- over FCC's existing Responses catalog builder rather than another inventory.
- Native help, authentication, configuration, export, trace, skills, sandbox,
- and initialization commands pass through without requiring FCC.
-- Muse retains its native whole-request retry loop because release 0.2.1 has no
- complete process-scoped retry-off control and does not honor
- `x-should-retry: false`. FCC still owns provider retries and ordered model
- fallback inside each repeated request; the launcher does not mutate Muse's
- persistent retry settings.
-- Meta's official installer supports macOS, Linux, and WSL. On native Windows,
- FCC's standalone Muse installer selects and verifies Meta's published Windows
- artifact, then owns its fixed local executable and PATH lifecycle without
- adopting external Muse installations.
-
-[cli/managed/](src/free_claude_code/cli/managed/) owns managed Claude Code subprocesses used by
-Discord and Telegram messaging. Managed task invocations extend the same proxy
-environment only with non-interactive terminal settings, optional `--resume`,
-optional `--fork-session`, `--model fable`, and `--output-format stream-json`.
-Messaging pins this Claude tier alias so phone sessions route through
-`MODEL_FABLE` or the `MODEL` fallback instead of inheriting a user's interactive
-`/model` picker state. Managed execution does not override Claude's
-`plansDirectory`; plan files use Claude's native user-level location so the
-project workspace may reside on any filesystem volume. The managed session
-parser extracts persistent Claude session IDs and yields Claude stream-json
-events to the messaging event parser. Managed Claude
-also owns subprocess stderr diagnostic classification so known benign Claude
-Code notices do not become messaging task errors, while unknown stderr remains
-fatal. Before subprocess stop, the manager marks the session closing so new
-lookups and aliases cannot borrow it; the session also marks itself terminal so
-an already-issued reference cannot launch again. One lifecycle lock linearizes
-that terminal transition with subprocess publication. Aliases plus PID
-registration remain owned until exit is confirmed. Aggregate shutdown attempts
-every distinct mapped or closing session, removes only confirmed successes,
-reports a count-only failure, and leaves failures available for the next cleanup
-attempt. Real-session registration is collision-safe and becomes durable tree
-state only after the manager accepts it.
-
-Codex, Pi, OpenCode, Cline, Hermes, DeepSeek Harness, Grok Build, and Muse Code
-are supported through their installed launchers. FCC does not keep internal
-managed session runners for them because no user-facing messaging setting
-selects those clients for Discord or Telegram.
-
-## Messaging Architecture
-
-Messaging is optional. [runtime/application.py](src/free_claude_code/runtime/application.py) calls
-`create_messaging_components()` from
-[messaging/platforms/factory.py](src/free_claude_code/messaging/platforms/factory.py) during startup.
-If `MESSAGING_PLATFORM` is `none`, or if the selected platform token is missing,
-the messaging bridge is skipped.
-
-`ApplicationRuntime` privately owns the selected platform runtime, the
-`MessagingWorkflow`, configured `Transcriber`, and managed CLI session manager.
-The workflow owns conversation snapshot restoration and terminal close: cancel
-work, stop managed CLI sessions, await every processor-owned claim and recovery
-task, then flush persistence. Interactive `/stop` keeps its bounded task-drain
-behavior; only terminal close waits for full completion.
-The API sees only the application-owned `TaskController` used to preserve
-`/stop` behavior.
-
-The platform factory returns a `MessagingPlatformComponents` bundle from
-[messaging/platforms/ports.py](src/free_claude_code/messaging/platforms/ports.py): a
-`MessagingRuntime` with separate `quiesce()` and `close()` phases, an
-`OutboundMessenger` for queued sends/edits/deletes, an optional
-`VoiceCancellation` port for scoped and bulk voice cancellation during `/stop`
-and `/clear`, and an optional immutable startup-notice intent. Workflow code
-depends on these ports and values, not on Telegram or Discord SDK objects.
-
-Runtime adapters in
-[messaging/platforms/telegram.py](src/free_claude_code/messaging/platforms/telegram.py) and
-[messaging/platforms/discord.py](src/free_claude_code/messaging/platforms/discord.py) own SDK client
-lifecycle, event subscription, inbound handoff, voice-note handoff, and one
-injected `MessagingRateLimiter`. The platform factory creates a fresh limiter
-for the selected runtime. `quiesce()` stops new SDK ingress and drains active
-handlers while delivery remains available; after workflow tasks settle,
-`close()` drains the outbox and limiter. Discord additionally retains, observes,
-and drains its long-lived client task and inbound-handler tasks, so an SDK exit
-after initial readiness immediately withdraws the runtime's connected state.
-Telegram retries initialization and polling as separate repeatable steps; it
-never restarts an already-running SDK application after polling bootstrap fails.
-Separate application runtimes cannot share or stop each other's queue. Inbound
-normalization lives in
-[messaging/platforms/telegram_inbound.py](src/free_claude_code/messaging/platforms/telegram_inbound.py)
-and [messaging/platforms/discord_inbound.py](src/free_claude_code/messaging/platforms/discord_inbound.py).
-Outbound SDK calls live in
-[messaging/platforms/telegram_io.py](src/free_claude_code/messaging/platforms/telegram_io.py) and
-[messaging/platforms/discord_io.py](src/free_claude_code/messaging/platforms/discord_io.py). Shared
-delivery policy lives in [messaging/platforms/outbox.py](src/free_claude_code/messaging/platforms/outbox.py),
-which requires that limiter directly and owns queued send/edit/list-based delete,
-dedup keys, and retained fire-and-forget tasks. Shutdown cancels and awaits both
-queued limiter work and arbitrary outbox work; there is no optional unthrottled
-fallback, and both owners reject admission once close begins. Workflow and command code request deletion of
-message ID lists; platform IO decides whether to use native batch deletion
-(Telegram) or internal per-message deletion (Discord).
-Shared voice-note orchestration lives in
-[messaging/platforms/voice_flow.py](src/free_claude_code/messaging/platforms/voice_flow.py), which owns
-file-size validation, temp-file cleanup, transcription, error replies, and the
-handoff to `IncomingMessage`. Before status delivery it reserves an opaque claim
-in the `PendingVoiceRegistry` owned by [messaging/voice.py](src/free_claude_code/messaging/voice.py).
-That registry atomically owns optional status binding, cancellation by either
-message ID, and one child task that retains the exclusive handoff lease through
-the complete workflow callback. An explicit stop or clear atomically removes
-the exact claim and assumes ownership under the registry lock, then cancels and
-joins its published child without holding that lock. Caller cancellation instead
-keeps both aliases published while it cancels and drains the child, then removes
-only that exact generation. Repeated cancellation cannot abandon either join or
-pre-handoff cleanup, and fatal callback failures release the aliases before they
-propagate. A cancellation that wins turns late status, transcription, callback
-completion, or ordinary callback failure into cleanup-only work. Bulk
-cancellation deduplicates the voice/status aliases and excludes the exact
-current handoff child plus claims participating in a nested cancellation, so a
-voice-transcribed `/stop` or `/clear` cannot cancel itself or form a recursive
-join cycle. A stale flow cannot bind or remove a newer generation reusing the
-same ID. Pending voice identities use the same
-`(platform, chat_id)` `MessageScope` as tree references, so raw IDs from different
-transports cannot share cancellation ownership. The flow depends only on the
-consumer-owned `Transcriber` protocol. Bootstrap selects either the
-instance-owned local Whisper `TranscriptionService` or the provider-owned
-`NvidiaNimTranscriber`. Messaging no longer imports a provider adapter, and the
-local service retains only one lazy pipeline for its immutable runtime settings;
-caller cancellation waits for thread-backed transcription to actually exit
-before temporary files, pipelines, or credentials are released. The NIM adapter
-closes its per-call authenticated gRPC channel before that worker exits. Changing the
-credential used by an active voice backend through Admin is therefore
-restart-required, while the same provider credential remains hot-replaceable
-when voice does not use it.
-
-[messaging/workflow.py](src/free_claude_code/messaging/workflow.py) contains `MessagingWorkflow`, the
-platform-agnostic coordinator. It owns dependencies, render settings, the
-state-transaction lock, global stop generation, per-chat clear generations,
-stop/clear side effects, and shutdown-visible state. Each inbound turn snapshots
-both applicable generations before external status I/O and rechecks them while
-committing admission. Global `/stop` invalidates every older provisional turn;
-standalone `/clear` invalidates only the invoking `MessageScope`. Before taking
-the workflow lock, those commands cancel and join their applicable older voice
-handoffs; they then cancel any matching tree that won admission during the join.
-Reply-scoped commands first join the matching voice claim and then apply an exact
-reference transition, so either the voice cancellation or admitted-tree
-transition wins without double-counting. Stop operations return one typed
-outcome after assigning every terminal status owner. The outcome records which message scopes own terminal
-status feedback. Existing task statuses are the sole success UI when every
-affected status is in the invoking scope; the command adapter sends a message
-for a no-op, any cross-scope work, or the rare voice cancellation that wins
-before a status ID is bound. Generation validation, tree admission, processor
-publication, and persistence of the detached snapshot complete as one
-workflow-owned operation; caller cancellation is restored only after that
-transaction finishes. Stop and clear use the same completion-driven boundary,
-so caller cancellation cannot leave a committed state transition without its
-remaining cancellation and persistence cleanup. At startup it restores and normalizes
-persisted state before ingress begins, then repairs interrupted platform
-statuses after outbound delivery starts. Diagnostic detail policy is captured
-at construction and passed into the processor; messaging does not read global
-settings while executing callbacks or failures.
-
-Clearable lifecycle notices are workflow-owned rather than SDK-runtime side
-effects. After transport readiness and restored-status repair,
-`ApplicationRuntime` hands the platform's semantic startup-notice intent to the
-workflow. The workflow owns platform rendering and snapshots the notice chat's
-clear generation before sending outside its state lock. Once delivery returns a
-message ID, a cancellation-safe finalizer briefly reacquires the lock: it records
-the ID only if no standalone clear in that chat or startup cancellation crossed
-the reservation;
-otherwise it releases the lock and deletes the notice. Failed compensation
-attempts to restore the ID to the current managed-message log so a later `/clear` can
-retry. No platform I/O runs under the workflow lock. Ordinary notice-send
-failure is privacy-safe and nonfatal, while cancellation before a delivery
-receipt remains immediate and cannot create a phantom message ID.
-
-[messaging/turn_intake.py](src/free_claude_code/messaging/turn_intake.py) owns slash command dispatch,
-status-echo filtering, initial status messages, and rendering detached frozen
-admission/queue effects. The workflow records each accepted inbound prompt,
-voice note, or command before intake performs external status I/O. Intake asks
-the workflow to resolve and admit turns rather than receiving a mutable tree.
-Reply lookup is always scoped by platform and chat; an unknown or cross-chat
-reference starts an independent root. A previously resolved exact parent that a
-concurrent clear removes is instead rejected as `PARENT_REMOVED`; intake then
-best-effort deletes both the stale child prompt and its provisional status.
-Duplicate delivery deletes only its provisional status.
-
-[messaging/node_runner.py](src/free_claude_code/messaging/node_runner.py) owns managed CLI session
-lifecycle for queued nodes: parent-session fork/resume, session registration,
-CLI event parsing, transcript/status updates, cancellation, error propagation,
-and session cleanup. It executes an immutable `NodeClaim`; session, completion,
-and failure writes return through `TreeQueueManager` with that claim identity. A
-non-exit CLI error may render an error immediately, but only a terminal failure
-propagates to queued descendants; a later successful exit is authoritative for
-the same live, non-cancelled claim. A stale runner receives no snapshot and
-cannot restore a branch removed by `/clear`.
-
-[messaging/event_parser.py](src/free_claude_code/messaging/event_parser.py) normalizes managed Claude
-JSON events into low-level transcript events.
-[messaging/transcript/](src/free_claude_code/messaging/transcript/) owns transcript assembly and
-rendering: open content-block tracking, Task/subagent display state, segment
-models, render context, and truncation. Platform markdown details stay in
-[messaging/rendering/](src/free_claude_code/messaging/rendering/).
-
-[messaging/command_context.py](src/free_claude_code/messaging/command_context.py) defines the typed
-dependency surface for `/stop`, `/clear`, and `/stats`; commands should not
-depend on the concrete workflow object or on platform SDK runtimes.
-
-[messaging/trees/runtime.py](src/free_claude_code/messaging/trees/runtime.py) contains the
-`MessageTree` aggregate. Its lock is private, and complete operations own every
-graph/queue/claim invariant: add-and-admit, enqueue-or-claim,
-finish-and-claim-next, semantic state writes, cancellation, and atomic branch
-removal. Logical `parent_id` owns execution/session ancestry, while
-`parent_reference_id` records the exact prompt or FCC status that received the
-platform reply. The aggregate derives literal reference adjacency from those
-canonical fields instead of maintaining a second graph. Removing a prompt
-therefore removes its status and every literal descendant; removing a status
-preserves its prompt and prompt-level siblings while invalidating that prompt's
-session. `TreeIdentity` is `(platform, chat_id, root_message_id)`, because
-platform message IDs are not globally unique. Every execution receives a fresh
-opaque claim ID, so a task from an older runtime generation cannot mutate or
-collide with a re-admitted tree. Active execution ownership is separate from the
-node's UI state: cancellation can still reach a task that already rendered
-complete/error but is cleaning up, while a cancellation tombstone prevents late
-success from reviving a stopped node. Only the matching finish transition may
-select the FIFO successor. Duplicate node/status admission and terminal-node
-re-admission are rejected without changing active state.
-
-[messaging/trees/transitions.py](src/free_claude_code/messaging/trees/transitions.py) owns frozen,
-slotted claims, queue entries, read views, and cancellation/removal effects.
-These values copy the UI and execution facts callers need and never contain a
-mutable `MessageNode`, lock, or `asyncio.Task`.
-
-[messaging/trees/manager.py](src/free_claude_code/messaging/trees/manager.py) is the only external
-tree facade. It keeps one structural lock across aggregate membership changes
-and repository index publication/removal, registers node and status references
-together under `MessageScope`, coordinates cross-tree requests, and returns
-transition-owned snapshots. Claim completion re-enters that same lock: the
-manager verifies the exact aggregate is still published and publishes any
-successor task slot before a competing detach can commit. Cancellation and
-removal entrypoints finish their exact transition despite caller cancellation,
-so a committed detach cannot lose its persistence result. Reply `/clear` is one
-exact-reference cancel-and-detach transition before platform I/O; standalone
-clear atomically detaches every aggregate in the invoking scope before task
-draining. Reply `/stop` cancels exactly one request; its matching finisher
-releases execution ownership and advances the next eligible queued request.
-Global `/stop` drains every queue instead, and reply `/clear` removes the selected
-literal message subtree before any survivor can advance. Separate scopes and
-trees still progress independently. Subtree transitions return exact reference
-IDs for both repository unindexing and authorized platform deletion, including
-user-authored messages selected by the explicit command.
-[messaging/trees/repository.py](src/free_claude_code/messaging/trees/repository.py)
-is manager-private and owns only aggregate/reference indexes.
-[messaging/trees/processor.py](src/free_claude_code/messaging/trees/processor.py) owns every
-`asyncio.Task`, keyed by globally unique claim ID. It publishes a task slot
-before task creation, which is safe under Python's eager task factory, then
-launches claims returned by the aggregate, cancels the exact matching task,
-drains cleanup outside tree locks, and feeds matching completion back to the
-aggregate. Cancellation before a task body starts has an explicit recovery path;
-the cancellation flag is rechecked after callbacks, and best-effort UI callback
-failure cannot prevent successor launch. If a node processor unexpectedly
-escapes, the processor routes failure through the manager-owned aggregate
-transition; the workflow persists its snapshot and schedules its UI effect as
-normal queue advancement continues. The processor's completion event covers the
-published slot from launch through normal completion, successor publication,
-and pre-run recovery, so terminal workflow close cannot release delivery while
-cleanup is still active. A failed aggregate-completion callback releases its
-finished task slot, records the failure, and hands it to the terminal waiter
-exactly once; a failed close therefore retains the workflow for reconciliation
-instead of hanging on ownership that no longer exists.
-[messaging/trees/node.py](src/free_claude_code/messaging/trees/node.py) owns
-`MessageNode` and `MessageState`; each node keeps only the copied scope and
-prompt needed by the aggregate rather than retaining a mutable ingress value,
-[messaging/trees/graph.py](src/free_claude_code/messaging/trees/graph.py) owns parent/child and
-status-message lookup state, and
-[messaging/trees/snapshot.py](src/free_claude_code/messaging/trees/snapshot.py) owns typed persisted
-conversation snapshots. New snapshots serialize scoped trees as a list, while
-loading derives scope from existing pre-scope `sessions.json` tree roots. Nodes
-persist logical and exact-reference parent relations; runtime child indexes are
-rebuilt on restore, and transport ingress payloads do not leak into aggregate
-storage. Old snapshots without an exact parent reference attach conservatively
-to the logical parent prompt. A cleared optional status is valid only for an
-inert node; runnable restored nodes must still have a status.
-A malformed tree carrying neither current scope nor legacy root ingress is
-reported and skipped because assigning it to an inferred chat would violate the
-same ownership boundary.
-
-[messaging/session/](src/free_claude_code/messaging/session/) persists typed conversation snapshots
-and message IDs to a JSON file under the managed messaging state directory.
-`SessionStore` reads existing `sessions.json` files but exposes typed snapshot
-APIs to runtime code and deep-copies snapshot ingress and egress so no caller
-shares mutable persisted state. Debounced atomic writes live in
-[messaging/session/persistence.py](src/free_claude_code/messaging/session/persistence.py). One writer
-lock serializes physical replaces, and a generation check under that lock
-prevents an older timer snapshot from landing after a newer flush or clear.
-Timer-triggered saves are best effort and leave the store dirty on failure;
-explicit flushes and authoritative writes propagate failure while preserving
-that dirty state for retry. Successful retry writes the current in-memory
-snapshot and is the only operation that marks it clean.
-Standalone `/clear` detaches and drains only the invoking scope, then writes an
-authoritative scoped removal while other chats remain intact. Per-chat deletion
-ownership lives in
-[messaging/session/managed_message_log.py](src/free_claude_code/messaging/session/managed_message_log.py).
-The registry accepts managed inbound prompts, voice notes, and commands as well
-as FCC output. It migrates legacy `message_log` entries and persists the final
-shape as `managed_messages`. Startup notices use the same registry. An incoming
-standalone `/clear` defers insertion because the command handler already owns its
-ID on success; this prevents the command from evicting an older deletion target
-when an explicit cap is configured. Failed or cancelled clear attempts record
-the command before propagating so a later clear can discover it.
-
-`/clear` commits FCC state cleanup first and then best-effort deletes the exact
-authorized message-ID set through the list-based outbound port. Standalone clear
-deletes every tracked user and FCC message in its chat; reply clear deletes only
-the selected literal reply subtree plus its command. Discord/Telegram can still
-reject individual deletions for platform reasons such as permissions, age, or
-missing messages; such failures never restore cleared FCC state.
-
-```mermaid
-sequenceDiagram
- participant Runtime as DiscordOrTelegramRuntime
- participant Outbound as OutboundMessenger
- participant Workflow as MessagingWorkflow
- participant Intake as MessagingTurnIntake
- participant Queue as TreeQueueManager
- participant Runner as MessagingNodeRunner
- participant Manager as ManagedClaudeSessionManager
- participant CLI as ClaudeCode
- participant Proxy as LocalProxy
-
- Runtime->>Workflow: IncomingMessage
- Workflow->>Intake: handle inbound turn
- Intake->>Queue: create or extend message tree
- Queue->>Runner: process node in order
- Runner->>Manager: get_or_create_session
- Manager->>CLI: launch JSON stream task
- CLI->>Proxy: provider-backed API calls
- CLI-->>Runner: parsed stdout events
- Runner-->>Outbound: status and transcript updates
-```
-
-## Observability, Diagnostics, And Safety
-
-[core/trace.py](src/free_claude_code/core/trace.py) emits structured trace events across stages such
-as ingress, routing, provider, egress, messaging, and client CLI execution. Trace
-payloads are intended to connect API, provider, CLI, and messaging activity
-without requiring raw transport logs by default.
-
-Logging defaults are conservative:
-
-- The JSON file sink defaults to `INFO`. Detailed structured request traces use
- `DEBUG`, so normal customer logs retain lifecycle and failure events without
- recording request-by-request trace payloads.
-- The active server log rotates at 50 MB and retains five rotated files,
- bounding normal on-disk usage to roughly 300 MB.
-- API payloads and SSE events are not logged raw unless explicitly enabled.
-- Provider and application errors log metadata by default; verbose traceback and
- message logging are opt-in.
-- Messaging text, transcription previews, CLI diagnostics, and detailed
- messaging exception strings are controlled by separate diagnostic flags.
-- Process logging, server/managed-CLI authentication, and messaging diagnostics
- are captured by their lifecycle owners at construction. Admin marks those
- settings restart-required so an Apply cannot report success while an existing
- runtime continues using stale security or privacy policy.
-- Values under keys that look like API keys, authorization, tokens, or secrets
- are redacted by trace helpers where structured traces are emitted.
-
-Important safety boundaries:
-
-- Admin UI and admin APIs are loopback-only.
-- Proxy API auth is controlled by `ANTHROPIC_AUTH_TOKEN`.
-- `web_fetch` egress defaults to configured URL schemes and blocks private
- network targets unless explicitly allowed.
-- Local provider URLs are user-configurable, but local-provider status checks are
- exposed only through the local admin API.
-
-## Testing And CI Strategy
-
-Deterministic tests live under [tests/](tests/). They cover API routes, config,
-provider conversion, upstream adapters, streaming contracts, messaging, CLI
-adapters, import boundaries, provider catalog contracts, and other invariants.
-The import-boundary contract derives every static production edge with one AST
-scanner and checks the package matrix, exact exceptions, facade ownership, and
-lazy optional imports. The resulting first-party module graph must remain
-acyclic. The same contract rejects untyped provider collaborators and private
-provider access from helper modules. These tests protect current architectural
-properties rather than preserving deleted modules or an exact internal file
-layout.
-
-Rendered Admin workflows live separately under [e2e/](e2e/). They use the
-official Python Playwright pytest plugin with headless Chromium, a temporary FCC
-home, fake providers, deterministic local probes, and a real loopback FastAPI
-server on an OS-assigned port. The suite proves scrolling, focus, responsive
-layout, configuration-versus-check state separation, model-option updates, and
-credential redaction without reading developer configuration or contacting an
-upstream service. Browser traces and full-page screenshots are retained only on
-failure.
-
-Live and local product tests live under [smoke/](smoke/). See
-[smoke/README.md](smoke/README.md) for target taxonomy, environment variables,
-failure classes, and examples. Smoke tests can launch subprocesses, call real
-providers, touch local model servers, and optionally send bot messages.
-
-CI is defined in [.github/workflows/tests.yml](.github/workflows/tests.yml). It
-enforces:
-
-- `Ban suppressions and legacy annotations`;
-- `ruff-format`;
-- `ruff-check`;
-- `ty`;
-- `pytest`;
-- `playwright`.
-
-Contributor verification commands:
-
-```powershell
-uv run ruff format
-uv run ruff check
-uv run ty check
-uv run pytest
-uv run playwright install chromium
-uv run pytest e2e -n 0
+| [settings.py](src/free_claude_code/config/settings.py) | Pure Pydantic types, defaults, normalization and cross-field validation |
+| [loader.py](src/free_claude_code/config/loader.py) | Source precedence, provenance, public settings cache |
+| [env_migrations.py](src/free_claude_code/config/env_migrations.py) | Locked, atomic consolidation of legacy configuration |
+| [paths.py](src/free_claude_code/config/paths.py) | Managed configuration, auth, logs, catalogs, Chat and messaging paths |
+| [config/admin](src/free_claude_code/config/admin/) | Catalog-driven fields, presentation, validation and sparse persistence |
+| [runtime/application.py](src/free_claude_code/runtime/application.py) | Credential checks, Apply publication/restart decisions and account operations |
+
+Live precedence is defaults, managed `~/.fcc/.env`, then process environment.
+The deliberate exception is a non-empty managed `ANTHROPIC_AUTH_TOKEN`, which
+wins over an inherited token. Settings loading may perform the one-time legacy
+migration; after consolidation, checkout env files and `FCC_ENV_FILE` are not
+live sources. [.env.example](.env.example) is documentation only.
+
+Admin updates are sparse: omission preserves values, optional-field removal is
+explicit, and masked/blank secret submissions mean unchanged. Process-owned
+fields are shown as locked. Provider fields derive from catalog metadata;
+new settings must distinguish hot-apply, restart-required, and session-sensitive
+behavior according to their runtime owners.
+
+Apply validates prospective settings and checks edited API keys through
+[credential_validation.py](src/free_claude_code/providers/credential_validation.py).
+Checks use documented non-generating authenticated endpoints and return
+`verified`, `rejected`, or `unverified`. Proven rejection blocks Apply;
+unsupported probes and inconclusive network failures are not proof of a bad
+key. Accepted changes either replace a provider generation or follow the runtime
+restart path. Configuration readiness, live provider checks, and discovery are
+separate states.
+
+Authentication is defined in
+[api/dependencies.py](src/free_claude_code/api/dependencies.py):
+
+- `PROXY_AUTH_ENABLED` controls enforcement; `ANTHROPIC_AUTH_TOKEN` is the
+ retained non-empty credential. Disabling enforcement does not erase it.
+- Responses and model-list routes use bearer authorization.
+- Anthropic Messages/token-count routes accept bearer authorization or, only
+ when Authorization is absent, the proxy token in `x-api-key`. An invalid
+ Authorization header does not fall through to `x-api-key`.
+- Token comparison is constant-time.
+- [Admin security](src/free_claude_code/api/admin_security.py) independently
+ requires a loopback client, local Host authority, and a local Origin when
+ supplied. It covers configuration and Chat surfaces.
+
+See [config tests](tests/config/), [auth tests](tests/api/test_auth.py),
+[credential tests](tests/providers/test_credential_validation.py), and
+[Admin tests](tests/api/test_admin.py).
+
+## Chat Sessions
+
+Chat is a separate local product surface that calls the shared application
+executor directly; it does not launch a coding agent or call FCC over loopback
+HTTP. The composition root injects provider-runtime and storage ports.
+
+| Owner | Responsibility |
+| --- | --- |
+| [application/chat/service.py](src/free_claude_code/application/chat/service.py) | Session commands, one active operation per session, generation/compaction, cancellation and terminal settlement |
+| [application/chat/context.py](src/free_claude_code/application/chat/context.py) | Model options, context estimation, transcript construction and compaction budgets |
+| [application/chat/events.py](src/free_claude_code/application/chat/events.py) | Bounded operation event subscriptions |
+| [application/chat/ports.py](src/free_claude_code/application/chat/ports.py) | Application-owned storage/subscription interfaces |
+| [runtime/chat_sqlite.py](src/free_claude_code/runtime/chat_sqlite.py) | SQLite implementation, transactions, revisions, schema handling and restart repair |
+| [api/chat_routes.py](src/free_claude_code/api/chat_routes.py) | Loopback HTTP commands, snapshots and SSE feed |
+| [Admin static assets](src/free_claude_code/api/admin_static/) | Browser session UI; [chat_markdown.py](src/free_claude_code/api/chat_markdown.py) renders response Markdown |
+
+Send/retry/regenerate/compact operations validate revisions and retain a provider
+lease while work runs. Chat uses the same Messages execution/fallback pipeline.
+Context handling includes proactive/manual compaction and bounded reactive
+recovery from context-window exhaustion. Mixed fallback failures do not become
+an unconditional compaction retry.
+
+Mutations and terminal publication must agree with durable state. Stop, delete,
+and shutdown retain operation ownership until settlement finishes; a late
+cancellation cannot downgrade an already committed completion. Browser event-feed
+disconnect only closes its subscription, not the active generation. Overflow
+requests a resync from authoritative snapshots.
+
+SQLite lives under `~/.fcc/chat/` with an exclusive process lock, short
+thread-backed transactions, and WAL. Startup handles supported schema state,
+removes unpublished generations, and marks visible unfinished generations
+interrupted. A storage startup failure leaves Chat unavailable while allowing
+the inference gateway to start.
+
+See [Chat service tests](tests/application/test_chat_service.py),
+[storage tests](tests/runtime/test_chat_sqlite.py),
+[Chat API tests](tests/api/test_chat_routes.py), and
+[browser tests](e2e/test_chat_sessions.py).
+
+## Client Launchers And Messaging
+
+[cli/launchers](src/free_claude_code/cli/launchers/) owns client-specific model
+projection, argument handling, credential isolation and temporary configuration.
+The shared [model catalog adapter](src/free_claude_code/cli/launchers/model_catalog.py)
+consumes direct Messages/Responses views; the API owns routable wire identity.
+Native client configuration and credentials remain client-owned. Pass-through
+commands and unsupported persistent/background modes are decided by each
+launcher and covered under [tests/cli](tests/cli/).
+
+[cli/local_http.py](src/free_claude_code/cli/local_http.py) bypasses forward
+proxies for local FCC health/catalog calls and adds FCC/loopback hosts to child
+`NO_PROXY` settings while retaining outbound proxy configuration.
+[cli/claude_env.py](src/free_claude_code/cli/claude_env.py) owns the shared Claude
+environment. Codex's launcher owns its generated catalog and command-backed proxy
+authentication.
+
+[Aider](src/free_claude_code/cli/launchers/aider.py) projects the Messages catalog
+into temporary model-settings/metadata files. Its model names use Aider's
+Anthropic transport, and the real proxy token is carried through a unique child
+environment variable. The launcher rejects route-file overrides that would
+replace its FCC overlay.
+
+Messaging follows a different path:
+
+```text
+Discord/Telegram ingress → workflow/turn intake → scoped tree queue
+ → node runner → managed Claude CLI → FCC inference API
+ → CLI event parser → transcript renderer → platform outbox
```
-For docs-only architecture changes, a source-link and accuracy review is usually
-sufficient. Full CI can still be run when the doc accompanies runtime changes or
-when maintainers want branch-level assurance.
-
-## Extension Checklists
-
-### Add An Admin Setting
-
-1. Add or expose the setting in [config/settings.py](src/free_claude_code/config/settings.py).
-2. Add the template key to [.env.example](.env.example) if users configure it.
-3. Add a `ConfigFieldSpec` under [config/admin/](src/free_claude_code/config/admin/), or add
- provider catalog metadata when the setting is provider credential, configurable base URL,
- proxy, or display-name metadata.
-4. Mark `restart_required` or `session_sensitive` when runtime state cannot be
- updated in place.
-5. Add tests under [tests/api/](tests/api/) or [tests/config/](tests/config/).
-
-### Add Or Change A Client Surface
-
-1. For an installed wrapper, add or update a launcher under
- [cli/launchers/](src/free_claude_code/cli/launchers/) and keep credential stripping local to that
- client.
-2. For messaging-managed execution, update [cli/managed/](src/free_claude_code/cli/managed/) only
- when Discord or Telegram should actually run a different managed client.
-3. Ensure managed task parsing emits the event shapes expected by
- [messaging/event_parser.py](src/free_claude_code/messaging/event_parser.py) and
- [messaging/node_event_pipeline.py](src/free_claude_code/messaging/node_event_pipeline.py).
-4. Add launcher, managed-session, and customer-flow tests under
- [tests/cli/](tests/cli/) and [tests/messaging/](tests/messaging/).
-
-### Add A Messaging Platform
-
-1. Implement a `MessagingRuntime`, `OutboundMessenger`, and inbound normalizer
- under [messaging/platforms/](src/free_claude_code/messaging/platforms/).
-2. Reuse [messaging/platforms/outbox.py](src/free_claude_code/messaging/platforms/outbox.py) for
- queued outbound delivery and
- [messaging/platforms/voice_flow.py](src/free_claude_code/messaging/platforms/voice_flow.py) for
- voice-note handoff when the platform supports audio.
-3. Add construction logic to
- [messaging/platforms/factory.py](src/free_claude_code/messaging/platforms/factory.py).
-4. Add settings and admin fields for tokens, allowlists, and platform-specific
- runtime options.
-5. Add rendering profile support in
- [messaging/rendering/profiles.py](src/free_claude_code/messaging/rendering/profiles.py) if needed.
-6. Add deterministic runtime/outbound/workflow tests and optional live smoke
- targets.
-
-### Add Protocol Behavior
-
-1. Put shared Anthropic behavior under [src/free_claude_code/core/anthropic/](src/free_claude_code/core/anthropic/).
-2. Put OpenAI Responses behavior under
- [src/free_claude_code/core/openai_responses/](src/free_claude_code/core/openai_responses/).
-3. Keep provider-specific request quirks inside the provider profile or specialized
- provider subclass.
-4. Add stream contract tests under [tests/contracts/](tests/contracts/) or
- [tests/core/](tests/core/) when event shape or ordering changes.
-5. Add provider tests when the behavior changes upstream request or response
- handling.
-
-## Maintenance Rules For This Document
-
-Update this file when a change adds or meaningfully changes:
-
-- a top-level package or installable runtime boundary;
-- a public route or wire protocol;
-- startup, shutdown, or resource ownership;
-- configuration precedence or managed config behavior;
-- provider runtime, catalog, or upstream-adapter architecture;
-- model routing or reasoning behavior;
-- CLI adapter behavior;
-- messaging platform behavior;
-- protocol conversion or streaming contracts;
-- CI, smoke, or verification strategy.
-
-Docs-only changes to this file do not require a semver bump. Production code
-changes still follow the versioning rules in [AGENTS.md](AGENTS.md) and
-[CLAUDE.md](CLAUDE.md).
-
+[ApplicationRuntime](src/free_claude_code/runtime/application.py) wires the
+platform, [MessagingWorkflow](src/free_claude_code/messaging/workflow.py),
+transcriber and [managed session manager](src/free_claude_code/cli/managed/manager.py).
+The platform adapters depend on SDKs; workflow code consumes normalized messages
+and platform-neutral ports.
+
+[Turn intake](src/free_claude_code/messaging/turn_intake.py) handles commands and
+admission; [node runner](src/free_claude_code/messaging/node_runner.py) owns CLI
+work; [trees](src/free_claude_code/messaging/trees/) encapsulates aggregates,
+claims, queues and task ownership. Identity includes platform and chat scope.
+Opaque execution claims prevent stale runners from mutating cleared or
+re-admitted branches. Reply references distinguish logical session ancestry from
+the exact prompt/status being replied to.
+
+Global stop, scoped clear, and reply-scoped operations have different boundaries.
+State detachment/cancellation and persistence complete before best-effort platform
+deletion; platform failures never restore cleared state.
+[Session persistence](src/free_claude_code/messaging/session/) uses typed
+snapshots and serialized atomic writes. Explicit flush failures remain retryable.
+
+[Platform outbox](src/free_claude_code/messaging/platforms/outbox.py) owns queued
+delivery with the runtime's limiter.
+[Voice flow](src/free_claude_code/messaging/platforms/voice_flow.py) and
+[voice claims](src/free_claude_code/messaging/voice.py) own transcription handoff,
+scoped cancellation and temporary-file cleanup. Thread-backed transcription must
+finish before its resources are released. Bootstrap selects local Whisper or the
+NIM transcriber; messaging never constructs provider adapters.
+
+See [messaging tests](tests/messaging/) for scope, reply-tree, persistence, voice,
+delivery and shutdown contracts.
+
+## Local Tools And Diagnostics
+
+[Messages optimizations](src/free_claude_code/api/optimization_handlers.py) handle
+configured quota probes, command-prefix detection, titles, suggestions and
+filepaths locally. Claude safety-classifier handling is a Messages routing policy:
+it adjusts recognized classifier requests and reasoning; it does not fabricate
+a verdict.
+
+[api/web_tools](src/free_claude_code/api/web_tools/) owns supported Anthropic
+server-tool compatibility. Forced search/fetch can run locally; the supported
+automatic-search shape buffers a normal provider decision before emitting local
+search results. Other hosted-tool shapes are rejected before upstream execution.
+[Web-fetch egress policy](src/free_claude_code/api/web_tools/egress.py) owns allowed
+schemes and private-network restrictions.
+
+[core/trace.py](src/free_claude_code/core/trace.py) carries request correlation
+across layers; [diagnostics](src/free_claude_code/core/diagnostics.py) redacts
+credentials and bounds error detail.
+[Logging configuration](src/free_claude_code/config/logging_config.py) owns file
+rotation/retention. Raw API payloads, detailed errors and messaging content are
+opt-in diagnostics. Construction-time security/logging settings require restart
+when their existing owners cannot be updated safely.
+
+## Verification And Extension Map
+
+| Change area | Primary code | Relevant verification |
+| --- | --- | --- |
+| Provider | Catalog/settings, OpenAI Chat profile or specialized adapter, runtime factory | [Provider tests](tests/providers/), [catalog contracts](tests/contracts/test_provider_catalog_order.py), targeted provider smoke |
+| Protocol | `core/anthropic`, `core/openai_responses`, transport presenters | [Protocol matrix](tests/contracts/test_protocol_matrix.py), [stream contracts](tests/contracts/test_stream_contracts.py), API failure/response tests |
+| Setting/Admin | Settings, catalog/generated manifest, Apply owner, browser assets | [Config](tests/config/), [Admin API](tests/api/test_admin.py), [e2e](e2e/) |
+| Chat | Application service/context/ports, SQLite, Chat routes/assets | [Application](tests/application/), [SQLite](tests/runtime/test_chat_sqlite.py), [Chat e2e](e2e/test_chat_sessions.py) |
+| Client/install | Launcher/config projection, entrypoints, installer/uninstaller | [CLI](tests/cli/), [scripts](tests/scripts/), [packaging](tests/contracts/test_packaging_contracts.py) |
+| Messaging | Platform ports, workflow/trees, runner/rendering, persistence | [Messaging](tests/messaging/), targeted product smoke |
+| Lifecycle | Runtime, provider manager, HTTP lifetime/response owner | [Runtime](tests/runtime/), [request lifetime](tests/api/test_request_lifetime.py), [response streams](tests/api/test_response_streams.py) |
+
+New provider settings feed the catalog-driven Admin manifest where possible.
+New clients need launcher/packaging coverage; messaging-managed support is a
+separate integration. Shared protocol behavior belongs in core, while provider
+quirks stay with their adapter. New imports must satisfy the dependency contract.
+Tests protect user behavior and ownership invariants, not obsolete internal
+module layouts.
+
+[tests](tests/) is the deterministic suite.
+[e2e](e2e/) runs real browser interactions against isolated local state and fake
+providers. [smoke](smoke/README.md) separates prerequisite probes from product
+scenarios and documents live-service opt-ins; a liveness probe is not proof that
+a complete client/tool workflow works.
+
+Runtime release identity comes from installed distribution metadata through
+[core/version.py](src/free_claude_code/core/version.py), not by parsing project
+files or duplicating version literals.
+
+Local CI is [scripts/ci.ps1](scripts/ci.ps1) on Windows or
+[scripts/ci.sh](scripts/ci.sh) on macOS/Linux. Both cover suppression policy,
+Ruff formatting/lint, ty, pytest and Playwright. Local Ruff runs repair code;
+[GitHub CI](.github/workflows/tests.yml) runs check-only Ruff and requires all
+six checks. See [AGENTS.md](AGENTS.md) for commands and subset/dry-run flags.
+The trusted dependency-cache workflow populates caches, not validation results.
+
+Update this map when public surfaces, package boundaries, ownership, lifecycle,
+configuration or extension paths change. Documentation-only updates need source
+accuracy/link checks and do not require a release bump; production changes follow
+the versioning rules in the identical instruction files.
diff --git a/CLAUDE.md b/CLAUDE.md
index 9e7fae7b..c768452e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,109 +1,126 @@
-# AGENTIC DIRECTIVE
-
-> Keep AGENTS.md and CLAUDE.md identical.
-
-## CODING ENVIRONMENT
-
-- Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
-- Install Python 3.14.0 stable using `uv python install 3.14.0` if not already installed (requires uv >=0.9; see `[tool.uv] required-version` in `pyproject.toml`)
-- Always use `uv run` to run files instead of the global `python` command.
-- Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
-- Read `.env.example` for environment variables.
-- All CI checks must pass; failing checks block merge.
-- Add tests for new changes (including edge cases).
-- Before pushing, prefer `./scripts/ci.sh` (macOS/Linux) or `.\scripts\ci.ps1` (Windows) to run the local CI sequence; requires `uv` on PATH. The local scripts run Ruff in repair mode (`ruff format`, then `ruff check --fix`) before type checking and tests.
-- Use `--only` / `--skip` (PowerShell: `-Only` / `-Skip`) to run a subset when iterating; use `--dry-run` to print commands without running them.
-- GitHub CI remains check-only for Ruff (`ruff format --check`, `ruff check`) so branch protection verifies committed code.
-- Fall back to individual repair commands when debugging local failures: `uv run ruff format`, `uv run ruff check --fix`, `uv run ty check`, `uv run pytest -v --tb=short`. Use GitHub-style checks only when verifying enforcement locally: `uv run ruff format --check`, `uv run ruff check`.
-- Do not add `# type: ignore` or `# ty: ignore`; fix the underlying type issue.
-- Do not add `from __future__ import annotations`; Python 3.14 native lazy annotations are the project standard.
-- All 6 check IDs are represented in `scripts/ci.sh` / `scripts/ci.ps1` and enforced by `tests.yml` before each merge (parallel jobs: suppression grep, ruff-format, ruff-check, ty, pytest, playwright).
-- Deterministic rendered Admin UI interactions live under `e2e/` and run separately from ordinary pytest. Install Chromium once with `uv run playwright install chromium`; API and unit contracts remain under `tests/`.
-- GitHub CI runs for every pull request, including stacked PRs targeting non-`main` branches. Head updates trigger fresh checks; strict required checks keep PRs targeting `main` current with `main`, so the tested PR tree is the tree squash-merged without a duplicate post-merge run.
-- A separate trusted `Dependency Cache` workflow runs after pushes to `main` only and is the sole writer for reusable Python and uv dependency caches. Pull-request jobs only restore caches; the maintenance workflow never reruns validation and is not a required status check.
-- Repository protection should use rulesets: a non-bypassable main integrity ruleset requires pull requests and strict required checks, keeps branches current, and blocks direct/force pushes to `main`; a separate review ruleset may allow `Alishahryar1`/admins to bypass review only.
-- Required status checks: set **required status checks** to **all** of those statuses (e.g. **Ban suppressions and legacy annotations**, **ruff-format**, **ruff-check**, **ty**, **pytest**, **playwright**—use the exact labels GitHub shows, which may be prefixed with **CI /**). Remove **ci** from required checks if it was previously added for the old gate job.
-
-## IDENTITY & CONTEXT
-
-- You are an expert Software Architect and Systems Engineer.
-- Goal: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush.
-- Code: Write the simplest code possible. Keep the codebase minimal and modular.
-
-## ARCHITECTURE PRINCIPLES
-
-- **Shared utilities**: Put shared Anthropic protocol logic in neutral `src/free_claude_code/core/anthropic/` modules. Do not have one provider import from another provider's utils.
-- **Failure ownership**: Keep canonical failure semantics and redaction SDK-free in `core/`; providers alone classify SDK/HTTP failures and own retries; protocol/API adapters alone choose wire error types and commit-boundary serialization.
-- **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
-- **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
-- **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
-- **Model-independent reasoning**: Resolve client reasoning intent once at the application boundary; provider adapters translate documented provider capabilities. Never branch on upstream model names or versions to choose reasoning behavior.
-- **Dead code**: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. `settings.provider_type` not `"nvidia_nim"`).
-- **Performance**: Use list accumulation for strings (not `+=` in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
-- **Platform-agnostic naming**: Use generic names (e.g. `PLATFORM_EDIT`) not platform-specific ones (e.g. `TELEGRAM_EDIT`) in shared code.
-- **Precise types**: Avoid `typing.Any`. Use owner-defined domain types for known values, `JsonValue`/`JsonObject` for JSON, and `object` only at genuinely opaque boundaries where the value is narrowed before use. Enforce this through design review and type checking, not a mechanical text ban in CI.
-- **No type ignores**: Do not add `# type: ignore` or `# ty: ignore`. Fix the underlying type issue.
-- **Python 3.14 annotations**: Do not use `from __future__ import annotations`; rely on native lazy annotations and fix circular import boundaries instead of hiding them with annotation stringization.
-- **Imports**: Prefer top-level imports. Avoid `TYPE_CHECKING` and local imports for first-party or required dependencies; if a top-level import creates a cycle, move shared types/protocols to a neutral owner.
-- **Complete migrations**: When moving modules, update imports to the new owner and remove old compatibility shims in the same change unless preserving a published interface is explicitly required.
-- **Maximum Test Coverage**: There should be maximum test coverage for everything, preferably live smoke test coverage to catch bugs early
-
-## COGNITIVE WORKFLOW
-
-1. **ANALYZE**: Read relevant files. Do not guess.
-2. **PLAN**: Map out the logic. Identify root cause or required changes. Order changes by dependency.
-3. **EXECUTE**: Fix the cause, not the symptom. Execute incrementally with clear commits.
-4. **VERIFY**: Run `./scripts/ci.sh` or `.\scripts\ci.ps1`, plus relevant smoke tests when needed. Confirm the fix via logs or output.
-5. **SPECIFICITY**: Do exactly as much as asked; nothing more, nothing less.
-6. **PROPAGATION**: Changes impact multiple files; propagate updates correctly.
-7. **VERSION**: If the commit touches production files on `main`, bump semver in the same commit (see [Versioning](#versioning-main)).
-
-## VERSIONING (MAIN)
-
-Every commit on `main` that changes a **production file** must include a semver bump in **`pyproject.toml`** in the **same commit**. Do not merge or push prod changes without updating the version.
-
-### Production files
-
-These paths count as production (runtime, packaging, or install surface):
-
-- `src/free_claude_code/api/`, `src/free_claude_code/cli/`, `src/free_claude_code/config/`, `src/free_claude_code/core/`, `src/free_claude_code/messaging/`, `src/free_claude_code/providers/`
-- `src/free_claude_code/application/`
-- `.env.example`
-- `pyproject.toml` (dependencies, scripts, packaging)
-- `scripts/install.sh`, `scripts/install.ps1`, `scripts/uninstall.sh`, `scripts/uninstall.ps1`, `scripts/ci.sh`, `scripts/ci.ps1`
-
-These do **not** require a version bump on their own:
-
-- `tests/`, `smoke/`
-- Docs and assets: `README.md`, `assets/`, `AGENTS.md`, `CLAUDE.md`
-- CI and repo config: `.github/`, `.gitignore`
-
-If a single commit mixes production and non-production edits, still bump the version.
-
-### Semver rules
-
-Use `[project].version` as `MAJOR.MINOR.PATCH`:
-
-- **PATCH** (`x.y.Z+1`): bug fixes, refactors with no user-visible behavior change, dependency updates, packaging/install fixes.
-- **MINOR** (`x.Y+1.0`): backward-compatible features—new providers, admin fields, CLI commands, config options, or behavior additions.
-- **MAJOR** (`X+1.0.0`): breaking changes—removed or renamed env vars, incompatible API/CLI/default changes, or migrations users must act on.
-
-When unsure between PATCH and MINOR, prefer PATCH for fixes and MINOR for new capability.
-
-### Required steps
-
-1. Classify the change and choose the bump level.
-2. Update `version` in `pyproject.toml`.
-3. Run `uv lock` so `uv.lock` reflects the new package version.
-4. Include the version and lockfile updates in the same commit as the production change.
-
-Example commit on `main` after a packaging fix: bump `1.2.38` → `1.2.39`, run `uv lock`, commit together with the fix.
-
-## SUMMARY STANDARDS
-
-- Summaries must be technical and granular.
-- Include: [Files Changed], [Logic Altered], [Verification Method], [Residual Risks] (if no residual risks then say none).
-
-## TOOLS
-
-- Prefer built-in tools (grep, read_file, etc.) over manual workflows. Check tool availability before use.
+# FCC Development Instructions
+
+Keep `AGENTS.md` and `CLAUDE.md` byte-for-byte identical.
+
+Free Claude Code is a local Python gateway connecting coding agents to configured
+AI providers. Read [ARCHITECTURE.md](ARCHITECTURE.md) for ownership and request
+flows, [README.md](README.md) for user workflows, and [.env.example](.env.example)
+for documented settings.
+
+## Tooling
+
+- Commands assume the repository root. Unrelated edits and untracked files are
+ outside the change scope; use `git ls-files` for tracked paths and `rg` for search.
+- Use `uv` for Python environments and `uv run` for Python tools/scripts. Follow
+ [.python-version](.python-version), `[tool.uv]` in [pyproject.toml](pyproject.toml),
+ and [uv.lock](uv.lock). Install missing prerequisites as needed; do not upgrade
+ tools or dependencies during unrelated work.
+- `uv sync --locked` prepares the development environment. Optional voice extras
+ are needed only for the corresponding live transcription work.
+- Never use the real `~/.fcc/` configuration, credentials, chat database, or
+ messaging state as disposable test fixtures. Use isolated temporary state.
+
+| Task | Command |
+| --- | --- |
+| Focused deterministic tests | `uv run pytest tests/<area>/test_<feature>.py -n 0 -q` |
+| Format / lint repair | `uv run ruff format <changed-paths>`; `uv run ruff check --fix <changed-paths>` |
+| Read-only format / lint checks | `uv run ruff format --check`; `uv run ruff check` |
+| Type checking | `uv run ty check` |
+| Full deterministic tests | `uv run pytest -v --tb=short` |
+| Browser setup / tests | `uv run playwright install chromium`; `uv run pytest e2e -n 0 -v --tb=short` |
+| Full local CI | Windows: `.\scripts\ci.ps1`; macOS/Linux: `./scripts/ci.sh` |
+
+Use full local CI before pushing code. The scripts run Ruff in repair mode
+before type checking and tests; review their diff. Use PowerShell
+`-Only` / `-Skip` / `-DryRun` or shell `--only` /
+`--skip` / `--dry-run` when iterating. Check IDs are `suppressions`,
+`ruff-format`, `ruff-check`, `ty`, `pytest`, and `playwright`.
+
+## Ownership And Contracts
+
+- `runtime/` composes services and owns process lifecycle and provider generations.
+ `api/` owns HTTP validation, authentication, product handlers, and response
+ commitment. `application/` owns routing, reasoning intent, model fallback, and
+ Chat use cases. Keep these responsibilities separate.
+- `core/` owns shared protocol models/conversion, failure semantics, and redaction.
+ `providers/` alone classifies SDK/HTTP failures and owns upstream attempts,
+ retries, and recovery. Protocol/API boundaries choose wire errors.
+- Provider metadata belongs in `config/provider_catalog.py`; ordinary upstream
+ differences belong in OpenAI Chat profiles. Add a specialized adapter only for
+ behavior/state a profile cannot express. Keep provider-only settings out of
+ shared `ProviderConfig`.
+- Resolve reasoning intent at the application boundary. Providers encode supported
+ controls; never infer reasoning behavior from upstream model names/versions.
+ Keep reasoning replay distinct from controls for the next generation.
+- Preserve each ingress protocol through the application boundary and the four
+ ingress/upstream cells. Do not introduce a lossy universal request model.
+ Preserve tool identity, call/result pairing, images, reasoning, usage, and
+ event order; reject unrepresentable input instead of silently dropping it.
+- Preserve stream commitment and resource ownership: no model fallback after
+ output commits, no duplicate terminal events, and no lease release before its
+ response/stream closes. Cancellation must drain owned work; shutdown must not
+ abandon partially closed resources or overlap replacement runtimes.
+- Keep config loading/provenance in `config/loader.py`, sparse Admin persistence
+ in `config/admin/`, and runtime Apply in `runtime/application.py`. The managed
+ `~/.fcc/.env` is the live file; repository `.env.example` is documentation.
+- Keep Chat revisions, operation settlement, and durable state consistent.
+ Messaging identities include platform/chat scope; stale tasks must not revive
+ cleared branches. Launchers own temporary client overlays, not native user
+ credentials/configuration.
+- Follow the exact dependency/facade policy in
+ [test_import_boundaries.py](tests/contracts/test_import_boundaries.py).
+ Change allowed edges deliberately, never just to silence a failing contract.
+
+## Python And Design
+
+- Use Python 3.14 native annotations. Do not add
+ `from __future__ import annotations`, `# type: ignore`, or `# ty: ignore`.
+- Use owner-defined types; `JsonValue`/`JsonObject` for JSON; narrowed `object`
+ only at opaque boundaries. Avoid `typing.Any`; fix the underlying model.
+- Prefer top-level imports. Resolve cycles through ownership, not
+ `TYPE_CHECKING` or annotation stringization. Preserve deliberate lazy loading
+ at existing optional-dependency, provider-factory, and lightweight CLI owners.
+- Prefer simple composition and shared helpers over duplicated behavior or
+ unnecessary base classes. Use public operations rather than another object's
+ private mutable state; keep platform/provider quirks at their adapters.
+
+## Verification By Change
+
+Changed behavior needs regression coverage, including relevant failure paths.
+
+| Change | Required evidence |
+| --- | --- |
+| Protocol/provider | Relevant core/provider tests; matrix/stream contracts for conversion or event changes |
+| Routing/lifecycle/failure | Application/API/runtime tests, including fallback, disconnect, cancellation, and cleanup paths affected |
+| Settings/Admin | Config/API contracts; deterministic `e2e/` tests for changed browser interactions |
+| Chat/messaging | Persistence, revision/scope isolation, concurrency, and stop/clear tests affected |
+| CLI/install/packaging | Launcher/script/packaging contracts; relevant installed-client smoke when needed |
+| Documentation only | Source accuracy, local links, instruction-file equality, and scoped `git diff --check` |
+
+Live checks are under [smoke/](smoke/README.md), separate from deterministic CI.
+Use `FCC_LIVE_SMOKE=1` and targeted `FCC_SMOKE_TARGETS` only for the relevant
+configured services; prerequisites alone do not prove product behavior. Live
+checks can consume quota or send/delete bot messages: use only authorized
+targets and report skips or missing prerequisites accurately.
+
+GitHub's [CI workflow](.github/workflows/tests.yml) runs Ruff in check-only mode
+and enforces all six checks; failing required checks block merge. The
+dependency-cache workflow is not a validation substitute.
+
+## Versioning And Documentation
+
+Every commit merged to `main` that changes production files must include a semver
+bump in `pyproject.toml` and the matching
+`uv lock` update. Production includes all installed code/assets under
+`src/free_claude_code/` (including `runtime/`), `.env.example`, runtime/dependency/
+packaging metadata, and install/uninstall/CI scripts.
+
+Use **PATCH** for fixes/refactors/dependency or packaging updates, **MINOR** for
+backward-compatible capabilities, and **MAJOR** for breaking API/CLI/configuration
+changes. Docs, tests, smoke tests, and repository workflow changes alone do not
+require a bump.
+
+Update `ARCHITECTURE.md` when ownership, public protocols, lifecycle, configuration,
+or extension paths change; update `README.md` and `.env.example` for user-facing
+setup/configuration changes. Keep volatile defaults and catalogs in their source
+owners, and keep these two instruction files concise and identical.