@andorra-labs/code 0.0.0-stage → 0.1.5

package/docs/guides/graph-builder.md

@@ -0,0 +1,93 @@
+# Graph Builder
+
+The Graph Builder is a local browser application for composing custom graphs: agents with their own instructions, models, and tools, wired together with typed handoffs, conditions, loops, and joins. A free account can save one custom graph of up to 3 nodes (Done does not count) without the Orchestrator; the Create graph button is disabled once it has one. Paid membership lifts both limits.
+
+It is the editor for people. An agent should author and edit graphs through the local MCP server instead — the same store, the same validation and revisions, driven by tool calls instead of a canvas. See [Agent MCP server](../agents/mcp-server.md); use this page for hands-on editing and for showing a graph to a person.
+
+## Opening it
+
+Run `andorra`, open `/providers`, and choose **Add provider** if nothing is configured yet — missing or empty provider configuration directs you to `/providers` before anything opens (this checks saved configuration, not live connectivity). Then:
+
+```sh
+andorra graph            # start the local server and open your browser
+andorra graph --no-open  # print the launch URL instead
+```
+
+The URL grants access to the local editor for this server session — keep it private. Ctrl+C shuts down the server; closing the tab leaves it running. Graphs are stored in `~/.andorracode/graphs` (or under `ANDORRACODE_HOME`). From inside the TUI, `/graph` selects saved graphs, and its **Edit Graphs** action opens this builder; `/graph` → **Create new graph** starts a new draft.
+
+## Building a graph
+
+The searchable Node Library creates Agents manually or from editable shared presets. Use the Inspector for instruction/model, completion outcomes, capabilities, context, typed input/output contracts, subagent roles and budgets. Click or drag an Agent onto the canvas (drop coordinates account for pan and zoom). Outcome ports can connect to multiple nodes; Join all/any expresses synchronization. Select an edge to configure explicit input mappings. Every Agent owns an independent executor invocation.
+
+New graphs start with an optional Orchestrator that inspects the codebase and asks about requirements and design choices before handing work to its configured successor. Select it and use Remove node or Delete to start directly at its successor instead. When deleting any starting node, the first surviving outgoing connection supplies the new start; if none survives, the first remaining node in the node list becomes the start. Undo restores the node, connections and previous start together. Version 3 graphs saved without an Orchestrator keep their ordinary starting node when reopened or run.
+
+Structured inputs pass through explicit `$source.output.field`/`$run.input.task` mappings or constants. Cycles require a finite graph visit limit. Child capabilities cannot exceed the parent; shared read-only and isolated worktree policies are enforced at runtime. Custom graphs with extra required run inputs or initial shared state can receive JSON object files:
+
+```sh
+andorra --graph my-workflow --prompt "Verify staging" --run-input inputs.json --run-state state.json
+```
+
+For example, `inputs.json` can contain `{"environment":"staging"}` and `state.json` can contain `{"ticket":123}`. The runtime validates both against the selected graph contracts before invoking its entry node. Do not put credentials in handoff data.
+
+## Modifiers and concurrency
+
+Condition, Loop, and Parallel are optional Agent modifiers. Condition routes matching output fields to true and nonmatching output to false. Loop repeats an agent until its configured outcome or output value matches, bounded by Maximum attempts; exhaustion stops instead of reporting success. Parallel has two modes — directly connected downstream Agents, or independent read-only copies of the same Agent — each honoring its own concurrency cap and the graph ceiling, including nested copies. Copy results appear in `output.results` in copy-index order; all copies must return the same outcome, and copies cannot write to the shared workspace. Ordinary top-level stages run serially.
+
+Concurrent siblings and copies receive fixed shares of the remaining token/tool budget; unused shares are not redistributed. Budget exhaustion or cancellation stops new work and prevents a successful downstream handoff.
+
+## Route frontend, backend, and DevOps work
+
+All branches belong to the same graph canvas. Select the Orchestrator, find **Routing** outside Advanced, and set **Routing behavior** to **Choose outcome using written criteria**. Configure outcome names and their **Written criteria for <outcome>** fields:
+
+| Outcome name | Written criteria |
+| --- | --- |
+| `frontend` | Choose when the confirmed request requires UI, styling, or browser interaction changes without backend changes. |
+| `backend` | Choose when the confirmed request requires API, database, or server behavior changes without frontend changes. |
+| `devops` | Choose when the confirmed request concerns GitHub Actions or infrastructure configuration. |
+| `fullstack` | Choose when the confirmed request requires both frontend and backend changes. |
+
+Keep the shared intake instructions in the Orchestrator's **Prompt**, for example:
+
+> Research the request and confirm its acceptance criteria with the user. Ask for clarification when the scope is ambiguous. Choose exactly one outcome using its written criteria. Hand off the confirmed task, relevant files, acceptance criteria, and verification requirements. Do not implement or deploy during intake.
+
+Add Agents named Frontend Software Engineer, Frontend QA, Backend Software Engineer, Backend QA, and DevOps, each with its own task instructions and verification criteria. Connect the Orchestrator's outcomes to the engineers/DevOps (`fullstack` connects to both engineers). Connect each engineer's `completed` output to its QA node; give each QA `pass`/`fail`/`blocked` outcomes with written criteria; connect `pass` to Done, `fail` back to its engineer, and `blocked` to a separate End node. Because the fail routes create cycles, set **Graph → Maximum visits per node**, for example to `3`. Use a Join if a later stage must wait for multiple branch results.
+
+Written criteria guide the model's judgment; they are not automatic assertions or permission grants. A blank criteria field falls back to the node's Prompt. Keep **Require a route for every outcome** enabled. Naming a node "DevOps" grants no access — configure **Advanced → Permissions** for the actual task. Test the routing with a dry-run prompt before authorizing external changes.
+
+## Reuse conversation between Agent stages
+
+The visible **Conversation** selector defaults to **Reuse with the same provider and model**. A direct Agent-to-Agent handoff can carry the preceding conversation, including tool calls and results, when both resolve to the same provider profile and model. The next node gets its current role instructions and task, its own permitted tools, and fresh per-node execution counters. Reuse does not give QA the engineer's write permissions or reset shared graph budgets.
+
+Choose **Start an isolated conversation** to prevent reuse into and out of that node. Fan-out destinations receive separate snapshots of the shared predecessor history. Joins, intervening control/action nodes, and convergence of pending activations conservatively start isolated conversations. **Advanced → Context sharing → Include previous task summaries** controls summaries from earlier user tasks; it is separate from this run's conversation reuse.
+
+## Skill inheritance between graph nodes
+
+The **Skill inheritance** selector on each Agent defaults to **Inherit active workflow skills**. Explicit slash-invoked skills at run entry, and skills successfully loaded via `Skill` or `read_skill_resource` during the run, become available to later Agent nodes as active skill references. This context is separate from conversation history: it survives isolated conversations, different providers or models, control nodes, and parallel branches.
+
+A receiving Agent is instructed to load each inherited skill before doing its own work, and to apply it to **its own role only**, rather than restarting the previous Agent's playbook. Skill content is still untrusted task reference data. It cannot expand the node's tools, permissions, or approval authority. Missing required skills surface as execution errors rather than silently dropping the workflow mode.
+
+Select **Do not inherit skills** on a node to keep that node's skill context independent. This also suppresses explicit slash-skill guidance and predecessor conversation reuse for that node, so a prior skill body cannot leak through the transcript. It does not disable installed skills or prevent the node from choosing its own skills. Active skill IDs are journaled so a stopped run resumes with the same inherited workflow references. A skill activated in one branch is run-wide for later graph nodes; use node opt-outs for roles that must not receive it.
+
+## Editor usability
+
+- The editor renders the same appearance as the Andorra Code desktop client: the same surfaces, type and measurements, in dark. It follows your operating system's light or dark preference, and the **Light** or **Dark** button in the status bar switches it and remembers the choice for the session. Opened inside the desktop client, the editor takes the client's appearance and offers no switch of its own.
+- Drag the left sidebar's right edge to resize it (or focus **Resize library sidebar** and use Left/Right, Home, End). The browser remembers the width.
+- The **Agents** section lists built-in presets first and saved variants after, all at one level. **Copy** on any Agent row creates a new Agent starting from that row's settings under a name you choose.
+- Library changes save independently of graph revisions and do not change nodes already on the canvas. Save a selected node as a named variant from the Agent inspector.
+- Select a node or connection and press Delete to remove it, then Undo to restore. Delete inside a text field edits text. Deleting every remaining node is prevented so the draft retains a start.
+- Connections use orthogonal routes around node cards and indicate direction with arrowheads. Separate overlapping cards when their ports are enclosed by another card. If a return edge creates an unbounded cycle, the inspector explains it and offers a finite visit limit.
+- Ctrl-click (Cmd-click on macOS) matching node types to select several nodes. Under Output Node, select their shared outcome and use Route all N to, then click the destination.
+
+Schema versions 1/2 remain executable with their original semantics; opening them in the editor adds an Orchestrator before the existing entry, and saving creates a version 3+ revision without rewriting history.
+
+## Cloud backup and draft recovery
+
+For paid accounts, the graph builder saves revisions and drafts locally, then automatically synchronizes them to your Andorra account. The sidebar reports cloud status separately from local save success; connection failures retain the local queue and retry every 30 seconds while the builder is open. Open the Graph Builder to refresh cloud graphs on another installation; in the desktop app, opening a task's graph list does the same, so a graph saved on another machine is listed there without opening the builder first.
+
+Incomplete graphs are autosaved as drafts after a short pause, even when validation prevents saving an executable revision. Open a draft from the sidebar, or choose **Show draft history** for earlier and conflicting versions. Remote revisions keep their original IDs and history; a conflicting revision is preserved as a separate graph — existing files are never silently overwritten.
+
+The first paid graph refresh assigns existing local graphs to the current account. Later accounts on the same installation use separate graph directories. Cloud storage is private to the verified account. Agent-library definitions and model credentials are not synchronized; configure the required model profiles on each installation. Starting the builder requires an online paid-membership check.
+
+## Model health
+
+Loading a graph checks each model with a small inference request, including agent overrides, retry fallbacks, and enabled subagent roles. Unavailable models are listed with their affected nodes and tasks are blocked; open `/graph` → **Edit Graphs** to repair the selections. Each probe has a 30-second deadline and may consume provider quota.

package/docs/guides/headless.md

@@ -0,0 +1,45 @@
+# Headless mode
+
+Headless mode runs one task non-interactively: no TUI, one result, machine-readable output. It is the right surface for scripts, CI, and other agents.
+
+## Usage
+
+```sh
+andorra --prompt "Explain this repository" --provider local --model your-model
+andorra --prompt "Fix the failing test" --yolo --json
+andorra --prompt "Fix the failing test" --yolo --json --jev off   # this run without Jev; the saved preference is unchanged
+andorra --prompt "Ship it" --no-tui --json --graph my-workflow \
+  --run-input inputs.json --run-state state.json
+```
+
+`--no-tui --prompt ...` and `--json --prompt ...` are both accepted. `--json` emits one result object on stdout with status, run ID, graph revision, completion, usage, and tool count. Startup errors go to stderr.
+
+## Subagent runs
+
+`andorra subagent` is a narrower contract for agents that drive Andorra (Claude CLI, Codex CLI, a
+script): it runs only the built-in Software Engineer graph, and it requires a provider/model —
+either per call or from the saved `/subagent` setting. Without one it answers
+`PROVIDER_NOT_SET` with the list of configured providers and models, so the calling agent can ask
+its user and retry. See [Subagent mode](../agents/subagent-mode.md).
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Failure, limit exhaustion, or `needs_clarification`. |
+| `130` | Cancellation (Ctrl+C). |
+
+## `needs_clarification`
+
+Graphs that start with an Orchestrator — the paid Andorra workflow (`--graph :andorra`) or custom graphs that keep intake — return `needs_clarification` with exit code 1, because the intake answer is interactive. The default graph is a single Software Engineer agent and does not require intake. Use `andorra` or `andorra --graph <id>` interactively to answer Orchestrator intake. A noninteractive clarification input/resume protocol is not included yet.
+
+## Permissions
+
+Without `--yolo`, headless writes and shell calls receive a permission-denied observation because no interactive approver is present; read tools remain usable. `--yolo` applies session-wide automatic approval and retains tool allowlists, argument checks, and containment.
+
+One exception: a workspace with a **saved Full-Access permission mode** (`/permissions full-access`) restores automatic approvals at startup even in headless runs without `--yolo`. For automation that must not mutate a workspace, reset the saved mode with `/permissions` first, or point the run at an isolated configuration home with `ANDORRACODE_HOME`.
+
+## Headless notes
+
+Headless runs use the saved model configuration without the interactive context-window discovery refresh. Custom graphs can receive `--run-input`/`--run-state` JSON files (see [Graph Builder](graph-builder.md)).

package/docs/guides/tui.md

@@ -0,0 +1,75 @@
+# The TUI
+
+The default `andorra` command opens a full-screen terminal UI: a welcome panel, conversation and tool transcript, a bordered input composer, and a live status bar. While a task runs, the transcript shows public assistant progress, tool actions, and compact result previews.
+
+- Press **Ctrl+O** to expand or collapse tool and approval details.
+- Scroll with Page Up/Page Down, or with the mouse wheel/trackpad while a run streams or a screen is open. Select text by dragging, as in any terminal program.
+- File proposals show numbered green additions and red removals; edit numbers are relative to the replaced snippets. Errors are red and tool headings are cyan. Approval prompts retain the full arguments in expandable details.
+- Updates appear after each model response; token-by-token streaming is not supported. `--json` remains machine-readable and does not include display formatting.
+- Text wraps at word boundaries where possible; tokens wider than the terminal still split safely.
+
+## Welcome panel and footer
+
+The welcome panel uses an Andorra ASCII wordmark and shows your workspace, session, and graph. It scrolls upward as messages arrive. The footer keeps the selected provider/model, Git branch, approval mode, activity, provider-reported session usage, the known context window, the selected graph (`Graph: Default` until changed with `/graph`), the permissions profile, and the configured thinking effort visible. Session token totals are cumulative usage, not a measurement of the current context fill.
+
+Once a run's first request completes, the usage line also shows generation speed as `· N tok/s`, held between LLM calls (providers report token counts only as a request finishes; the footer keeps the previous value rather than dropping or aging it toward zero). The number is a request average spread over the seconds the request ran — a response that burst its tokens at the end and one that trickled them read the same — and only provider-reported totals are used, never estimates. It is absent at idle, while a run's first request is in flight, and after a run ends or is cancelled.
+
+## Composer, questions, and approvals
+
+Agent questions and tool approvals replace the composer with a selection menu. Use Up/Down and Enter to answer, or Escape to cancel; questions include a custom-answer option. While execution is active, a gray/white animated Working indicator and elapsed time appear above the composer; it pauses while waiting for input. While a run streams with no prompt pending, Up/Down scroll the transcript alongside Page Up/Page Down.
+
+Type `/` as the first character to open command suggestions. Typing filters the list; Up/Down highlights a match, Enter runs the highlighted command, and Tab fills it into the composer so an argument can be added by hand. Use arrow keys to edit, Up/Down for input history, and Enter to submit. Pasted multiline text stays in the composer until you submit it.
+
+**Ctrl+C** stops the active run (paused runs resume from your next message); Ctrl+C again — or a press while idle — exits, with a hard-exit backstop if a run refuses to unwind. **Ctrl+D** exits from an empty prompt. Terminal resizing adjusts the layout, and exiting restores the terminal.
+
+## Mouse, selection and scrolling
+
+Andorra never captures the mouse. Drag-to-select, double-click word selection and your terminal's copy shortcut work in every state — at the idle prompt, while a run streams, and while a selection or settings screen is open — with no Shift or Option bypass to remember. The composer additionally has its own keyboard selection (Shift with an arrow, Home or End; Ctrl+C copies, Ctrl+X cuts).
+
+What the wheel does depends on where you are:
+
+- **While a run streams** with no question on screen, the wheel scrolls the transcript. Up/Down and Page Up/Page Down do the same from the keyboard. If you have started typing a steer, Up/Down move inside that draft instead; the wheel and Page Up/Page Down still scroll.
+- **On a selection, settings or usage screen**, the wheel scrolls the screen or moves the highlight, like Up/Down.
+- **At the resting prompt**, and while an approval or clarification question is open, the wheel does nothing. Up/Down recall input history there, and Page Up/Page Down scroll the transcript.
+
+The reason for the resting-prompt exception is how terminals report an uncaptured wheel in a full-screen program: under *alternate scroll mode* they send the same bytes as the Up and Down keys. Windows Terminal, GNOME Terminal and iTerm2 have that mode on by default, which once made the wheel recall the previous prompt. Andorra therefore switches the mode on only in the states above, where Up/Down cannot reach history, and off everywhere else. A terminal that ignores the mode request and always translates the wheel will still recall history on wheel-up at the prompt; a terminal that never translates it has an inert wheel during runs, where Page Up/Page Down and the arrow keys still work.
+
+Collapsed long-prompt boxes expand and collapse with Ctrl+O, and the live reasoning preview toggles with Ctrl+Y. Dragging works while a task runs: the screen redraws eight times a second for its animation, but only the rows whose text actually changed are rewritten, so an unchanged row is never refreshed out from under your selection. Rows that do change — the animated indicator and counters — may move your selection with them, as in any terminal.
+
+## Selection screens
+
+`/model`, `/providers`, and `/graph` open dedicated selection screens. Use Up/Down to browse, Enter or Space to choose, and Escape to return without changing the selection. The model screen fetches the active provider's available models; Escape also cancels loading. `/usage` opens a usage screen with Escape to return. `/yolo on` and `/yolo off` set the session boolean immediately (a bare `/yolo` only reports it); the bottom-left footer reads **Yolo mode is on** when approvals are bypassed. Choosing a graph other than the one in use opens a confirmation first, because switching clears the previous graph progress and starts fresh.
+
+A settings list that asks for a typed value — an API key, endpoint URL, provider name, model ID, or context window — keeps the list on display with its highlighted entry and opens the bordered input bar underneath it. Escape in that bar discards only the typed value and returns to the same list.
+
+## Side panel
+
+On a terminal at least 110 columns wide and 14 rows tall, a status panel is drawn to the right of the conversation, separated by a vertical divider. It is display only — no key or click reaches it — and it reports, from the top:
+
+- **Git tools** — the working tree's `+insertions −deletions`, the current branch, and how many tracked files are changed plus untracked entries. A clean tree reads `clean`; a non-repository says so. Refreshes when a run starts, ends, and after each tool completion, throttled to one read every two seconds.
+- **Node** — the graph node the run is on, with `loop i/n` and `copy i/n` when the graph loops or runs copies, and the provider/model that node actually resolved. At idle it shows the selected graph's entry node.
+- **Progress** and **Plan** — the run's plan: a completion bar with `done · active · waiting` counts, then the item in progress, the completed count, and the waiting items. While the panel is drawn the composer's own Todo block stands down, so the plan is reported once.
+- **Terminals** — background sessions the agent opened through `qa.terminal`, with how long each running one has been alive.
+- **Graph** — for a **custom** graph only, a zoomed neighbourhood of the current node: what feeds into it, the node itself, and what it hands off to, each labelled `✓` visited, `●` current or `○` not yet reached, with hand-off outcomes. The trail stays after the run ends and clears when the next run starts.
+
+Below 110 columns, below 14 rows, in the dashboard (Ctrl+B), and while a selection or settings screen is open, the panel is not drawn and the chat column uses the full width with the usual Todo block.
+
+## Todo progress
+
+The Todo panel shows the current run's plan: pending, in progress, and completed items. The Orchestrator sets the initial plan, and later Agent stages update it as they work. Completed items remain visible; a stopped or failed run keeps unfinished items unfinished.
+
+The compact panel shows up to five items with a remaining-item and completed-item count. Press **Ctrl+T** to expand or collapse the list; in the expanded panel, Page Up/Page Down scrolls longer plans. Ctrl+O separately controls transcript details. A new run or `/clear` clears the previous plan, and `/clear` also wipes the on-screen conversation. On a terminal wide enough for the side panel, the plan is reported there instead and this block is not drawn.
+
+Todo updates are recorded with the run events and rendered as text outside the full-screen terminal. They describe reported progress, not independent proof that tests or implementation succeeded.
+
+## Dashboard
+
+Type `/dashboard` and press Enter at the task prompt or while steering an active run. The view remains selected across tasks until toggled. **Ctrl+B** switches between the dashboard and the original transcript without resetting the task or changing a typed draft. Routine messages and tool observations remain in transcript history; questions, errors and final summaries appear above the input. Long notices show an explicit continuation indicator; Ctrl+B opens the transcript for their full text. Approval and clarification options still use Up/Down and Enter, and Ctrl+C still cancels the run.
+
+The token card segregates session totals by provider ID and actual requested model, including node overrides, fallback models and delegated requests. **Ctrl+N** cycles the displayed provider/model; it does not change execution settings. Missing provider usage remains **Unavailable**; explicit reported zero displays as zero. Speed is output tokens divided by completed model-request wall time, including network/request overhead. There are no pricing estimates.
+
+Elapsed time covers the current task (including time waiting for answers), or the latest finished task. LLM and tool durations are sums of operation wall time, so overlapping parallel calls can exceed elapsed time. Tool time includes the entire tool call, including approval and `ask_user` waiting. A new task resets task timing and todos while retaining session token totals.
+
+The Todo card shows completed, active and pending counts and then the items, unfinished first: `●` in progress, `○` pending, `✓` completed; Page Up/Page Down pages it. The graph card shows every active node plus direct incoming and outgoing neighbours, with each node name and effective provider/model on separate lines, then the edges between them as `source → target` and a count of the distant nodes left out. Active nodes are marked `●` in the accent, neighbours `○`. At idle, the entry carries the mark and the legend says so. **Ctrl+G** pages the card one row at a time; a neighbourhood that fits is shown whole, and one that does not keeps its last row for the page range.
+
+The cards share the composer's rounded frame: each title sits in the top edge with its key hint against the right corner, readouts keep their values in one column, and the two cards of a row end on the same line. At 80 columns by 24 rows, four cards share two columns above the composer, with the latest question, error or result on the row beneath them. Expanded windows give the Todo and graph cards the extra rows; narrow/short windows stack the cards and shorten them, preserving editable input and question selection. A value that cannot fit its card is cut with `…`. Dashboard state is local to the running terminal session and is not saved across process restarts.

package/docs/guides/update.md

@@ -0,0 +1,68 @@
+# Update
+
+`andorra` does not check for updates on launch — updates are explicit.
+
+## `andorra update`
+
+Run from any directory:
+
+```powershell
+andorra update
+```
+
+This asks npm which release the `latest` tag of `@andorra-labs/code` names and, when it is newer than the installed version, installs exactly that version globally with `npm install -g @andorra-labs/code@<version>`. It uses the npm that ships with the Node.js running Andorra, and it updates the global installation that provides the command, regardless of your current project directory.
+
+- When the installed version is already the latest, nothing is installed: `Andorra 0.1.4 is already the latest release on npm; nothing was installed.`
+- It never downgrades. If the `latest` tag points at an older release than the one installed, nothing changes and the message says so.
+- If npm cannot be reached, nothing changes; fix the network or registry settings and run it again.
+
+Requirements:
+
+- The `andorra` command must be the global npm installation, `npm install -g @andorra-labs/code`.
+- It refuses, without changing anything, when `andorra` runs from a source checkout — one linked with `npm link`, or started as `node dist/src/cli.js` — and when it runs from any other copy, such as a project's own dependency or the desktop client's engine. The message names the path and the command to use instead.
+
+### Switching from a source checkout
+
+An installation made by cloning the repository and running `npm link` is not updated by `andorra update`. To move it to the npm release:
+
+```sh
+npm install -g @andorra-labs/code@latest
+```
+
+That replaces the linked global command with the published package. The checkout itself is left as it is. To keep running the checkout instead, update it yourself from the checkout:
+
+```sh
+git pull --ff-only
+npm ci
+npm run build
+```
+
+## A failed or blocked update
+
+Before npm touches anything, the update checks that the installed package can be moved, because npm replaces it by moving it aside. On Windows a terminal or program whose working directory is inside the package keeps it in place; the update then refuses, names the path, and changes nothing. Close that program and run `andorra update` again.
+
+Another Andorra session or CodeGraph that has a native module of the old release loaded does not block the update: npm installs the new release, but cannot delete the old copy it moved aside (`@andorra-labs/.code-<random>` beside the package) while that process runs, and warns about it. The update names that copy. It is no longer used by the `andorra` command, and the next `andorra update` deletes it once the process holding it has exited.
+
+When `npm install` itself fails, npm moves the previous release back, and the message says which version is still installed. A failure that looks like a brief Windows sharing violation is retried a few times first.
+
+## An interrupted update
+
+While it runs, `andorra update` holds a lock file, `update.lock` in the Andorra home directory (`~/.andorracode`, or `ANDORRACODE_HOME` when set), so two updates cannot run at once. The lock records the updater's process id. If an update is cancelled with Ctrl+C, its terminal is closed, or it crashes, the lock stays behind.
+
+Run `andorra update` again. When the process the lock names has exited, the update removes the stale lock, prints `Removed a stale update lock left by process …`, and continues.
+
+The update refuses to start when the lock names a process that is still running, or when the lock is empty or unreadable. If you are sure no update is running (a process id can be reused by an unrelated program), break the lock:
+
+```powershell
+andorra update --break-lock
+```
+
+## The desktop client's engine
+
+A source build of the desktop client has an engine of its own, `desktop/node_modules/@andorra-labs/code`, which `andorra update` does not touch. Every `npm install` or `npm ci` in `desktop/` moves it to the latest npm release; see [Desktop client](desktop-app.md#which-engine-the-window-starts).
+
+The reverse holds too: updating the desktop app does not update the global `andorra`. When the global installation is older than the desktop's engine, the desktop says so under **Settings → Appearance & engine** and offers `andorra update` to copy, or `npm install -g @andorra-labs/code@latest` for a release before 0.1.5, whose updater predates npm releases; see [Desktop client](desktop-app.md#the-terminals-andorra).
+
+## Version
+
+`andorra --version` prints the installed version, read from the package manifest of the installation that provides the command.

package/docs/guides/windows-code-signing.md

@@ -0,0 +1,316 @@
+# Windows code signing
+
+## Public release notes
+
+The update manifest's `notes` field and the Desktop Release workflow's `release_notes` input are
+displayed to customers. Describe user-visible changes there; do not include private commit IDs,
+branch names, checkout paths, or build provenance. Keep source and signing evidence in the private
+pull request and QA records. A concise default is "A new version of Andorra Code is available."
+
+Correcting notes on a published version changes only the manifest's `notes` field. Preserve the
+version, publication date, platform URLs, and updater signatures; never replace a published
+installer under the same version. Use a conditional write against the current manifest ETag and
+invalidate `/desktop/latest.json` after the write.
+
+## Release versions and the bundled engine
+
+The GUI and its bundled engine are one release. Before building a new installer, bump the root
+and desktop `package.json` versions and their lockfile package entries, plus Tauri's
+`tauri.conf.json`, `Cargo.toml` and the application entry in `Cargo.lock`, to the same new version.
+The packager refuses mismatched engine/GUI versions. `npm run desktop:build --prefix desktop`
+stages the compiled engine, locked production dependencies and matching Node runtime before
+building the signed installer; the updater replaces that managed payload with the GUI.
+An explicit engine path or `ANDORRA_CLI` remains a user-managed override.
+
+The desktop bundles carry two independent signatures. They answer different questions and neither
+replaces the other.
+
+| Signature | Produced by | Answers | Key material |
+| --- | --- | --- | --- |
+| Authenticode | Azure Artifact Signing (formerly Azure Trusted Signing), through `signtool.exe` | Windows SmartScreen, the UAC publisher name, and "Properties → Digital Signatures" | None in the repository; the service issues a three-day certificate per request |
+| minisign | Tauri, at bundle time | "Is this update file the one the release produced?" for the in-app updater | `TAURI_SIGNING_PRIVATE_KEY`, a repository secret |
+
+This guide covers the Authenticode signature. The updater signature is described in
+[Desktop client](desktop-app.md) and `.github/workflows/desktop-release.yml`.
+
+## How the build signs
+
+`desktop/src-tauri/tauri.conf.json` names the signing command:
+
+```json
+"bundle": {
+  "windows": {
+    "signCommand": { "cmd": "node", "args": ["../scripts/sign-windows.mjs", "%1"] }
+  }
+}
+```
+
+Tauri replaces `%1` with the file to sign and runs the command from `desktop/src-tauri/`, not from
+`desktop/`. That is why the script path starts with `../`, and why a path relative to `desktop/`
+fails the build with the unhelpful message `failed to run node`: the bundler reports a non-zero
+sign command this way and discards what the command printed. Run the command by hand (or
+`npm run sign:check`) to see the real error.
+
+Tauri invokes the command for every PE file it puts on disk:
+
+- the application executable (`target/release/andorra-desktop.exe`),
+- the NSIS plugin DLLs under `target/release/nsis/<arch>/Plugins/`,
+- the uninstaller it generates at build time (a `.tmp` file in `%TEMP%`, through the
+  `!uninstfinalize` hook in the vendored `nsis-template.nsi`),
+- the final `setup.exe`.
+
+The vendored hook carries the `= 0` comparison (`!uninstfinalize '...' = 0`) because NSIS
+otherwise ignores the finalize command's exit code, which would let a failed uninstaller
+signature produce a bundle that passes every later check while shipping an unsigned
+uninstaller. With the comparison, a non-zero exit aborts `makensis` and the bundle fails.
+
+The script imports only Node builtins, so a bundling job still installs nothing from the
+application's lockfile.
+
+`desktop/scripts/sign-windows.mjs` reads its configuration from the environment, writes a
+`metadata.json` into a temporary directory, calls `signtool.exe` with the Artifact Signing dlib, and
+deletes the metadata file afterwards. No account name, endpoint, or credential is written to the
+repository.
+
+### Environment
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `ANDORRA_SIGNING_ENDPOINT` | yes | `https://<region>.codesigning.azure.net` for the account's region |
+| `ANDORRA_SIGNING_ACCOUNT` | yes | Artifact Signing account name |
+| `ANDORRA_SIGNING_PROFILE` | yes | certificate profile name |
+| `ANDORRA_SIGNING_REQUIRED` | releases only | `1` turns a skipped signature into a failed build |
+| `ANDORRA_SIGNING_CORRELATION_ID` | no | opaque value recorded on the signing request |
+| `ANDORRA_SIGNING_DESCRIPTION` | no | Authenticode description, shown in the UAC prompt; default `Andorra Code` |
+| `ANDORRA_SIGNING_DEBUG` | no | `1` passes `/debug` to signtool |
+| `ANDORRA_SIGNTOOL` | no | explicit `signtool.exe` |
+| `ANDORRA_SIGNING_DLIB` | no | explicit `Azure.CodeSigning.Dlib.dll` or its folder |
+
+Authentication is `DefaultAzureCredential` inside the dlib: `AZURE_TENANT_ID` + `AZURE_CLIENT_ID`
+with either `AZURE_CLIENT_SECRET` or `AZURE_FEDERATED_TOKEN_FILE` when they are set, otherwise the
+account signed in to the Azure CLI. The interactive-browser credential is disabled in the generated
+metadata, because a bundling command that opens a browser window waits forever in CI and in a
+non-interactive shell; a missing sign-in fails instead, and `az login` is the fix.
+
+The dlib spawns `az` from `PATH`, and a per-user install of the Azure CLI is often not there. The
+script finds the documented install location, prepends its directory for the signtool child process,
+and leaves the machine's `PATH` alone.
+
+Without the three required variables a developer build succeeds and prints a warning that the
+bundle is unsigned. A release sets `ANDORRA_SIGNING_REQUIRED=1`, and then a missing variable, a
+missing tool, or a signtool failure fails the bundling job.
+
+## Checking the workstation
+
+```bash
+npm run sign:check --prefix desktop
+```
+
+The command prints one row per prerequisite and exits non-zero only under `--require`. A ready
+workstation looks like this:
+
+```text
+Azure Artifact Signing self-check
+  configuration          ok      https://eus.codesigning.azure.net · andorrasigning · andorra-code
+  signtool.exe           ok      C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe (10.0.26100.0)
+  Artifact Signing dlib  ok      C:\Users\<you>\AppData\Local\Microsoft\MicrosoftArtifactSigningClientTools\Azure.CodeSigning.Dlib.dll
+  .NET 8 runtime         ok      8.0.8
+  Azure credentials      ok      azure-cli: <you>@andorralabs.com
+```
+
+Prerequisites, in install order:
+
+```powershell
+# 1. signtool, from the Windows 10/11 SDK (Windows 11 SDK 10.0.22621.755 or newer;
+#    10.0.26100.0 recommended). The 10.0.20348 server SDK is explicitly unsupported.
+winget install --exact --id Microsoft.WindowsSDK.10.0.26100
+
+# 2. .NET 8 desktop runtime, which loads the signing plugin
+winget install --exact --id Microsoft.DotNet.Runtime.8
+
+# 3. The Artifact Signing client tools (the dlib), from Microsoft
+winget install --exact --id Microsoft.Azure.ArtifactSigningClientTools
+```
+
+The client tools install under `%LOCALAPPDATA%\Microsoft\MicrosoftArtifactSigningClientTools\` for a
+per-user install and under `%ProgramFiles%\Microsoft\` for a machine-wide one. The script searches
+both, plus the NuGet cache, so the exact folder name is not part of the contract.
+
+Then sign in once per session:
+
+```powershell
+az login
+```
+
+A per-user Azure CLI install is often not on `PATH`; the script looks in the documented location
+(`%ProgramFiles%\Microsoft SDKs\Azure\CLI2\wbin\az.cmd`) and prepends it for the signing child
+process, so `az login` is enough without editing `PATH`.
+
+## One-time Azure setup
+
+You need a Microsoft Entra tenant, an Azure subscription, and the Artifact Signing eligibility
+approval this team already has. Identity validation can be started only from the Azure portal and
+is the long pole (1–20 business days).
+
+```bash
+az login
+az provider register --namespace Microsoft.CodeSigning
+az extension add --name artifact-signing
+```
+
+Create the account. The region decides the endpoint every build and CI run must name, so pick one
+and keep it: the endpoint table is in Microsoft's
+[quickstart](https://learn.microsoft.com/en-us/azure/artifact-signing/quickstart).
+
+```bash
+az group create --name rg-andorra-signing --location eastus
+az artifact-signing create --name andorrasigning --resource-group rg-andorra-signing \
+  --location eastus --sku Basic
+```
+
+In the portal, on the new account:
+
+1. **Identity validations → New identity → Organization → Public.** Organization validation puts
+   the legal entity on the certificate; individual validation puts a person. For an installer
+   published by Andorra Labs, use the organization. You must hold the *Artifact Signing Identity
+   Verifier* role to create it.
+2. Wait for the validation to reach **Completed**, then copy its **Identity validation ID**.
+3. **Certificate profiles → Create → Public Trust**, name it `andorra-code`, and select the
+   completed identity validation. Leave *Program Type* at None.
+
+Or create the profile from the CLI once the validation is complete:
+
+```bash
+az artifact-signing certificate-profile create \
+  --resource-group rg-andorra-signing \
+  --account-name andorrasigning \
+  --name andorra-code \
+  --profile-type PublicTrust \
+  --identity-validation-id <identity-validation-id>
+```
+
+### The identity that signs
+
+Local builds sign as whoever ran `az login`. CI needs its own identity, and it should be an app
+registration with a federated credential, not a client secret:
+
+```bash
+APP_ID=$(az ad app create --display-name andorra-code-signing --query appId -o tsv)
+az ad sp create --id "$APP_ID"
+
+az ad app federated-credential create --id "$APP_ID" --parameters '{
+  "name": "andorra-code-releases",
+  "issuer": "https://token.actions.githubusercontent.com",
+  "subject": "repo:Andorra-Labs/Andorra-Code:ref:refs/heads/main",
+  "audiences": ["api://AzureADTokenExchange"]
+}'
+
+az role assignment create \
+  --assignee "$APP_ID" \
+  --role "Artifact Signing Certificate Profile Signer" \
+  --scope "/subscriptions/<subscription-id>/resourceGroups/rg-andorra-signing/providers/Microsoft.CodeSigning/codeSigningAccounts/andorrasigning/certificateProfiles/andorra-code"
+```
+
+The release workflow runs on `workflow_dispatch` from `main`, which is what the branch subject
+above covers. Narrowing it to a GitHub environment (`subject: repo:…:environment:release`) is
+stricter; if you do that, add the environment to the `bundle-windows` job.
+
+### Repository configuration for releases
+
+| Kind | Name | Value |
+| --- | --- | --- |
+| variable | `SIGNING_ENDPOINT` | `https://eus.codesigning.azure.net` (the account's region) |
+| variable | `SIGNING_ACCOUNT` | `andorrasigning` |
+| variable | `SIGNING_PROFILE` | `andorra-code` |
+| variable | `AZURE_CLIENT_ID` | the app registration's application (client) ID |
+| variable | `AZURE_TENANT_ID` | the Entra tenant ID |
+| variable | `AZURE_SUBSCRIPTION_ID` | the subscription that holds the account |
+
+None of these is a secret: `azure/login` exchanges GitHub's short-lived OIDC token for an Azure CLI
+session, and the dlib authenticates with that session. The bundling job fails before it builds
+anything when one of them is missing.
+
+### Signing a local release build
+
+```bash
+export ANDORRA_SIGNING_ENDPOINT=https://eus.codesigning.azure.net
+export ANDORRA_SIGNING_ACCOUNT=andorrasigning
+export ANDORRA_SIGNING_PROFILE=andorra-code
+export ANDORRA_SIGNING_REQUIRED=1
+
+npm run desktop:build --prefix desktop
+```
+
+`ANDORRA_SIGNING_REQUIRED=1` is the difference between "I built an installer" and "I built the
+installer I intend to publish": it refuses to produce an unsigned bundle.
+
+## Verifying a signature
+
+After a build, before publishing:
+
+```powershell
+$setup = Get-ChildItem 'desktop\src-tauri\target\release\bundle\nsis\*.exe'
+Get-AuthenticodeSignature $setup.FullName |
+  Format-List Path, Status, StatusMessage, SignerCertificate, TimeStamperCertificate
+```
+
+Expected:
+
+- `Status` is `Valid`.
+- `SignerCertificate.Subject` names the legal entity from the completed identity validation
+  (`CN=Andorra Labs, …`), not a person and not a self-signed certificate.
+- `TimeStamperCertificate` is present. Artifact Signing certificates are valid for three days, so an
+  unstamped signature stops verifying almost immediately and older installers would report as
+  untrusted.
+
+The same verdict from the SDK directly, which also validates the chain against the current trusted
+roots:
+
+```powershell
+& "${env:ProgramFiles(x86)}\Windows Kits\10\bin\10.0.26100.0\x64\signtool.exe" verify /pa /v $setup.FullName
+```
+
+Explorer shows the same signature under the setup file's **Properties → Digital Signatures** tab.
+
+SmartScreen reputation is not part of verification: a valid signature from a new publisher can
+still show "Windows protected your PC" until downloads accumulate. That is expected and does not
+indicate a broken signature.
+
+## Releasing
+
+`.github/workflows/desktop-release.yml` → `bundle-windows` does, in order:
+
+1. Refuses to run when any repository variable above is unset.
+2. Signs in with `azure/login@v3` using the federated credential (`id-token: write`). The action
+   runs `az login` with the OIDC token, and the dlib later authenticates through that CLI session.
+3. Installs the Artifact Signing client tools with `winget`.
+4. Runs `tauri bundle` with the `ANDORRA_SIGNING_*` variables and `ANDORRA_SIGNING_REQUIRED=1`, so
+   the app executable, the uninstaller, and the setup executable are all signed.
+5. Verifies every produced `.exe` with `Get-AuthenticodeSignature`: `Status` must be `Valid` and a
+   timestamp must be present. The job fails otherwise, and the manifest is never written.
+
+The updater's minisign signature is produced in the same step from
+`TAURI_SIGNING_PRIVATE_KEY`; it is unchanged by this setup and both signatures must be present on a
+published release.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `signtool exited with 1`, `Azure.Identity: AuthenticationFailed` | no credential reached the dlib | `az login` locally, or check the OIDC app registration and `id-token: write` in CI |
+| `403 Forbidden` / `SignerSign() failed` | the endpoint region differs from the account's region, or the identity lacks *Certificate Profile Signer* | use the region's exact endpoint from the table above; grant the role at the profile scope |
+| `The specified module could not be found` when signtool loads the dlib | .NET 8 runtime missing | install `Microsoft.DotNet.Runtime.8` |
+| `Artifact Signing dlib ... not found` | client tools not installed, or installed in an unusual place | `winget install -e --id Microsoft.Azure.ArtifactSigningClientTools`, or set `ANDORRA_SIGNING_DLIB` |
+| `signtool.exe not found` | SDK missing or older than 10.0.2261.755 | install a current Windows SDK, or set `ANDORRA_SIGNTOOL` |
+| The build warns "signing skipped" on a machine that should sign | the three required variables are not exported in that shell | run `npm run sign:check --prefix desktop` |
+| The bundler fails with `failed to run node` and nothing else | the `signCommand` script path is relative to the wrong directory | it must be `../scripts/sign-windows.mjs`, relative to `desktop/src-tauri/`; run the command from that directory by hand to see the real message |
+| Timestamp request fails | outbound access to `http://timestamp.acs.microsoft.com` blocked | allow the host (port 80 is enough; the response is signed) |
+
+## What not to do
+
+- Do not commit a `metadata.json`, an account name, or a credential. The script builds the metadata
+  file in the system temporary directory and removes it on the way out.
+- Do not add a client secret for CI to make `azure/login` simpler. The federated credential exists
+  so there is nothing to rotate or leak.
+- Do not treat the Authenticode signature as a substitute for the updater's minisign signature.
+  Windows reads the first; Tauri's updater reads the second.