@andorra-labs/code 0.0.0-stage → 0.1.5

package/docs/llms.txt

@@ -0,0 +1,45 @@
+# Andorra Code
+
+> Andorra Code is a terminal-first coding agent. Work runs on a visible graph of agent nodes
+> with typed handoffs, driven by your own model providers. This file indexes the documentation
+> for AI agents. Every page below is published on the documentation site at the path given.
+
+## Getting started
+
+- [Getting started](getting-started/README.md): Install from source (Node 22.19+), configure a provider with /providers, run the first task.
+- [Configure providers](getting-started/configure-providers.md): /providers screen, API keys and environment fallback, model discovery and health checks, local servers, config.json provider registry.
+- [Accounts, membership, and hosted Jev](getting-started/accounts.md): andorra login/logout/auth status, free vs paid access, /jev routing service and quotas.
+
+## Concepts
+
+- [Concepts overview](concepts/README.md): the graph is the harness — agent nodes, Orchestrator intake and routing, Condition/Loop/Parallel, typed handoffs, immutable revisions; default runs a single Software Engineer agent, the Orchestrator workflow is the paid :andorra graph.
+- [Workspace instructions](concepts/workspace-instructions.md): ANDORRA.md preferred, then AGENTS.md, then agents.md; never combined; 16,000-character cap; per-node Prompt overrides.
+- [Memory](concepts/memory.md): optional Graphiti persistent project memory; enable via config.json memory block or ANDORRA_GRAPHITI_URL.
+- [Limits](concepts/limits.md): limits block (wallTimeMs, maxIterations, maxToolCalls, maxContextChars, maxCompletionRepairs); defaults unlimited; request-level bounds; token totals are telemetry.
+- [Security and permissions](concepts/security.md): approvals vs /yolo, workspace containment, secrets handling, headless permission denials.
+- [Jev decision thresholds](concepts/jev-decision-thresholds.md): what gates each Jev action, what the hosted service answered in the 3D-Dodge run, and why the thresholds stay while the service is calibrated.
+- [Efficiency features](concepts/jev-efficiency.md): the off-by-default `efficiency` switches (prepared continuations, post-tool round gating, tool-result filtering, context selection, catalog selection, adaptive model-tier routing), their safety rules, accounting, and the deterministic evaluation (`npm run eval:jev`).
+
+## Guides
+
+- [The TUI](guides/tui.md): transcript, composer, slash completion, side panel, todo panel, dashboard, mouse handling.
+- [Graph Builder](guides/graph-builder.md): andorra graph; the human editor for nodes, outcome routing with written criteria, loops, joins, conversation reuse, cloud backup; paid feature. Agents author graphs through the Agent MCP server instead.
+- [Headless mode](guides/headless.md): --prompt (headless on its own; --no-tui/--json optional); exit codes 0/1/130; Orchestrator graphs return needs_clarification; --yolo for non-interactive writes.
+- [Extensions](guides/extensions.md): /skills, /mcp, /plugins — install formats, MCP server config (stdio/HTTP), limits, /logout codex.
+- [Browser workspace](guides/browser.md): /browser local web client with projects, sessions, steering, approvals.
+- [Desktop client](guides/desktop-app.md): the Tauri desktop app — projects, conversation, terminal drawer, runs, account, remote workspaces.
+- [Update](guides/update.md): andorra update (main branch, clean tree required).
+
+## Reference
+
+- [CLI](reference/cli.md): all subcommands and flags — interactive, headless, graph, mcp-server, app-server, remote, update, login, logout, auth status.
+- [Slash commands](reference/slash-commands.md): every in-TUI command with behavior notes and keyboard reference.
+- [Configuration and files](reference/config.md): ~/.andorracode layout, config.json schema, environment variables.
+
+## For AI agents
+
+Authoring a graph? Use `andorra mcp-server --stdio`, not the Graph Builder UI: begin a draft, upsert nodes and edges, validate, publish.
+
+- [For AI agents](agents/README.md): how to read these docs, raw URLs, grounding rules, and which surface to use for which task.
+- [Install Andorra Code via an AI agent](agents/install-for-agents.md): deterministic copy-paste install procedure for a coding agent to execute.
+- [Agent MCP server](agents/mcp-server.md): andorra mcp-server --stdio — the supported surface for an agent to author and edit graphs (begin, upsert, validate, publish), plus session monitoring tools, error codes, drafts, paid-membership gate, security model.

package/docs/reference/README.md

@@ -0,0 +1,7 @@
+# Reference
+
+Exact surfaces: what the CLI accepts, what the slash commands do, and what lives on disk.
+
+- [CLI commands and flags](cli.md)
+- [Slash commands](slash-commands.md)
+- [Configuration and files](config.md)

package/docs/reference/cli.md

@@ -0,0 +1,70 @@
+# CLI
+
+`andorra` is the primary command; `andorracode` is an alias for the same binary. This page is the complete command-line surface.
+
+## Usage
+
+```text
+andorra [--cwd path] [--provider id] [--model id] [--graph id]
+        [--run-input file.json] [--run-state file.json] [--yolo] [--jev on|off] [--debug]
+andorra --prompt "task" [--json] [--yolo] [--jev on|off] [--no-tui] [--debug]
+andorra graph [--no-open]
+andorra mcp-server --stdio
+andorra app-server --stdio
+andorra remote serve [--port N] [--insecure-http] [--rotate-cert]
+       andorra remote status
+       andorra remote code
+       andorra remote devices | andorra remote revoke <device-id>
+       andorra remote share <path> [--label name] | andorra remote unshare <share-id>
+       andorra remote pair <pairing-code> [--name nickname]
+       andorra remote workspaces | andorra remote unpair <workspace-id>
+       andorra remote rotate-cert
+andorra update [--break-lock]
+andorra login
+andorra logout
+andorra auth status
+```
+
+`andorra -h`/`--help` prints this usage plus the slash-command reference; `andorra --version` prints the installed version. `andorra setup` prints a pointer to `/providers` — the standalone setup wizard was removed.
+
+## Flags
+
+| Flag | Applies to | Behavior |
+| --- | --- | --- |
+| `--cwd path` | both | Set the workspace directory instead of the current folder. Works in interactive and headless mode. |
+| `--provider id` | both | Start with the given provider. |
+| `--model id` | both | Start with the given model. |
+| `--graph id` | both | Start with the given graph for this session only; make it permanent with `/graph`. `--graph :andorra` selects the paid Andorra workflow graph. |
+| `--run-input file.json` | both | Provide a JSON object satisfying a custom graph's required run inputs (for example `{"environment":"staging"}`). The prompt always supplies the canonical `task` input. |
+| `--run-state file.json` | both | Provide initial shared run state for a custom graph (for example `{"ticket":123}`). State is freshly cloned per run. |
+| `--yolo` | both | Session-only automatic approval of write and shell tools. Retains tool allowlists, argument checks and containment; it is not a sandbox. |
+| `--jev on|off` | both | Session-only Jev decision policy, overriding the saved `jevEnabled` preference without writing it. `on` still needs a signed-in account and an Agent node that opts in; when Jev cannot run, the run log records `decision.unavailable` with the reason and one notice is printed. `/jev on|off` during the session replaces the flag; `/jev status` says the flag is in effect. |
+| `--prompt "task"` | headless | Run one task non-interactively; any `--prompt` invocation is headless. `--no-tui` disables the terminal UI and `--json` prints a machine-readable result object — both optional companions, not requirements. |
+| `--no-tui` | headless | Disable the terminal UI; requires `--prompt`. |
+| `--json` | headless | Print one machine-readable result object on stdout (status, run ID, graph revision, completion, usage, tool count). Startup errors go to stderr. |
+| `--debug` | both | Write a debug journal. |
+| `--configure` | interactive | Open the local browser Graph Builder (same as `andorra graph`). |
+
+## Subcommands
+
+| Command | Behavior |
+| --- | --- |
+| `andorra` | Open the interactive TUI in the current (or `--cwd`) directory. |
+| `andorra graph [--no-open]` | Start the local Graph Builder server and open the browser. `--no-open` prints the session URL instead. Ctrl+C stops the server; closing the tab leaves it running. |
+| `andorra mcp-server --stdio` | Run the local stdio MCP server: the supported surface for an agent to author and edit graphs, plus session monitoring. See [Agent MCP server](../agents/mcp-server.md). |
+| `andorra app-server --stdio` | Run the JSON-lines app server that drives the desktop client. Not for humans; see [Desktop client](../guides/desktop-app.md). |
+| `andorra remote <subcommand>` | Remote workspace pairing and sharing — `serve`, `status`, `code`, `devices`, `revoke <device-id>`, `share <path>`, `unshare <share-id>`, `pair <pairing-code>`, `workspaces`, `unpair <workspace-id>`, `rotate-cert`, with the flags shown in the usage above. See [Remote workspace](../guides/desktop-app.md#remote-workspace). |
+| `andorra update [--break-lock]` | Install the latest npm release of `@andorra-labs/code` into the global npm installation; a source checkout is refused. `--break-lock` replaces a leftover updater lock; see [Update](../guides/update.md#an-interrupted-update). |
+| `andorra login` | Open the browser to sign in to (or create) an Andorra account. |
+| `andorra logout` | Remove this machine's saved Andorra account session and revoke its refresh token. |
+| `andorra auth status` | Show the saved Andorra account session and membership. |
+
+## Headless exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure, limit exhaustion, or `needs_clarification` (the selected graph has an Orchestrator that needs an interactive answer). |
+| `130` | Cancelled (Ctrl+C). |
+
+Without `--yolo`, headless write and shell calls receive a permission-denied observation because no interactive approver is present; read tools remain usable.

package/docs/reference/config.md

@@ -0,0 +1,85 @@
+# Configuration and files
+
+## The configuration home
+
+Everything Andorra Code stores lives under one directory:
+
+| Platform | Default |
+| --- | --- |
+| Windows | `%USERPROFILE%\.andorracode` |
+| macOS / Linux | `~/.andorracode` |
+
+Set `ANDORRACODE_HOME` to move the whole directory (useful for tests or throwaway installs).
+
+| Path | Contents |
+| --- | --- |
+| `config.json` | Providers, graph selection, limits, memory, MCP servers, extensions, permissions. Schema `version: 1`. |
+| `graphs/<id>/` | Saved graphs and their immutable revisions. |
+| `runs/<id>.jsonl`, `runs/<id>.json` | Run records: observable events with bounded tool output, and the final result. These local files can contain workspace text and command arguments; they do not store hidden reasoning or persist provider keys. |
+| `sessions/` | Saved conversation sessions (resumable with `/session`). |
+| `skills/` | Installed skills. |
+| `plugins/` | Installed plugins. |
+
+Workspace-local caches (not configuration): `.codegraph/` holds the CodeGraph index and is disposable.
+
+One exception to the configuration home: **trajectory journals** — the detailed model-request and tool-event records written during runs — live under `<installation checkout>/.andorracode/trajectories`, derived from the installed package location. They do **not** follow `ANDORRACODE_HOME`, so a throwaway configuration home still leaves trajectories in the installation checkout.
+
+## `config.json`
+
+```json
+{
+  "version": 1,
+  "provider": "local",
+  "providers": [
+    {
+      "id": "local",
+      "type": "openai-compatible",
+      "baseUrl": "http://127.0.0.1:1234/v1",
+      "model": "your-served-model"
+    }
+  ]
+}
+```
+
+Provider entries support `id`, `type` (`openai-compatible` \| `anthropic` \| `codex` \| `claude` \| `opencode-go`), `baseUrl`, `apiKey` (stored plaintext — keep the file private), `apiKeyEnv` (a saved key takes precedence), `model`, `models[]`, and `modelContextWindows` (a map from model id to its token limit, used when the endpoint does not report one), plus per-provider HTTP request bounds `requestTimeoutMs` and `streamIdleTimeoutMs`.
+
+An `anthropic` provider may set `anthropicAuth: "console"` to authenticate with the Claude Console login that `ant auth login` stored in `<config home>/anthropic-accounts/<provider id>` instead of an API key. Such a provider must use `baseUrl: "https://api.anthropic.com/v1"` and may not carry `apiKey` or `apiKeyEnv`; two signed-in providers may not have ids that differ only by case. See [Configure providers](../getting-started/configure-providers.md#claude-console-sign-in).
+
+`claude` uses the installed Claude Code CLI's managed subscription sign-in, with fixed `baseUrl: "https://api.anthropic.com"`. Like `codex`, it rejects API keys, environment-key overrides, and HTTP timeout fields. `opencode-go` uses `baseUrl: "https://opencode.ai/inference/go"` and selects each model's supported API automatically. Other endpoints retain their existing protocol behavior.
+
+OpenAI-compatible and OpenCode Go entries also accept `reasoningEffort` (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`). Omitting it uses the provider default. Go checks the selected level against the model's verified catalog options before inference.
+
+Other top-level blocks:
+
+- `limits` — `{ wallTimeMs, maxIterations, maxToolCalls, maxContextChars, maxCompletionRepairs }`, all optional. Defaults are unlimited except two completion repairs. `wallTimeMs`/`maxIterations` of `0` means unlimited; `maxToolCalls: 0` refuses every tool call. See [Limits](../concepts/limits.md).
+- `memory` — persistent memory settings, e.g. `{ "enabled": true, "provider": "graphiti", "graphiti": { "endpoint": "http://localhost:8000" } }`. See [Memory](../concepts/memory.md).
+- `mcpServers` — directly configured MCP servers (the same settings `/mcp` edits). See [Extensions](../guides/extensions.md).
+- `jevEnabled` — installation-wide Jev switch; omission means on. When on, Jev runs only on Agent nodes that set `jevEnabled: true` (the bundled presets do) and only for a signed-in account; when off, no node uses it. `/jev` and the desktop composer switch change it. See [Accounts](../getting-started/accounts.md).
+- `efficiency` — independent, off-by-default switches that reduce coding-model turns and request size: `preparedContinuations`, `postflightOnlyWithCandidates`, `toolResultFiltering` (with `toolResultFilterThresholdChars`, default 6000), `contextSelection`, `catalogSelection`, and `adaptiveRouting` (`{ enabled, tiers: { economy, balanced, premium }, maxEscalations, pricing }`, where each tier names a configured provider and optionally one of its models). Omitting the block is the shipped behavior. See [Efficiency features](../concepts/jev-efficiency.md).
+- `workspacePermissions` — remembered per-workspace permission modes (`/permissions`).
+- `extensions.disabledSkills` / `extensions.disabledPlugins` — disabled extension ids.
+- `graph`, `graphSelections` — default graph per account.
+- `codeIntel` — CodeGraph/code intelligence settings.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `ANDORRACODE_HOME` | Override the whole configuration directory. |
+| `ANDORRA_GRAPHITI_URL` | Endpoint for the Graphiti memory service (alternative to the `memory.graphiti.endpoint` config). |
+| `ANDORRA_MEMORY_PROVIDER` | Memory provider override (`graphiti` or `none`). |
+| `ANDORRA_CODEX_PATH` | Explicit Codex CLI executable override. Invalid overrides fail without falling back to another installation. |
+| `ANDORRA_CLAUDE_PATH` | Path to the native Claude Code executable used by the Claude subscription provider. |
+| `ANDORRA_ANT_PATH` | Path to the Anthropic CLI (`ant`) executable used for Claude Console sign-in, when it is not on PATH. |
+| `ANDORRA_CLI` / `ANDORRA_NODE` | Desktop client engine overrides. See [Desktop client](../guides/desktop-app.md). |
+| Provider keys | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `MOONSHOT_API_KEY`, or any name configured in a provider's **Environment fallback** field. |
+
+Remote endpoints require HTTPS; private-network hosts (including Tailscale addresses) may use HTTP. URLs cannot contain embedded credentials.
+
+On Windows, automatic Codex provider discovery checks `%LOCALAPPDATA%\Programs\OpenAI\Codex\bin\codex.exe`, then the current user's registered official Codex desktop package, then PATH/npm installations. The package is queried on each connection, so desktop updates do not pin Andorra to an obsolete versioned WindowsApps path. This order preserves an existing fixed desktop installation and prefers the signed desktop package over PATH. Discovery checks the package identity, Store signature status, and native executable; it does not scan WindowsApps or execute npm shims. If Windows package queries are unavailable, PATH/npm discovery continues. Restricted shell tools still apply their separate installation trust checks.
+
+## Security notes
+
+- Saved API keys are plaintext in `config.json`. Keep the file private; do not commit or share it.
+- Shell tools execute as your OS user with an allowlisted environment that excludes provider credential variables — but shell commands can still access credential files on disk.
+- Andorra account tokens are stored in the operating system credential store, never in `config.json`, and are never written as plaintext fallback.

package/docs/reference/slash-commands.md

@@ -0,0 +1,54 @@
+# Slash commands
+
+Slash commands run inside the interactive TUI. Type `/` as the first character to open the suggestion list; typing filters it, Up/Down highlights, Enter runs, and Tab fills the command into the composer so an argument can be added by hand. A command that needs an argument (`/attach`, `/codegraph`, `/feedback`, `/jev`, `/reasoning`, `/yolo`) never runs bare from the composer: Enter or Tab fills in the command and a space and opens its argument list, read-only choice first, so a second Enter reports rather than changes a setting.
+
+| Command | Behavior |
+| --- | --- |
+| `/browser` | Open the browser workspace (CLI stays available). See [Browser workspace](../guides/browser.md). |
+| `/session` | Browse and resume saved sessions (newest first). |
+| `/login` | Open browser sign-in or create an Andorra account. |
+| `/auth logout` | Remove this machine's saved Andorra account session. |
+| `/auth status` | Show Andorra account session status and membership. |
+| `/model [model-id]` | Open model selection or select a model directly; with a graph that pins node models, asks whether to override them. |
+| `/model list` | Discover models from the active provider. |
+| `/providers [id]` | Choose providers; Right/e edits; Add provider configures. See [Configure providers](../getting-started/configure-providers.md). |
+| `/reasoning <level>` | Set reasoning effort: `default\|none\|minimal\|low\|medium\|high\|xhigh\|max`. Without a level it reports the current one and the usage. |
+| `/graph [id]` | Select a graph or open the web graph builder. See [Graph Builder](../guides/graph-builder.md). |
+| `/codegraph <action> [--global]` | Code intelligence: `status\|enable\|disable\|rebuild`. `enable`/`disable` alone record an override for the current repository; with `--global` they set the saved default that every project and every new session starts from, and clear the per-repository overrides. `status` shows the saved default and this repository's override. |
+| `/dashboard` | Toggle live dashboard and transcript (TTY only). See [The TUI](../guides/tui.md#dashboard). |
+| `/attach <path>` | Attach a file or folder to your next task (large pastes and dropped files attach automatically). |
+| `/usage` | Open session usage: requests, provider-reported input/output tokens, last run and tool count (Escape to return). Cost is unavailable. |
+| `/permissions [mode]` | Choose and remember workspace permissions. |
+| `/jev <on\|off\|status>` | Turn hosted Jev routing on or off, or show its saved setting (all plans). Without an argument it reports, like `status`, and changes nothing. See [Accounts](../getting-started/accounts.md). |
+| `/feedback <on\|off\|status>` | Show the anonymous-feedback setting; Paid accounts can turn it off. Without an argument it reports, like `status`, and changes nothing. |
+| `/yolo <on\|off>` | Turn session-wide Full Access (host files and network) on or off. Never persisted. Without an argument it reports the current state and changes nothing. |
+| `/tools` | List available coding tools and the approval policy. |
+| `/skills` | List, install, enable, disable or remove skills. See [Extensions](../guides/extensions.md). |
+| `/plugins` | List, install, enable, disable or remove plugins. See [Extensions](../guides/extensions.md). |
+| `/mcp` | Add, edit, enable, disable or delete MCP servers. See [Extensions](../guides/extensions.md). |
+| `/logout` | Sign out of your Andorra account on this machine (same as `/auth logout`). Run `/login` afterwards to sign in, or to switch to another account. |
+| `/logout codex` | Sign out of every configured Codex (ChatGPT) account and exit. Provider settings are kept. |
+| `/status` | Show workspace and current settings. |
+| `/clear` | Clear the conversation on screen and the retained context (session usage is retained). |
+| `/compact` | Compact retained conversation history to free context. |
+| `/help` | Show commands. |
+| `/exit` | Quit (`/quit` is an alias). |
+
+## Behavior notes
+
+- Changing model/provider clears conversation context. Each task starts a fresh Agent attempt with up to six previous task/completion summaries as explicit follow-up context; private tool transcripts are not reused.
+- Slash commands run between runs. During a run, a live subset (`/browser`, `/attach`, `/yolo`, `/permissions`, `/status`, `/usage`, `/tools`, `/help`, `/exit`/`/quit`) executes immediately; any other line starting with `/` is neither run nor sent to the model — a recognized session command such as `/clear` or `/graph` prints a hint to press Ctrl+C first, and anything else that starts with `/` (including a path such as `/src/app.ts`) is reported unavailable. Text that does not start with `/` still steers the running task.
+- `/graph` switching clears the previous graph's progress and starts fresh; choosing a different graph confirms first, and `/graph <id>` warns in its reply instead.
+- Selection screens use Up/Down to browse, Enter or Space to select, and Escape to return without changing anything.
+
+## Keyboard reference
+
+| Key | Action |
+| --- | --- |
+| Ctrl+B | Toggle dashboard; Ctrl+G pages its graph; Ctrl+N cycles dashboard model statistics (display only). |
+| Ctrl+T | Expand/collapse the todo list. |
+| Ctrl+O | Expand/collapse tool and approval details. |
+| Ctrl+Y | Expand the reasoning preview. |
+| Ctrl+C | Stop an interactive run; press again (or while idle) to exit. Headless Ctrl+C cancels the run; a second press exits. |
+| Ctrl+D | Exit from an empty prompt. |
+| Page Up/Page Down | Scroll the transcript (and expanded todo/dashboard cards). |

package/docs/superpowers/plans/2026-11-01-claude-console-sign-in.md

@@ -0,0 +1,111 @@
+# Claude Console Sign-in Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let an `anthropic` provider authenticate with a Claude Console login made through `ant auth login`, from the desktop settings and the TUI, and default Anthropic providers to `claude-opus-5-5`.
+
+**Architecture:** `ant` performs the browser login into a per-provider config directory (`<andorra home>/anthropic-accounts/<provider id>`). The engine reads that directory with the Client SDK's `resolveCredentialsFromConfig`, which refreshes tokens, and sends `Authorization: Bearer` plus the OAuth beta and workspace headers. Sign-in is exposed through the existing `providers.auth.*` app-server methods and a TUI menu entry.
+
+**Tech Stack:** TypeScript (Node ≥ 22, ESM), `@anthropic-ai/sdk` 0.124.0, `node:test` via `scripts/run-tests.mjs`, React + Vitest in `desktop/`.
+
+Spec: `docs/superpowers/specs/2026-11-01-claude-console-sign-in-design.md`.
+
+---
+
+## File map
+
+| File | Change |
+|---|---|
+| `src/providers.ts` | `anthropicAuth` field; credential assertions; `send` uses the header helper and retries a 401 once; Opus default |
+| `src/config.ts` | validation for `anthropicAuth` |
+| `src/anthropic-credentials.ts` (new) | account directory, saved-login reader, `providerAuthHeaders` |
+| `src/anthropic-console-auth.ts` (new) | `ant` resolution, `AnthropicConsoleAuth` start/status/cancel/logout, account retirement |
+| `src/provider-connection.ts`, `src/model-metadata.ts` | use `providerAuthHeaders` |
+| `src/app-server.ts`, `src/app-server/protocol.ts` | `providerType: 'anthropic'` sign-in, `organization`/`workspace` fields, capability, upsert passthrough, retirement |
+| `src/provider-settings.ts`, `src/command-screens.ts` | TUI credential toggle, sign-in entry, retirement |
+| `desktop/src/engine/*`, `desktop/src/components/AnthropicConsoleSignIn.tsx` (new), `SettingsView.tsx`, `providerPresets.ts` | form choice, sign-in panel, labels |
+| `test/anthropic-credentials.test.ts`, `test/anthropic-console-auth.test.ts` (new), existing config/app-server/desktop tests | coverage |
+| `tests/claude-console-sign-in-test-plan.md` (new) | QA plan |
+
+## Task 1: Config field and validation
+
+**Files:** `src/providers.ts` (ProviderConfig, `assertProviderCredentials`, `defaultProviders`), `src/config.ts` (provider loop), `test/config.test.ts`.
+
+- [ ] Add to `ProviderConfig`, after `codexEmail`:
+
+```ts
+  /** `console`: requests use the Claude Console login stored for this provider instead of an API key. */
+  anthropicAuth?: 'console';
+```
+
+- [ ] In `assertProviderCredentials` (widen its `Pick` to include `anthropicAuth`):
+
+```ts
+  if (provider.anthropicAuth !== undefined && (provider.type !== 'anthropic' || provider.anthropicAuth !== 'console')) {
+    throw new Error('anthropicAuth is an Anthropic-only setting whose only value is console.');
+  }
+  if (provider.anthropicAuth === 'console' && (provider.apiKey !== undefined || provider.apiKeyEnv !== undefined)) {
+    throw new Error('Claude Console sign-in replaces the API key; remove the key or the sign-in.');
+  }
+```
+
+- [ ] In `validateConfig`'s provider loop: a console provider's `baseUrl` must be `https://api.anthropic.com/v1`; after the loop, reject two console providers whose ids fold to the same lowercase string.
+- [ ] `defaultProviders()` anthropic model becomes `claude-opus-5-5`.
+- [ ] Tests in `test/config.test.ts`: accepted console provider; rejected on `openai-compatible`; rejected with `apiKeyEnv`; rejected with another base URL; rejected case-colliding ids. Run `node scripts/run-tests.mjs test/config.test.ts` (fail → implement → pass). Commit.
+
+## Task 2: Saved login and request headers (`src/anthropic-credentials.ts`)
+
+- [ ] Exports:
+
+```ts
+export const ANTHROPIC_CONSOLE_BASE_URL = 'https://api.anthropic.com/v1';
+export function anthropicAccountHome(providerId: string, configHome = configDirectory()): string; // join(configHome, 'anthropic-accounts', providerId)
+export interface AnthropicConsoleAccount { email?: string; organization?: string; workspace?: string }
+export async function readAnthropicConsoleAccount(home: string): Promise<AnthropicConsoleAccount | undefined>;
+export async function providerAuthHeaders(provider: ProviderConfig, options?: { forceRefresh?: boolean; configHome?: string; fetch?: typeof fetch }): Promise<Record<string, string>>;
+```
+
+- `readAnthropicConsoleAccount` reads `credentials/default.json`; returns `undefined` unless it has a string `access_token` and either a refresh token or an `expires_at` in the future. Display fields are bounded strings without control characters.
+- `providerAuthHeaders`: API-key providers return today's headers (`anthropic-version` + `x-api-key` for Anthropic; `authorization: Bearer` otherwise; nothing without a key). Console providers: read `configs/default.json`, require `authentication.type === 'user_oauth'`, set `credentials_path`, call `resolveCredentialsFromConfig(config, { baseURL: 'https://api.anthropic.com', fetch })`, call `provider({ forceRefresh })`, and return `anthropic-version`, `authorization: Bearer <token>`, `anthropic-beta: oauth-2025-04-20`, plus `extraHeaders`. Missing files → `Sign in with Claude Console for provider <id>, then retry.`; any SDK failure → `Your Claude Console sign-in expired or could not be refreshed. Sign in again.` (never the SDK message, which can echo response bodies).
+- [ ] `test/anthropic-credentials.test.ts`: API-key headers unchanged; console headers from a temp dir (token, beta, workspace); missing login message; an expired token with a refresh token refreshes against a local HTTP token endpoint (`configs/default.json` `base_url` pointing at `http://127.0.0.1:<port>`) and the file is rewritten; refresh failure message contains no token text. Fail → implement → pass. Commit.
+
+## Task 3: Use the helper in inference, test and discovery
+
+- [ ] `src/providers.ts` `send`: replace the header block with `Object.assign(headers, await providerAuthHeaders(config, { forceRefresh }))`; when a console provider answers 401, cancel the body and resend once with `forceRefresh: true`.
+- [ ] `src/provider-connection.ts` and `src/model-metadata.ts`: build headers with `providerAuthHeaders` (the connection test turns a thrown helper error into `failed(message)`).
+- [ ] Extend `test/anthropic-credentials.test.ts` with an adapter test: a local HTTP server returns 401 then 200, the adapter's `listModels` succeeds and the server saw two requests with Bearer headers. Run existing `test/providers*.test.ts` and `test/provider-connection.test.ts` to confirm API-key behaviour is unchanged. Commit.
+
+## Task 4: Sign-in manager (`src/anthropic-console-auth.ts`)
+
+- [ ] `resolveAntExecutable({ env, platform })`: `ANDORRA_ANT_PATH` (absolute path or a name looked up on PATH), else `ant`/`ant.exe` on PATH; skip `.cmd/.bat/.ps1`; a path ending in `.js`/`.mjs` is run with `process.execPath` (used by tests). Missing → `AuthFailure(installMessage, 'unavailable')`.
+- [ ] `AnthropicConsoleAuth` with the spec's state type. `start(attemptId, home)`: refuse a second live attempt for the same home (`busy`); `mkdir(home, { recursive: true })`; spawn `ant auth login --timeout 10m` (`shell: false`, `windowsHide`, `stdio: ['ignore', 'pipe', 'pipe']`, `detached` off-Windows, env = parent minus `ANTHROPIC_*` plus `ANTHROPIC_CONFIG_DIR=home`); drain output up to 1 MiB and discard it; answer `{ state: 'waiting', attemptId }`. On exit 0 with a readable login → `signedIn` with account fields; non-zero → `error` "Claude Console sign-in did not complete. Try again."; timeout of 11 minutes → kill tree, `error` `timeout`. `status(attemptId?, home)`: a live attempt answers its state; otherwise the saved login decides `signedIn`/`signedOut`. `cancel` kills the tree (`taskkill /PID /T /F` via `resolveTrustedTaskkill`, else `process.kill(-pid)`) and answers `cancelled`. `logout(home)`: cancel any attempt, `rm(home, { recursive: true, force: true })`, answer `signedOut`, or `error`/`logoutFailed`. `close()` cancels everything.
+- [ ] `droppedAnthropicAccounts(previous, next): string[]` (ids that were console providers and are not console providers in `next`) and `retireAnthropicAccounts(ids, configHome?)`.
+- [ ] `test/anthropic-console-auth.test.ts` with a fake `ant` (`.mjs` written to a temp dir) whose behaviour is chosen by an env var: writes the two files and exits 0; exits 1; sleeps. Cover signed-in result, error, busy, cancel kills it, logout removes the directory, the child's env has `ANTHROPIC_CONFIG_DIR` and lacks `ANTHROPIC_API_KEY`, missing executable → `unavailable`. Commit.
+
+## Task 5: App-server
+
+- [ ] `protocol.ts`: add `organization?`, `workspace?` to `AppServerProviderAuth`; `anthropicAuth?: 'console'` to `AppServerProvider`; capability `'providers.anthropicConsole'`.
+- [ ] `app-server.ts`: `providerAuth` accepts `providerType: 'anthropic'` with a required `providerId` naming a stored console provider and routes to an injected `anthropicAuth: AnthropicConsoleAuth` (constructor option for tests); `providerAuthView` projects the two new fields through `text(…, 200)`; errors map to `AppServerError('auth', 'Claude Console sign-in could not be completed. Check the Anthropic CLI (ant) and try again.')`. Provider views include `anthropicAuth`. Upsert: `anthropicAuth` keeps the stored value when omitted on an anthropic entry, `null` removes it. Removal and config writes retire `droppedAnthropicAccounts` after commit, next to `retireSlots`. `close()` closes the manager.
+- [ ] Tests in the app-server provider test file: auth start/status with a stub manager, rejection for a non-console provider, view projection, upsert passthrough, capability listed. Commit.
+
+## Task 6: TUI
+
+- [ ] `provider-settings.ts`: for `type === 'anthropic'` show `Credential: API key | Claude Console sign-in` (toggling sets/deletes `anthropicAuth`, clears `apiKey`/`apiKeyEnv`, fixes `baseUrl`) and, when console, replace the key rows with `Sign in with Claude Console`. The login runs `AnthropicConsoleAuth.start` then waits for a terminal state inside `ui.loadScreen` (Esc → `cancel`), prints "Opening your browser to sign in to Claude Console…", then lists models through the adapter. Add `anthropicAuth` to the key-reconcile list at the end of the loop. `discard()` retires the account of a new console provider that was never saved.
+- [ ] `command-screens.ts` `save`: after a committed write call `retireAnthropicAccounts(droppedAnthropicAccounts(previousProviders, reconciled.providers))`; after a refused write retire accounts of console ids absent from the saved config.
+- [ ] Extend `test/provider-settings.test.ts`: toggling to console removes key fields and sets the base URL; the sign-in entry calls an injected auth stub. Commit.
+
+## Task 7: Desktop
+
+- [ ] `engine/protocol.ts`: mirror the protocol additions. `engine/providerEntry.ts`: carry `anthropicAuth`, omit key fields for console entries, refuse a console save without the capability ("Update the Andorra CLI to use Claude Console sign-in.").
+- [ ] `engine/anthropicConsoleAuth.ts` (new): transport over `providers.auth.*` with `providerType: 'anthropic'` and a small controller that starts, polls status every 2 s while waiting, cancels, logs out.
+- [ ] `components/AnthropicConsoleSignIn.tsx` (new): states and buttons per the spec; on an unsaved draft it shows "Save this provider, then sign in from the provider list."
+- [ ] `SettingsView.tsx`: Credential select (API key / Claude Console sign-in) on Anthropic forms; render the panel on saved console providers and in the detail panel; credential row text. Labels: preset `Claude` / "Uses your Claude Code CLI sign-in"; type option "Claude (via Claude Code CLI)"; Anthropic preset model `claude-opus-5-5`.
+- [ ] Vitest: `AnthropicConsoleSignIn.test.tsx` (signed out → waiting → signed in; refusal without capability) and `providerEntry` cases. Run `npm --prefix desktop run test -- <files>`. Commit.
+
+## Task 8: Docs, QA plan, verification
+
+- [ ] `docs/getting-started/configure-providers.md` and `docs/reference/config.md`: document `anthropicAuth` and the `ant` prerequisite.
+- [ ] `tests/claude-console-sign-in-test-plan.md` per AGENTS.md.
+- [ ] `npm run build`; run the touched test files; `npm --prefix desktop run typecheck`.
+- [ ] Run verification with a throwaway `ANDORRACODE_HOME`: `app-server --stdio` driven over stdin with the fake `ant` (start → status signedIn → provider test against a local stub API), then one real `ant auth login` with the user's approval.
+- [ ] Commit, push, open the PR with the template.