@andorra-labs/code 0.0.0-stage → 0.1.4

package/docs/getting-started/configure-providers.md

@@ -0,0 +1,103 @@
+# Configure providers
+
+Andorra Code talks to your model providers directly. A provider entry stores a protocol type, an endpoint, credentials, and a default model. Everything is configured from the `/providers` screen inside the TUI — the old standalone `andorra setup` wizard has been removed.
+
+## Add or edit a provider
+
+Run `andorra`, then enter `/providers`. Each provider occupies one row. Up/Down moves the highlight; Enter selects the active provider. Press **Right Arrow** or **e** on a provider to open its settings. Endpoint and protocol details live in that editor instead of cluttering the provider list.
+
+Use **Add provider** to configure your first provider or add another. Select a preset such as DeepSeek, Kimi, Kimi For Coding (Global or China), GLM Coding Plan (Z.ai), OpenAI, Anthropic, local, or Codex, then edit the connection and model. You can enter an exact model ID when model discovery is unavailable. Settings remain a draft until you choose **Save changes**; Escape from the settings menu returns without saving the draft. **Delete provider** asks for confirmation and shows the replacement active provider; deleting the final provider returns to the unconfigured state.
+
+## Credentials
+
+For hosted APIs, choose **API key** and paste the **actual API key** into the masked field. The key is saved locally with the provider and reused after restarting Andorra. It is not added to command history or displayed in provider summaries. Configuration is stored in `config.json` under `ANDORRACODE_HOME` (default `~/.andorracode`); saved API keys are plaintext in this local file, so keep it private and do not commit or share it. The separate **Environment fallback** field accepts a variable name. A saved key takes precedence; **Remove authentication** clears both.
+
+Preset endpoints: DeepSeek uses `https://api.deepseek.com`; Kimi uses `https://api.moonshot.ai/v1`; Kimi For Coding (Global) uses `https://api.kimi.ai/coding/v1` and Kimi For Coding (China) uses `https://api.kimi.com/coding/v1`; GLM Coding Plan (Z.ai) uses `https://api.z.ai/api/coding/paas/v4`. The coding-plan presets come pre-filled with the plan's default model (`kimi-for-coding`, `glm-5.3`) and take the API key from that plan's console — the Kimi Code Console or the Z.ai coding-plan page — not the standard platform key. Codex uses the installed Codex CLI's managed ChatGPT sign-in; subscription tokens are not copied into provider configuration.
+
+### Claude Console sign-in
+
+An **Anthropic** provider can sign in with a Claude Console account instead of an API key. Requests are billed as API usage to the Console organization and workspace you pick in the browser; this is not a Claude Pro or Max subscription.
+
+1. Install the Anthropic CLI (`ant`) from [github.com/anthropics/anthropic-cli/releases](https://github.com/anthropics/anthropic-cli/releases) and make sure it is on PATH. `ANDORRA_ANT_PATH` can name the executable instead.
+2. In Desktop, add or edit an **Anthropic** provider, set **Credential** to **Claude Console sign-in**, save, then choose **Sign in with Claude Console** on the provider. In `/providers`, set **Credential** to **Claude Console sign-in** and choose **Sign in with Claude Console**.
+3. Your browser opens. Pick the organization and workspace, then return to Andorra. The provider shows the signed-in email, organization and workspace.
+
+Andorra runs `ant auth login` with `ANTHROPIC_CONFIG_DIR` set to `~/.andorracode/anthropic-accounts/<provider id>`, so each provider keeps its own login and your own `ant` profiles are never read or changed. The Anthropic SDK refreshes the access token from that directory; Andorra never handles the OAuth exchange. **Sign out**, or removing the provider, deletes the directory. New Anthropic providers start on `claude-opus-5-5`; **Discover Models** lists the rest.
+
+### Claude subscription
+
+Choose **Claude (via Claude Code CLI)** in Desktop, or **Claude subscription** in `/providers`. Install the native Claude Code CLI and run `claude auth login` yourself first. Andorra reuses that CLI's managed sign-in; it never copies OAuth access or refresh tokens into its configuration. `ANDORRA_CLAUDE_PATH` can select a native CLI executable when it is not on PATH.
+
+**Discover Models** reads the models available to the installed Claude CLI. The CLI must support safe mode, structured JSON output, and the stream-json control protocol. Andorra sends one model step at a time with native tools, MCP servers, hooks, plugins, and workspace customizations disabled. Andorra retains tool execution and permissions. Images use native image blocks. Changing providers does not change JEV or graph selection.
+
+In Desktop, Claude and Go drafts can discover models before saving: choose the provider type, select and add the first model, then save the complete entry. This requires an engine advertising draft discovery; older engines display an update instruction.
+
+Auxiliary requests such as titles, model-health checks, graph generation, and context summaries use a separate tool-free mode with an explicit output cap. This requires native output/budget controls and matching stream usage metadata; incompatible CLI behavior is rejected. An explicit output cap combined with tool execution is not supported.
+
+### OpenCode Go
+
+Choose **OpenCode Go (all model APIs)** and save your Go API key. Its fixed base is `https://opencode.ai/inference/go`. Discovery includes the live Go catalog. The adapter selects Chat Completions, Responses, Anthropic Messages, or Gemini according to verified model metadata. Requests stay on Go endpoints; failures never fall back to pay-as-you-go service. New models with unknown protocol metadata fail explicitly until their metadata is available.
+
+Go's model catalog is public. **Test connection** and per-model **Test** verify catalog reachability and listing membership, not authentication or account entitlement; the UI labels this distinction. Run a small task to verify access. Inference reports a sanitized error on failure and does not automatically retry transient errors. Model availability and subscription limits remain controlled by OpenCode.
+
+Changing an existing provider into or out of OpenCode Go clears its previous credential. Enter a key for the new connection. To reuse a previous environment-variable name, save the type change first and then set the variable; an unchanged fallback is not carried to a different provider.
+
+## Choose a model
+
+`/model` opens the model selection screen, which fetches the active provider's available models; Escape cancels loading. `/model list` queries the model endpoint directly, and `/model <id>` selects an exact ID.
+
+The model must support function/tool calling. Hosted defaults are configurable examples, not an account entitlement or availability guarantee. OpenAI-compatible providers use Chat Completions; Anthropic uses Messages. Protocol references: [OpenAI Chat](https://developers.openai.com/api/reference/resources/chat), [Anthropic Messages](https://platform.claude.com/docs/en/api/messages/create).
+
+Reasoning effort is per provider: `/reasoning` inspects it, `/reasoning high` (or another supported level: `default|none|minimal|low|medium|high|xhigh|max`) saves an explicit override for an OpenAI-compatible or OpenCode Go provider, and `/reasoning default` clears the override. An unset value shows as `provider default`; the CLI cannot infer the server's actual default. Effort support depends on the model and server; Go rejects values absent from the selected model's verified reasoning options before inference. Changing models clears the old override.
+
+## Model discovery and context windows
+
+For OpenAI-compatible and Anthropic API-key providers, model discovery (Desktop **Discover Models**, `/model list`) asks `GET <baseUrl>/models`; a base URL ending in `/v1` therefore calls `/v1/models`. The request is bounded by the shorter of a positive `requestTimeoutMs` and 30 seconds, or 30 seconds otherwise. A failed discovery names the endpoint and the reason — HTTP status, timeout, unreachable, or invalid JSON.
+
+Managed Claude and Codex discovery use their native CLIs. Go reads its public listing and protocol metadata under one shared deadline, using the same shorter-of-provider-and-30-seconds rule. Cancellation or expiration stops both reads; an ordinary metadata-service outage can still use verified bundled metadata.
+
+An endpoint that reports a limit (`max_model_len`, `context_window`, `context_length`, or `max_context_length`) has it shown per model; SparkDeck deployment metadata and LM Studio's native listing are used as fallbacks. The desktop settings screen saves the limit per configured model in `modelContextWindows`, so switching models does not inherit another model's window and an offline endpoint keeps the last known value. Each model row also has its own **Test** button, which checks that the model appears in the listing without spending tokens.
+
+## Local servers
+
+The local provider uses `http://127.0.0.1:1234/v1` with no key (an LM Studio-style server). Its placeholder model must be replaced with your server's model ID:
+
+```text
+/providers local
+/model list
+/model your-served-model
+```
+
+Private-network endpoints (including Tailscale addresses) may use HTTP; remote endpoints require HTTPS, and URLs cannot contain embedded credentials.
+
+## Model health checks
+
+Loading a graph checks each model with a small inference request, including startup's saved graph, agent overrides, retry fallbacks, and enabled subagent roles. Unavailable models are listed with their affected nodes, and tasks are blocked to prevent downstream errors. Open `/graph` and choose **Edit Graphs** to repair the model selections. Saving and reselecting the graph, or submitting the next task, reloads and rechecks it. Provider/model changes also trigger a check. Each probe has a 30-second deadline and may consume provider quota; probe usage is separate from task usage totals.
+
+## Editing `config.json` directly
+
+Saving setup creates `~/.andorracode/config.json` (override the directory with `ANDORRACODE_HOME`). `/providers` and `/model` save selections there. Add compatible providers by editing the shared registry:
+
+```json
+{
+  "version": 1,
+  "provider": "local",
+  "providers": [
+    {
+      "id": "local",
+      "type": "openai-compatible",
+      "baseUrl": "http://127.0.0.1:1234/v1",
+      "model": "your-served-model"
+    },
+    {
+      "id": "hosted",
+      "type": "openai-compatible",
+      "baseUrl": "https://your-provider.example/v1",
+      "apiKeyEnv": "YOUR_PROVIDER_API_KEY",
+      "model": "your-model"
+    }
+  ]
+}
+```
+
+Supported adapter types are `openai-compatible`, `anthropic`, `codex`, `claude`, and `opencode-go`. Managed CLI providers reject API-key overrides and HTTP timeout fields. The full configuration surface, including limits, memory, and request timeouts, is in [Reference: configuration](../reference/config.md).

package/docs/guides/README.md

@@ -0,0 +1,12 @@
+# Guides
+
+Task-oriented how-tos for every client and mode.
+
+- [The TUI](tui.md) — the `andorra` terminal interface: transcript, composer, side panel, todos, dashboard.
+- [Graph Builder](graph-builder.md) — building custom graphs in the local browser editor: nodes, routing, loops, joins, cloud backup.
+- [Headless mode](headless.md) — one-shot runs with `--prompt`, `--json`, exit codes, and `needs_clarification`.
+- [Extensions](extensions.md) — skills, MCP servers, and plugins.
+- [Browser workspace](browser.md) — the `/browser` local web client.
+- [Desktop client](desktop-app.md) — the Tauri desktop application.
+- [Windows code signing](windows-code-signing.md) — Authenticode signing of the desktop bundles with Azure Artifact Signing, and how to verify a signature.
+- [Update](update.md) — keeping a source installation current with `andorra update`.

package/docs/guides/browser.md

@@ -0,0 +1,15 @@
+# Browser workspace
+
+From an interactive Andorra Code CLI session, run `/browser`. Andorra starts a local application on an ephemeral loopback port and opens your default browser. The CLI continues working, including when `/browser` is launched during an active run.
+
+Projects in the left sidebar are folders used by CLI sessions. Select a session to inspect its conversation, recent expandable tool activity and progress. Activity keeps the newest 200 events within a 256 KiB budget per session; older activity leaves this window while full conversation turns remain retained. Send a task in an idle session, steer a running session from the composer, cancel it, or answer questions and approval requests. After cancellation, a browser-owned run remains Cancelling until its provider or tool settles; additional cancellation and steering are disabled during that time. Answers in the terminal and browser share the same pending runtime question.
+
+New session accepts an existing local folder path. Browser-created sessions use your configured default graph and provider/model, plus saved permissions for that workspace. Use CLI `/providers`, `/model`, `/graph` and `/permissions` to edit configuration. Permission and paid-graph gates continue to run in the existing runtime.
+
+Settings controls maximum days since last activity (30 by default; 0 means all history) and light/dark/system appearance, persisted across server restarts. Active sessions remain visible regardless of age. Filtering hides records without deleting them. New sessions retain all task/outcome turns; older records only contain what earlier versions saved. Model resume context is stored separately and uses at most six turns, preserving `/clear`, provider/model/graph resets, and `/compact` summaries without deleting the displayed transcript.
+
+The application belongs to the CLI that launched it. Closing its browser tab leaves runs active; exiting the owner CLI stops the application and cancels its browser-owned runs. Another live CLI is discovered through authenticated local endpoints. A historical run whose owner has disappeared is displayed as disconnected and can be resumed as a fresh run.
+
+The printed URL includes a capability token in its fragment. Keep it private. The server binds only to 127.0.0.1, validates request host/origin and bearer authorization, and uses existing trajectory sanitization for stored tool activity. It does not provide remote access or a cloud relay.
+
+

package/docs/guides/desktop-app.md

@@ -0,0 +1,325 @@
+# Andorra Code desktop client
+
+The desktop client is a window onto the same agent runtime the terminal uses. It adds projects, a
+conversation surface, provider and graph settings, a terminal, a file and change browser, run
+records, and the door to the graph editor. It does not reimplement any of them: the engine is the
+`andorra` CLI, driven by the window. Installers carry the matching engine and its dependencies.
+
+## Requirements
+
+| Requirement | Notes |
+| --- | --- |
+| Node.js 22.19 or newer | Needed to build from source or use a custom engine. Installed releases include their own supported Node runtime. |
+| The Andorra CLI | Installed releases include the engine built for that desktop version, with production dependencies. Source development links `@andorra-labs/code` from the checkout. Explicit custom engines must support `app-server --stdio`. |
+| Rust 1.90+ and the Tauri CLI | Only to build the shell. The Tauri CLI is installed by `npm install` in `desktop/`. |
+| Platform webview | WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux. |
+
+### Which engine the window starts
+
+An installed release starts its bundled engine and Node runtime by default. Updating the GUI
+replaces that engine and its production dependencies together, without npm, a separate CLI update,
+or access to the private repository. A damaged or mismatched payload shows a repair error instead
+of silently using an older global engine. Global CLI installations and source checkouts are not modified.
+
+To deliberately use a different engine, pick one under **Settings → Appearance → Engine**, or set
+`ANDORRA_CLI` to the absolute path of a `cli.js`. These choices take precedence over the bundled
+engine and remain your responsibility to update. The **Node executable** setting
+overrides the interpreter used for a JavaScript entry point, and `ANDORRA_NODE` applies when that
+field is empty.
+
+Source-development builds without a staged payload retain discovery of the checkout dependency,
+global npm installations, then `andorra` on `PATH`.
+
+The engine the window resolved — interpreter and entry point — is shown as **Resolved command**
+under Settings → Appearance → Engine, which is how a window driving a checkout is told apart from
+one driving an installed CLI.
+
+A checkout's own `cli.js` is never executed unless you select it: the launch directory is not
+searched, so starting the window from an untrusted checkout cannot run that checkout's engine. Set
+the **Entry point** setting, or `ANDORRA_CLI`, to point at a build you trust.
+
+Setting **Configuration home** (or `ANDORRACODE_HOME` for the window's own environment) points both
+clients at a throwaway home, which is how you keep a window's settings away from a real
+installation.
+
+## Run it
+
+```bash
+npm install               # in the repository root: the engine's own dependencies
+npm run build             # in the repository root: the built CLI, the client's engine
+cd desktop
+npm install               # links @andorra-labs/code -> the checkout root, and the shell toolchain
+npm run desktop:dev       # builds the shell and opens the window with the dev server
+```
+
+Other scripts:
+
+```bash
+npm run dev              # renderer only, in a browser (no engine: the window shows the failure state)
+npm test                 # renderer unit tests
+npm run build            # typecheck and build the renderer bundle
+npm run icons            # regenerate the application icons after changing the mark
+npm run desktop:build    # produce installers for the current platform
+```
+
+`npm run desktop:build` writes installers under `desktop/src-tauri/target/release/bundle/`: NSIS on
+Windows, `app` and `dmg` on macOS, and `appimage` on Linux. Linux ships as an AppImage only.
+Cross-compiling is not supported; build each platform on its own runner.
+
+### Closing the window
+
+On Windows, closing the window — the title bar's close button, `Alt+F4`, or the taskbar's Close
+window — hides it to the notification area instead of quitting: engines that are mid-run keep
+running, and unsaved editor state is kept as it was. A left click on the tray icon (a double click
+works too) shows the window again, a right click opens the tray menu, and that menu's **Exit** is
+the way to quit for real — it asks before dropping an unsaved provider draft. Launching the app
+again while it is hidden reveals the running instance rather than starting a second one. macOS and
+Linux close the window and quit as before.
+
+## How the window drives the engine
+
+The window talks to the `andorra` CLI over a line-delimited JSON protocol on standard input and
+output: one request object in, one response or event object out. The protocol is internal to the
+window and the CLI — you do not speak it directly.
+
+A process runs one task, so **a task started while another is working gets an engine of its own**.
+The window keeps one engine for browsing — projects, sessions, configuration, terminals, the run
+history — and a small pool of task engines: a task is offered to the free ones first, and another
+engine is started when they are all busy. Rows, approvals, questions, and Stop are routed to the
+engine executing that task, so two tasks can be read and steered side by side. The window caps one
+window at 16 live engines.
+
+Everything durable is the CLI's own: `config.json`, `sessions/*.json`, `runs/*.jsonl`,
+`trajectories/<sessionId>.jsonl` (one sanitized per-session debug log of the model calls, appended
+across runs and resumes), and the OS-stored account session. Nothing the desktop does can put the
+two clients out of step, and a session started in the window resumes in the terminal with
+`/session`.
+
+## What the window does
+
+The window is the **rail** (projects and their tasks), the **surface** (the task conversation, or one
+of the other surfaces), and the **terminal drawer** along the bottom.
+
+A window opens on the **New task** screen — the project, branch, graph, permission, and model choices
+a task is written with — because a fresh window has no task open, and the conversation surface with
+nothing selected is an empty transcript. It is the same screen the rail's **New task** button and
+each project's plus open; selecting a task replaces it with that task's conversation.
+
+- **Rail.** Add a folder with the platform picker; every project is listed with its tasks nested
+  underneath, newest first and capped at five per project with **Show more** for the rest. A task
+  opens with a click, renames on a double-click, and deletes from its context menu; a project is
+  removed from its own context menu, and neither action touches the folder on disk. The search field
+  filters the loaded task list by name, last task, and project — it does not search conversation
+  text. The footer holds the account, the surface menu (task, code, runs, studio), the terminal
+  drawer's toggle, and settings. The rail is resizable: drag the divider on its right edge, or focus
+  it and use Left/Right arrows for 20px steps and Home/End for the current bounds. It ships at
+  248px, runs from 180px to 480px, and never takes more than half the window. The chosen width is
+  remembered in `andorra.desktop.railWidth`.
+- **Task.** The transcript is built from the runtime's own events: assistant messages, tool calls
+  with their arguments and results, and run notices. A completed run writes a turn row from the
+  record the engine saved. Approvals and clarification questions appear above the composer and block
+  the run until answered. The latest turn's observed span is shown above the composer as
+  "Worked for" ("Working for" while it runs); a restored session has no measured span and shows none.
+  The checklist a run publishes appears above that line — its own state beside the conversation, not
+  a message in it.
+- **Markdown.** Assistant messages and turn summaries are rendered as Markdown — headings, emphasis,
+  inline and fenced code, lists (including task lists), quotes, tables, and rules. No HTML is
+  generated or inserted, so a message can style the transcript but cannot add markup to the window;
+  raw HTML an agent writes is shown as text, and an image becomes its alt text and address rather
+  than a fetch from the transcript. A link copies its address when clicked instead of navigating,
+  since a message must not be able to replace the application with a page of its choosing. Text with
+  no markdown renders exactly as written, and the task text you typed is never reinterpreted.
+- **Composer.** One card: a text area over a row of quiet controls — permission mode (accented when
+  it is the mode that stops asking), graph, provider, model, and reasoning effort (which writes the
+  provider entry; OpenAI-compatible and OpenCode Go providers accept it, and the engine applies it only while a
+  run uses that provider's own model), then the run spinner, the context ring, and the send action,
+  which becomes stop while a run holds the engine. The graph control is locked on **Default** without
+  paid membership, because every other graph is refused by the run's own membership preflight. The
+  metrics strip beneath the card is described below.
+- **Model override.** A multi-agent graph whose nodes each name their own provider decides its
+  models by itself, which leaves the composer nothing to steer with. The **Override models** control
+  on the New task screen's row asks for a provider and a model and widens that pair to the whole
+  graph: every agent node of the run, its delegated subagents and its retry fallbacks all run it.
+  The control appears only where a run has more than one model decision to unify: a graph with
+  more than one agent node, or a path that names a provider or model of its own instead of
+  inheriting both from the session — a node that pins only a model, a retry fallback, or an
+  installed `specific`/`per-role` delegation. Those are the paths the ordinary model picker cannot
+  name, because it writes provider and model as one pair. The bundled Default runs one engineer
+  node beside its `end` marker, names nothing, disables delegation and has no fallback, so it
+  offers no override control. An override
+  that is already armed stays reachable on any graph, because its panel is the only way to clear it.
+  The
+  override belongs to the run, not to the graph — the saved graph keeps its own selections, and a
+  run without the override uses them again. The setting itself is per project and stays armed
+  until it is cleared, so every later task of that project runs on the same pair until **Clear**
+  says otherwise. Beyond that, the control is offered whenever the window cannot prove the engine
+  would refuse it, because the engines it holds may be from a build that is no longer on disk; a
+  start that asks for the override against an engine that cannot honour it is refused with the
+  reason, rather than silently running the graph's own models. A paired workspace is the exception:
+  its providers live on that machine, so an override cannot be chosen for it from here. The chat
+  screen's runs honour the same setting as well.
+- **Terminal drawer.** Shells in the project folder, running in the engine process through a PTY,
+  with their elapsed time, along the bottom of the window. It is opened from the rail footer or from
+  the Code surface's commit route, and it starts closed: revealing the section starts the first shell
+  and only the first, and a project switch closes the shells it holds, because a shell belongs to the
+  folder it was started in. Hiding the drawer keeps them: the views are hidden, never unmounted.
+- **Code.** The project's files, one file's contents, and the Git working tree with diffs — the
+  branch, the changed files with their status marks, and a per-file or whole-tree diff. This is where
+  the working tree is read. The surface reports and diffs only: there is no stage, commit, or push
+  action, so **Commit or push** on the Changes tab opens a terminal in the project folder, where git
+  runs with your own credentials and hooks. Reads go through the engine, which refuses a path
+  outside the project.
+- **Runs.** Every run record on the machine, including runs the terminal started: outcome, usage
+  including cache traffic, the graph the run used, the completion, and the event journal.
+  Right-clicking a run copies or reveals its stored record, and — when the engine writes session
+  trajectories — the session's own log beside it, so the debug log survives a resume where a single
+  run's journal restarts.
+- **Studio.** The graph list with selection, the extension inventory, and a button that opens the
+  graph editor inside the current Tauri window.
+- **Account.** The account portal: the profile the owner types, what their use has been, and their
+  plan. It opens from the account name in the rail footer and from **Account** in the rail's list.
+  The profile is stored with the account, so it follows the account to every machine that signs in;
+  the session and token totals are this machine's, because that is where the work ran.
+- **Automations.** Create recurring jobs that start fresh sessions in a local project with a saved
+  prompt, provider/model/graph and permission mode. Choose a five-field CRON expression or a daily
+  local time with an explicit IANA timezone. The page lists jobs created by you and by agents, with
+  edit, pause, delete, run-now and last-session controls. Agents use the provider-visible
+  `automations` tool; `set_timer` still continues the current conversation once. Jobs persist across
+  restarts, skip occurrences at least a minute overdue and never overlap themselves. They run while
+  Andorra is open, or while its optional background scheduler runs. **Start background scheduler**
+  keeps scheduling after the window closes; Windows **Start at sign-in** registers a per-user logon
+  task against the current CLI installation. Keep that installation path stable, and uninstall the
+  task before moving it. The computer must stay awake and signed in. Unattended sessions deny
+  approval prompts and stop for user questions; open the saved session to inspect the result.
+  A job's saved permission mode applies only to its own run. It does not change the project's
+  interactive permission default, including when the job fails or is interrupted.
+  Jobs created from a terminal agent retain that run's provider, model, graph selection and valid
+  reasoning effort, including command-line overrides.
+  See [the automation QA plan](../../tests/automations-test-plan.md) for exact commands and limits.
+- **Settings.** Account and membership, providers and models (with model discovery from the
+  endpoint), graph selection and an in-app **Open Graph Editor** button under **Graphs**, MCP and
+  extension inventory, runtime bounds, appearance, and **Analytics** — anonymous product
+  telemetry, which is included with the Free and Legacy plans and can be turned off by a Paid
+  account. The preference is stored in the same configuration file the CLI reads
+  (`/feedback on|off|status`); on a plan that includes collection, `/feedback off` explains why it
+  cannot be changed instead of writing a preference that has no effect.
+
+### Adding a model provider
+
+Open **Settings > Providers & Models > Add Provider** to search the preset catalog, then choose
+your provider. Official provider logos appear in A-Z name order, with Custom pinned first. AWS
+Bedrock (Mantle, Bedrock API bearer key) and Fireworks AI presets are included. Review the suggested
+identifier, endpoint and API type, add your credentials and
+model IDs, and select **Save provider**. Regional presets include guidance for matching the endpoint
+to your account. Subscription providers retain their fixed endpoints and sign-in behavior.
+**Create custom provider** opens the manual setup form for local servers or other endpoints.
+**Back to providers** lets you choose another preset after confirming draft disposal; nothing is
+stored until Save. Existing connections keep their Edit, model discovery and testing controls.
+
+See [the provider preset QA plan](../../tests/provider-presets-test-plan.md) for workflows and limits.
+
+For **Codex**, select **Sign in with ChatGPT** at the top of the form before selecting a model or
+saving a provider. Complete sign-in in your browser; the form shows waiting and cancellation controls,
+then verified account status and a model selector. A current official Codex CLI must be installed on
+this computer. It manages the subscription credentials used by inference. Existing Codex sign-in is
+reused; **Refresh sign-in status** reads it again. A verified connected account shows **Sign out**,
+which signs out the local Codex subscription without deleting provider settings or signing out your
+Andorra account. The same controls appear on saved Codex connections and their Edit form.
+
+The first successful catalog load in a new Codex setup adds all models returned by Codex, including
+hidden catalog entries, with its default selected unless you already chose a model. Refreshing keeps
+your configured list and manual selections; saved providers are not silently expanded. The catalog
+contains Codex models, which can differ from models available only in the ChatGPT website. A listed
+model does not establish inference entitlement. Model rows provide compact context-window controls.
+
+Browser sign-in is available for the local engine. For a remote workspace, sign in with the Codex CLI
+on the remote machine or switch to Local. See [the desktop ChatGPT sign-in QA plan](../../tests/codex-desktop-signin-test-plan.md)
+for compatibility, cancellation and verification details.
+
+### Embedded Graph Studio
+
+In **Settings → Graphs**, select **Open Graph Editor** to work in the full application content
+area. The same action is available from **Studio**. A Back button closes the editor and restores
+the Settings/Studio screen. The account-scoped graph list is refreshed after closing, so newly
+saved revisions can be selected immediately.
+
+The editor runs on a local loopback port and is shown inside the window rather than in an external
+browser tab. Its access token stays in memory and is never logged or persisted. The same editor is
+still available separately from the CLI with `andorra graph`; the CLI version needs the same
+framing allowance, or older engines will refuse to show it.
+
+### The metrics strip
+
+The strip under the composer reports the following, measured from the run's own events:
+
+```text
+3 turns · 12 steps | LLM 45.2s · Tool call 2m42s | 75.2 tok/s | Cache hit 95% | Input 12.2K tok · Output 3.4K tok
+```
+
+Groups are separated by a pipe and figures inside a group by a mid dot. A group whose measurement is
+missing is dropped whole rather than printed as a zero. Sources:
+
+| Figure | Source |
+| --- | --- |
+| Turns, steps | Assistant turns in the session record; iteration events for the run in flight. |
+| LLM time | Measured between an iteration starting and its model completion arriving. |
+| Tool time | Summed from each tool completion's own `durationMs`. |
+| tok/s | Output tokens over measured LLM time. |
+| Cache hit | Cache-read over prompt tokens, never rounded up to 100% while a miss exists; omitted entirely when the provider reported no cache traffic. |
+| Input / output | Session totals; the engine's saved usage is authoritative after each run. |
+
+Context occupancy lives on the ring beside the send button, and one fact has one home: the ring
+shows the last measured prompt size against the model's context window.
+
+## Accounts
+
+The window signs in through the same flow as `andorra login`: a browser opens the hosted sign-in
+page, and the callback returns to a loopback port. The session is stored in the operating system's
+credential store under the same identity, so signing in or out in one client is visible in the
+other. Signed-out use is fully supported for local providers; hosted decisions and premium features
+need the account.
+
+The account label in the rail footer names the plan — `Free`, `Legacy`, or `Paid` — and opens the
+account portal when pressed. **Legacy** is the pre-release cohort: free of charge, and carrying the
+same features as a paid account. See [Accounts](../getting-started/accounts.md#plans).
+
+## Remote Workspace
+
+Pairing this window to another machine — or another machine to this one — makes the paired window a
+full client of the other machine's engine: the same authority as a window opened on that machine.
+
+Shipped: pairing and the security model, read-only browsing of a browse-grant pairing, and — for a
+full-grant pairing over TLS where both ends speak the engine relay — the full client surface:
+sessions, tasks that run on the workstation, the streaming transcript, approvals and questions,
+stop and resume, terminals, and workspace reads, as if the window sat at that machine.
+
+From the CLI, the same feature is `andorra remote serve` on the machine you want to drive,
+`andorra remote pair <pairing-code>` on the machine that drives it, and `andorra remote devices`,
+`revoke`, `status`, `code`, `share`, `unshare`, `workspaces`, `unpair` and `rotate-cert` to manage
+pairings and sharing. See [CLI](../reference/cli.md).
+
+## Known limits
+
+- A remote window's authority follows its pairing: browse-only pairings (including credentials
+  minted before the grant model) stay read-only with a pill that says so, and the message names
+  the fix — a full-access code from the host's Settings, or the owner granting full access there.
+  A host whose Andorra predates the relay, or a window whose installed CLI cannot proxy, says
+  which side to update.
+- Remote tasks run on the paired machine's own engine pool, so a paired window does not spend a
+  local engine on them; attachments cannot travel to the paired machine yet and are refused with a
+  message before the start, and the graph editor and host engine logs are not proxied yet.
+- One task per engine, and the window runs an engine per task in flight. Two tasks in the same
+  project share one working tree, so concurrent tasks belong in different projects or worktrees.
+- A window reload does not attach to a run in progress. The completed turns are re-read from the
+  session record, and the engine the run is in finishes it and writes that turn.
+- Steering a run while it is live, and pausing one, are not exposed yet; the engine supports
+  cancellation and the approval exchange. Continuing a stopped attempt is: the Resume control
+  continues it as it was, and a message typed after the stop continues it with that text as its
+  direction. Only the message falls back: when the engine answers that there is nothing left to
+  continue, the text becomes a new run in a forked session, because it is a new task in its own
+  right. The bare Resume control has no new task to turn into, so the same answer is reported as
+  an error — restarting the stopped attempt's own task over is exactly what Resume must not do.
+- The in-app graph editor uses the CLI's local Graph Studio server inside a sandboxed Tauri frame.
+  It is not a second graph implementation and does not open an external browser tab. The same editor
+  is still available separately from the CLI with `andorra graph`.
+- Extension and MCP editing is read-only in the window for now.

package/docs/guides/extensions.md

@@ -0,0 +1,100 @@
+# Skills, MCP servers, plugins, and sign-out
+
+Start `andorra` in a terminal after configuring a provider in `/providers`. Type `/skills`, `/mcp`, or `/plugins`; use Up/Down and Enter to select, and Escape to return. These commands also appear in slash completion and `/help`. Changes apply to the next task. Configuration updates retain provider, memory, code intelligence, and limit settings in `config.json`.
+
+The default home is `%USERPROFILE%\.andorracode` on Windows and `~/.andorracode` elsewhere. `ANDORRACODE_HOME` overrides the whole directory. Skill files live in `skills/`, plugins in `plugins/`, and disabled ids plus directly configured MCP servers in `config.json`.
+
+## Skills
+
+Choose **List skills** to inspect installed names, descriptions, status and paths. Select a skill to enable, disable or uninstall it. Choose **Install skill** and enter a local directory containing `SKILL.md`, a GitHub repository with `SKILL.md` at its root, or a GitHub subdirectory URL, for example `https://github.com/owner/repo/tree/main/skills/example`. Repository URLs accept `#branch-or-tag`; tree URLs require a single-segment ref (use a local checkout for refs containing slashes). A GitHub installation requires network access and a publicly accessible GitHub archive. For private repositories, use an authenticated local checkout and install its directory. The source directory or selected subdirectory name becomes the skill id; existing ids are rejected rather than overwritten.
+
+Example local directory:
+
+```text
+example/
+  SKILL.md
+  references/style.md
+```
+
+```markdown
+---
+name: example
+description: Apply the project's writing conventions.
+---
+Read references/style.md before editing documentation.
+```
+
+At each task the harness discovers enabled skill metadata. To bound prompt size, it advertises at most 16 skill descriptions, but can resolve up to 512 installed skills on demand using the `Skill` tool or `read_skill_resource` with `{"skill":"example","path":"SKILL.md"}`. Supply an exact installed ID (recommended), or a unique skill name; ambiguous names fail with an error requiring an ID. For a repository import such as pstack, a skill may also read a sibling `../how/SKILL.md`, but only while that sibling is installed and enabled. Cross-repository, disabled-sibling, unknown-directory, and symlink escapes are rejected. Loading a sibling `SKILL.md` activates the sibling's canonical ID for graph inheritance. Reads remain bounded to 128 KiB and never execute scripts or grant new tools. The Orchestrator must publish its plan before reading skills and still needs repository evidence and user confirmation before implementation. Disable removes discovery and access at the next task; uninstall removes the copied directory, retaining the original source.
+
+Installation copies local files or downloads a GitHub repository archive. GitHub downloads are bounded to 64 MiB compressed and 80 MiB expanded in memory before extraction; these archive limits include repository content outside a selected subdirectory. Use a local checkout for a larger repository. Only the validated selected bundle is written to staging, with at most 10,000 entries and 64 MiB of file content. Executable file permissions are retained where supported. It never executes package installers or hooks. Links, special files, bundles exceeding 10,000 entries or 64 MiB, and documents exceeding 128 KiB are rejected. Unreadable or malformed bundles are shown as unavailable and can be uninstalled; they do not block other tasks.
+
+Discovery validates at most 128 visible bundles per directory, in name order, with at most four concurrent bundle validations. Both task startup and manager screens report omitted entries; remove unused folders from the indicated directory to make room. Local sources containing the extension directory are rejected before scanning their contents, including paths resolved through directory aliases.
+
+## MCP servers
+
+Choose **Add MCP server**, enter a unique name, and select **Local command (stdio)** or **Streamable HTTP**. Select an existing server to edit, delete, enable or disable it. Enter arguments as a JSON array; environment or HTTP headers as a JSON object. Blank entries retain current fields when editing, while `[]` or `{}` clears them. Avoid entering raw credentials: use `${ENV_VAR}` placeholders, resolved from the CLI's process environment for env values and headers at task start. Environment/header input is concealed and excluded from input history; placeholders also keep secrets out of saved configuration. Authentication currently supports request headers, such as an Authorization bearer header, rather than an interactive MCP OAuth flow.
+
+Stdio processes receive the SDK's minimal execution environment (such as PATH and platform home/system paths), plus only the environment entries configured for that server. Unrelated provider and cloud variables are not inherited. Explicit `${ENV_VAR}` references supply only their configured destination entries.
+
+Example configuration (merge these fields with your existing provider configuration):
+
+```json
+{
+  "mcpServers": {
+    "local": {
+      "transport": "stdio",
+      "command": "node",
+      "args": ["C:/tools/example/server.mjs"],
+      "env": { "EXAMPLE_TOKEN": "${EXAMPLE_TOKEN}" },
+      "enabled": true
+    },
+    "remote": {
+      "transport": "http",
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ${EXAMPLE_TOKEN}" },
+      "enabled": false
+    }
+  }
+}
+```
+
+Public HTTP endpoints require HTTPS; private/local networks can use HTTP. URL credentials are rejected. The official MCP TypeScript SDK handles initialization, tool discovery, tool calls, and Streamable HTTP sessions. Legacy SSE-only endpoints are unsupported. Connection and individual discovery requests are bounded to 15 seconds, overall discovery to 30 seconds and 100 pages, and tool calls to 60 seconds. Server failures produce a visible unavailable status while the task continues. Missing auth environment variables also make that server unavailable. StdIO stderr is drained without copying potentially secret server messages into the transcript.
+
+Enabled servers connect once per task. Startup attempts at most eight enabled servers in configuration order, including plugin servers; failed connections and empty catalogs count toward this limit, while disabled servers do not. Additional servers are skipped with a visible notice. Disable unused servers to make room on the next task. Connection and every tool call use the existing approval policy: interactive approval, automatic approval in YOLO, and denial in headless mode without YOLO. Processes run as the local user; approval is not an OS sandbox. MCP tools use server-prefixed names with a hash to avoid collisions. Arbitrary external tools are offered only to agents with `shell: "allowed"`, because server read-only hints do not establish their effects. Orchestrators and read-only agents cannot call them. Agents with an explicit built-in `tools` allowlist exclude dynamically discovered MCP tools; use a full-capability agent without that list. Restricted subagents do not automatically inherit external tools. `/tools` describes discovery; the task's MCP connection notices report discovered counts. Pausing an established run cancels its in-flight tool call but keeps clients connected, so new direction can resume tool calls without reconnecting. Pausing during connection or discovery cancels startup and retries after new direction. Closing or cancelling the task closes its SDK clients and local processes.
+
+MCP incoming transport data is capped at 1 MiB before JSON parsing: the stdio pending message buffer and each HTTP response body, including error bodies and SSE streams. Oversized data closes the connection and fails pending calls. Long-lived SSE streams also close after this cumulative limit; start a new task to reconnect. Tool output is separately clipped to 32,768 characters after parsing a bounded response.
+
+Task-owned MCP clients are not inherited by any subagent, including roles with shell access or `toolInheritance: "inherit"`. Their working directory belongs to the parent task; excluding them preserves child workspace isolation. Use the parent agent for MCP calls.
+
+## Plugins
+
+Plugins use the same install/list/enable/disable/uninstall workflow. A plugin directory contains `andorra-plugin.json`, referring to included skills and optional MCP servers:
+
+```json
+{
+  "name": "Example plugin",
+  "description": "Writing guidance and a local helper",
+  "skills": ["skills/writing"],
+  "mcpServers": {
+    "helper": {
+      "transport": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/server.mjs"]
+    }
+  }
+}
+```
+
+Each skill directory must contain `SKILL.md`; paths must stay inside the plugin. A plugin may reference at most 16 unique skill directories; repeated paths and aliases are validated and advertised once. Exceeding this limit rejects installation or marks an existing plugin unavailable. Cancelling discovery or installation stops subsequent document reads. `${PLUGIN_ROOT}` expands literally to the installed directory in stdio command, arguments and environment values, including dollar characters in the path. MCP processes still use the task workspace as their working directory. Plugin tools and skills disappear from the next task when the plugin is disabled or removed. Plugin server ids and skill ids are namespaced separately from direct installations. Plugin libraries are not imported into the CLI, and arbitrary plugin entry points are not executed. This is Andorra's documented bundle format, not a Codex marketplace compatibility layer.
+
+A plugin may declare at most eight unique MCP server ids, including disabled servers. Excessive declarations reject installation or mark an installed plugin unavailable before server validation or nested skill reads. Disabled bundles are skipped before document validation during task startup; the managers still validate and display them for repair. Disabled bundles do not consume runtime discovery slots. HTTP connection approval details omit URL query parameters while transport requests retain the configured URL.
+
+## Logout
+
+`/logout` (like `/auth logout` and standalone `andorra logout`) removes your Andorra account session and never signs out of a provider; run `/login` afterwards to sign in to the same or another account.
+
+`/logout codex` signs out of every configured Codex account and exits the session after verifying sign-out, whichever provider is active. It uses the official app-server `account/logout` request for each account home, including the shared default Codex ChatGPT account. It retains provider settings, configured API-key environment names and environment variables. Open `/providers`, select the Codex provider and use its edit/sign-in flow to sign in again. With no Codex provider configured it reports that there is nothing to sign out of and leaves the session open; no API keys are deleted. Ctrl+C cancels a pending sign-out; a failed sign-out leaves the session open with an actionable status.
+
+## Validation
+
+See [the executable QA plan](../../tests/harness-extensions-test-plan.md) for coverage, commands and pending live integrations.