@andorra-labs/code 0.0.0-stage → 0.1.5

package/docs/concepts/jev-efficiency.md

@@ -0,0 +1,216 @@
+# Efficiency features: fewer coding-model turns, smaller requests
+
+**Status:** implemented behind independent switches, all off by default. Each switch was evaluated on
+its own with deterministic replay (`npm run eval:jev`); none has been validated on a live model, so
+none is enabled until a paired live evaluation shows preserved quality at lower cost.
+
+The agent runtime spends money in three ways: the number of coding-model requests, the size of each
+request (every turn resends the whole conversation), and the model tier each request runs on. The
+features below attack each of those without widening what the hosted decision service receives, and
+without touching permissions, approvals, required verification or user control.
+
+## The decision hierarchy
+
+Every change here follows one order:
+
+1. **Deterministic runtime logic for facts already known.** A process exit code, an empty workspace,
+   a missing repository, an unchanged context block, a test report's pass/fail counts: ordinary code
+   settles these and spends no decision request on them.
+2. **Jev for bounded semantic choices among known alternatives**, using only the question types the
+   hosted service supports today (`src/decision/providers/questions.ts`). The service accepts no new
+   question ids, so every selection that would need a new question stays deterministic.
+3. **The coding model for new code, new arguments, diagnosis and unfamiliar reasoning.**
+
+Jev never generates code, commands, paths, summaries or answers; never grants permissions; never
+overrides graph steps or user instructions; never treats an exit code of zero as task completion;
+and never turns tool output into instructions. On timeout, malformed output, uncertainty or an
+unavailable service the runtime falls back to ordinary execution, as before.
+
+## Configuration
+
+```json
+{
+  "efficiency": {
+    "preparedContinuations": false,
+    "postflightOnlyWithCandidates": false,
+    "toolResultFiltering": false,
+    "toolResultFilterThresholdChars": 6000,
+    "contextSelection": false,
+    "catalogSelection": false,
+    "adaptiveRouting": {
+      "enabled": false,
+      "tiers": { "economy": { "provider": "local", "model": "small" }, "balanced": { "provider": "local" }, "premium": { "provider": "cloud", "model": "large" } },
+      "maxEscalations": 1,
+      "pricing": { "local/small": { "inputPerMillionUsd": 0.1, "outputPerMillionUsd": 0.4, "cacheReadPerMillionUsd": 0.01 } }
+    }
+  }
+}
+```
+
+Omitting the block, or any switch, is the shipped behavior byte for byte (`test/jev-efficiency-runtime.test.ts`
+compares the serialized requests). To roll a feature back, remove its switch; no run state depends on it.
+The switches are read from `config.json` by the CLI and the desktop engine (`src/cli.ts`, `src/app-server.ts`).
+
+## 1. Prepared continuations (`preparedContinuations`)
+
+The coding model already prepares concrete next steps with `prepare_steps` (`src/decision/PreparedSteps.ts`),
+and a Jev round selects among them after the batch's results. With this switch an `investigate` or
+`verify` step may declare `when: "success" | "failure" | "always"`. The outcome of the batch that
+prepared it is a known fact, so the first step whose trigger matches runs right after that batch
+without a decision request. Only that one step runs deterministically; its own results are judged by
+a round like any other, with the remaining steps as candidates, so a chain of automatic actions still
+ends at the existing limit of three.
+
+Everything that restricted automatic actions still does: retries and completions never trigger, a
+step whose tool is not in the catalog is rejected when prepared, the fingerprint rule blocks repeating
+an unsafe action, approvals and hooks run, and the step is revalidated against the catalog the turn
+advertises and the permission state it was authored under immediately before execution. Steering,
+follow-ups and a model resumption discard prepared steps (`efficiency.prepared.invalidated`).
+
+Accounting: `decision.turn_bypassed` is emitted only after the prepared action executed. A step the
+catalog, a hook, invalid arguments or an approval rejected produced an error observation the model
+has to read, so it is reported as `efficiency.prepared.rejected` and never as a saved turn.
+`efficiency.prepared.declared` carries the serialized size of every `prepare_steps` call, so the
+preparation overhead is in the ledger next to the turn it may save.
+
+## 2. No post-tool round without a decision (`postflightOnlyWithCandidates`)
+
+The post-tool round is already non-blocking when the batch prepared no candidates
+(`docs/concepts/jev-decision-thresholds.md`): its only possible effect is one advisory line in a later
+prompt. Under this switch that round is not requested at all (`efficiency.postflight.skipped`,
+reason `no_candidates`). A round with candidates is requested and awaited as before, and the wait it
+puts on the critical path is recorded separately (`efficiency.postflight.awaited`, `waitMs`).
+
+## 3. Tool-result filtering (`toolResultFiltering`)
+
+`src/tool-result-filter.ts` parses bulky shell, search and listing results once, at insertion, before
+they enter the model-visible conversation. It recognizes test reports (node:test, vitest/jest,
+pytest, cargo, go), compiler output, search results, directory listings and progress-heavy logs. A
+filtered result keeps the executed command's exit status (the `Tool error: Exit code: N` line stays
+in place), every failure with its assertion and stack frames, the summary counts, warnings, the
+first and last lines, and a trailer made only of counts that names the archived original:
+
+```text
+[Tool output filtered (test-report): 2387 of 2416 lines omitted; passLines=600 failLines=2 summaryLines=4. Complete original: tool-output://<invocation>/1 (use expand_tool_output with ref, offset and limit).]
+```
+
+Nothing is reworded: the module assembles excerpts and counts and writes no summary of its own, so
+an instruction hidden in a test name cannot reach the structured trailer. The complete original is
+kept in an invocation-scoped archive (and in the run's artifact store when one exists, as `0600`
+files) and expanded by reference and range through `expand_tool_output`, whose schema joins the
+catalog only once something was archived. Another invocation's reference is refused. Expansions are
+recorded (`efficiency.tool_result.expanded`) so a model that reads the original back is charged for it.
+
+Never filtered: source reads, patch hunks, skill and memory content (not candidates at all), tool
+errors other than a non-zero exit (the text is the evidence), outputs at or under the threshold,
+formats the parser does not recognize (the existing clip and pressure-driven compaction stay as the
+fallbacks), and a filtered result that would not be at least 20% smaller. A filtered observation is
+reported as truncated, so no prepared completion may rest on it.
+
+Semantic selection by Jev of which excerpts to keep would require sending excerpts the hosted service
+is not contracted to receive. It is not implemented; the deterministic path stands alone.
+
+Finding from the evaluation: the shipped 24,000-character clip drops both failing tests of a
+600-test report, because they sit past the clip. Filtering keeps them.
+
+## 4. Context selection and retrieval gating (`contextSelection`)
+
+Before retrieval, `src/workspace-facts.ts` collects bounded facts (empty or not, file-count bucket,
+`.git` present, manifest names). An empty workspace has no source to explore and no repository
+history to recall, so both automatic retrievals are skipped on that fact alone
+(`efficiency.context.retrieval_skipped`). A missing repository gates nothing; the index and memory
+services report their own availability as before.
+
+After retrieval, `src/context-selection.ts` ranks what came back by bounded lexical evidence
+(identifiers shared with the task, weighted toward a candidate's own path or title), keeps mandatory
+items, keeps the dependencies of everything kept, and lists what it omitted with the tool that
+fetches it (`repo_explore`, `Read`, `memory_search`). The repository block is selected per file
+inside the CodeGraph query so the ledger records only what was injected; memory entries are selected
+and the block rebuilt from the kept entries, unchanged in wording. The selection is content-level and
+deterministic; it never claims a Jev judgment it did not make.
+
+A block whose exact text already sits in the conversation a node inherits from its predecessor is not
+injected again (`efficiency.context.duplicate`); a changed file produces different text and is
+injected as new. Memory entries remain untrusted evidence.
+
+## 5. Tool catalog and skills (`catalogSelection`)
+
+`src/tool-catalog.ts` builds a task-appropriate catalog from the tools the node is already permitted
+to use. Only certainties omit a family: no repository and no git wording omits `git`; an unavailable
+index omits `codegraph`; an empty workspace omits `memory`; `web`, `browser` and `subagents` are
+omitted when nothing in the task indicates them. Protected core tools, tools the node names
+explicitly, unknown families, and every tool an inherited transcript already called are kept, the last
+so providers that validate historical tool calls against the catalog still see the schema. The
+selection is a pure function of its inputs (byte-stable ordering), computed once per attempt, and it
+is applied only when the schema characters it saves exceed the cost of the omission note plus the
+`restore_tools` schema. Everything omitted stays restorable through `restore_tools` with the same
+permission checks (`efficiency.catalog.restored`).
+
+The skill catalog is ordered by relevance to the task within its budget, explicitly requested and
+inherited skills first and whole, the rest named without descriptions so they stay loadable. Skill
+bodies were already loaded lazily by the `Skill` tool; a catalog block already present in the inherited
+conversation is not re-inserted.
+
+## 6. Adaptive model-tier routing (`adaptiveRouting`)
+
+Off unless `enabled: true` and at least one tier names a configured provider and model. A node that
+pins a provider or model, a run started with an explicit model (`--model`, a desktop override, a live
+selection) and a delegated child are never re-tiered. The decision is taken once per attempt before
+the conversation is built: a decisive security or architecture answer from the preflight, or risk
+wording in the task, routes to `premium`; a short mechanical task (rename, typo, formatting,
+changelog) routes to `economy`; a complexity score with confidence routes by its value; anything
+else keeps the baseline (`efficiency.routing.decided`, reason `low_confidence`). A tier the
+configuration cannot resolve keeps the baseline too.
+
+Escalation is upward only, at most `maxEscalations` per node (default 1), and only after a defined
+failure (`repeatedToolFailure`, `maxIterations`); a cancellation or a deadline is not evidence. The
+escalated attempt is a fresh conversation (no provider continuation or reasoning state crosses
+models), told which workspace files the previous attempt already changed so it inspects rather than
+repeats them, and billed to the same node budget as every attempt before it.
+
+Cost reporting uses only prices the configuration supplies (`pricing`, keyed `provider/model`); a
+model without a price reports "cost unavailable", never zero. The runtime assigns no capability or
+quality rating to any model.
+
+## Accounting
+
+Every feature emits `efficiency.<feature>.<outcome>` events with fixed reason codes
+(`EFFICIENCY_REASONS` in `src/efficiency.ts`), folded into a local `efficiency` tally on the run's
+telemetry capture (`src/telemetry/capture.ts`). The tally is never uploaded; the emitter copies named
+fields only. The existing `decision.*` events, `decision.turn_bypassed`, provider usage and the
+Benchmarks metrics are unchanged.
+
+What is measured, and how it is labeled:
+
+| Figure | Source | Label |
+| --- | --- | --- |
+| Model requests, input, output, cache read/write | provider usage, as before | observed |
+| Request size | serialized JSON of messages and tool schemas | deterministic comparison, characters, not tokens |
+| Jev requests, latency, critical-path wait | `decision.*` and `efficiency.postflight.awaited` | observed |
+| Saved input of a bypassed turn | usage dashboard estimate from the preceding measured request | counterfactual estimate |
+| Cost | configured prices only | unavailable when no price is configured |
+
+Optimizations are applied in sequence and each delta is attributed once: a filtered result enters
+the conversation smaller, and the pressure-driven compaction that may later retire it sees only the
+smaller text. A skipped model call is counted as a bypassed turn and nothing else is credited for it.
+
+## Evaluation
+
+```bash
+npm run build
+npm run test:jev          # focused unit and integration suites
+npm run eval:jev          # deterministic replay: baseline, each feature alone, all together
+npm run eval:jev:live     # optional paired live evaluation; needs ANDORRA_LIVE_EVAL=1 and ANDORRA_LIVE_EVAL_HOME, a dedicated home signed in with an evaluation account (its config is used as is; only the efficiency block changes per run, and a probe run must show decisions being requested before any pair is spent)
+```
+
+The deterministic evaluation (`scripts/jev-efficiency-eval.mjs`, workloads in
+`tests/jev-efficiency/workloads.mjs`, criteria in `tests/jev-efficiency/criteria.json`) writes
+`tests/jev-efficiency/results/latest.{json,md}`. It compares what the runtime actually sent under
+scripted models, tools and a scripted decision provider. It is a mechanism and opportunity
+evaluation: a live model may behave differently with less context, scripted adapters report no
+tokens, and no cost is known for a mock model. The acceptance criteria were written before the first
+run; the two revisions made afterwards are recorded in the file with their reasons, and neither
+loosened a per-feature size or count threshold.
+
+Live savings and quality preservation are unvalidated. Until a paired live evaluation exists, every
+feature stays off by default.

package/docs/concepts/jev-eval-2026-11-01.md

@@ -0,0 +1,78 @@
+# JEV A/B evaluation: 2026-11-01 start, 2026-11-02 completion
+
+The evaluation at commit `23565f1f` passed all 16 workload checks. JEV used 4.2% fewer input tokens but 7.9% more output tokens and one more model request. This is not evidence of a reliable token-efficiency improvement: only three of eight pairs used less input, and the aggregate reduction depends on the second service pair. No model turn was bypassed by JEV.
+
+## Method and reproducibility
+
+Built a clean dedicated worktree at `23565f1f` on Windows with Node.js v24.13.1 and the configured GX10 OpenAI-compatible provider, model `glm-5.3-flash`. Used the real signed-in home required by the hosted decision service. `jevEnabled` was true and `efficiency` absent, so the JEV arm exercised shipped defaults; flag-only arms did not change configuration. Two repetitions rotate arm order and use fresh seeded workspaces.
+
+Commands run:
+
+```text
+npm ci --ignore-scripts
+npm run build
+node dist/src/cli.js --version
+node dist/src/cli.js auth status
+node eval/jev-ab.mjs --arms jev,nojev --workloads greenfield,bugfix,investigate,service --reps 2 --set build-23565f1f --out <installation-checkout>/eval/results/2026-11-01 --json
+node --test eval/analyze.test.mjs
+```
+
+The analyzer test file passed 7/7 tests with no skips; `git diff --check` passed. CLI version was 0.1.3; build passed and authentication reported signed in with paid membership. Raw artifacts remain local and gitignored in `eval/results/2026-11-01/`: `report.md`, `summary.json`, `INDEX.md`, `runs/build-23565f1f/`, and `trajectories/build-23565f1f/`. They contain provider/workspace data and are deliberately not published. Each row below maps to `<workload>-<arm>-r<rep>.json` and the corresponding `.run.jsonl` / `.trajectory.jsonl` files. See [suite instructions](../../eval/README.md).
+
+## Validity and lifecycle limitations
+
+All 16 final records succeeded and passed their executable checks; no final records were excluded. Five discarded automatic attempts are outside these totals: one greenfield NOJEV health timeout; two investigate JEV provider-health failures; one service NOJEV infrastructure failure after two model requests (9,998 input and 28,729 output tokens); and one service NOJEV health failure. Thus the table measures successful retained cells, not the total cost of running the experiment. No cells were manually rerun to improve a result.
+
+Three service CLI processes remained alive after their graphs completed. Both repetition-zero service cells reached the suite's 25-minute process deadline, then passed the independent service checks. Two verified orphan console children of the JEV repetition-zero process were stopped during diagnosis, without releasing the CLI. The NOJEV repetition-one process tree was terminated after persisted graph success to release the runner; its check then passed. The final JEV service exited normally. Graph success and functional checks do not establish clean CLI shutdown. The generated report's wall seconds measure graph execution, not total CLI/suite elapsed time; no end-to-end latency improvement is claimed.
+
+Two repetitions are exploratory, not a statistically stable estimate. Provider-health instability, nondeterministic long responses, and tool-output differences further limit causal attribution. These runs do not benchmark the optional `jeveff` arm.
+
+## Results
+
+| Workload | Rep | Arm | Requests | Input tokens | Output tokens | Check |
+|---|---:|---|---:|---:|---:|---|
+| greenfield | 0 | JEV | 7 | 168,082 | 20,593 | pass |
+| greenfield | 0 | NOJEV | 5 | 74,763 | 8,417 | pass |
+| greenfield | 1 | JEV | 7 | 180,653 | 22,881 | pass |
+| greenfield | 1 | NOJEV | 7 | 120,418 | 10,525 | pass |
+| bugfix | 0 | JEV | 10 | 130,514 | 5,221 | pass |
+| bugfix | 0 | NOJEV | 8 | 105,912 | 5,657 | pass |
+| bugfix | 1 | JEV | 8 | 122,227 | 9,734 | pass |
+| bugfix | 1 | NOJEV | 8 | 144,404 | 11,643 | pass |
+| investigate | 0 | JEV | 4 | 49,677 | 5,963 | pass |
+| investigate | 0 | NOJEV | 5 | 65,136 | 7,812 | pass |
+| investigate | 1 | JEV | 8 | 149,065 | 23,556 | pass |
+| investigate | 1 | NOJEV | 6 | 73,691 | 7,071 | pass |
+| service | 0 | JEV | 24 | 1,706,849 | 63,752 | pass |
+| service | 0 | NOJEV | 21 | 1,373,633 | 59,175 | pass |
+| service | 1 | JEV | 15 | 579,343 | 34,483 | pass |
+| service | 1 | NOJEV | 22 | 1,263,842 | 62,254 | pass |
+
+| Scope | Request delta | Input delta | Output delta |
+|---|---:|---:|---:|
+| All eight pairs | +1.2% | -4.2% | +7.9% |
+| Greenfield | +16.7% | +78.7% | +129.5% |
+| Bugfix | +12.5% | +1.0% | -13.6% |
+| Investigate | +9.1% | +43.2% | +98.3% |
+| Service | -9.3% | -13.3% | -19.1% |
+
+JEV totals: 83 requests, 3,086,410 input tokens, 186,183 output tokens, 2,456,051 cache-read tokens, 155 tools. NOJEV: 82 requests, 3,221,799 input, 172,554 output, 2,627,522 cache-read tokens, 129 tools. JEV used fewer requests in 2/8 pairs, less input in 3/8, and less output in 4/8. Both service and investigate reversed direction between repetitions; greenfield increased tokens in both. Cache reads are reported separately, not added to input or interpreted as a monetary saving. The OpenAI-compatible usage normalization in `src/providers.ts` treats prompt tokens as inclusive of cached tokens. Subtracting reported cache reads gives 630,359 uncached input tokens for JEV versus 594,277 for NOJEV (+6.1%). Thus lower total input did not mean less uncached input in this cohort.
+
+## What JEV actually did
+
+The generated report records eight preflight rounds, 120 questions and 66 decisive answers (55%). Family routing omitted 12 schemas across runs. All 83 JEV requests carried a preflight block.
+
+Of 66 post-tool rounds, 53 answered and 13 fell back with `decision_service_unavailable`. Of 318 boolean answers, 29 were decisive (9%), only two affirmative. Three requests carried a post-tool directive, all in `investigate-jev-r1`: gather missing evidence. That run used more requests and tokens than its matched NOJEV run; this association is not proof the directive caused the difference. No repeats or task-constraint directives were withheld.
+
+There were two `prepare_steps` calls and zero `decision.turn_bypassed` events. JEV did not save a model turn through prepared continuation anywhere in this cohort. All 53 post-tool responses arrived during the next request rather than before its construction, so applied guidance was delayed by one request. Average fixed overhead was 1,928 characters/request from the preparation schema and preflight guidance; characters are not token measurements. Total recorded decision-service latency was 61,421 ms, including 9,375 ms on the critical path.
+
+## Optimization priorities to validate next
+
+1. **Reduce irrelevant tool-result replay.** The JEV service repetition-zero trajectory includes a roughly 24,857-character Git listing from above its empty temporary workspace, replayed in later requests. Bound Git discovery to the intended workspace and summarize/cap irrelevant listings while retaining a retrieval path. This is a harness opportunity in both arms, not a demonstrated JEV saving. Never publish the raw listing. Re-evaluate in fresh isolated repositories so ambient parent Git state cannot distort the workload.
+2. **Make prepared continuations measurably useful before paying for their schema every turn.** Two preparation calls produced zero bypasses. Inspect why candidates expired or never received an actionable decision; evaluate conditional schema inclusion and candidate-only postflight as separate variants. Preserve capability, confidence, permission, and verification gates rather than lowering thresholds from this small cohort.
+3. **Keep postflight advice relevant when it arrives.** Every answered postflight round missed construction of the immediate next request. Check whether the advice is already satisfied before delivering it one request later, particularly the read-only investigation directive. Compare reduced repeated investigation against the existing executable coverage check; do not suppress necessary evidence gathering solely to save tokens.
+4. **Measure long first responses separately from replay.** In `service-jev-r0`, the first response accounted for 47,724 of 63,752 output tokens, about 75%. Investigate provider reasoning/output configuration and instruction verbosity independently of JEV decisions; no postflight directive was delivered in that run. Repeated terminal-shutdown probes and tool-schema errors also deserve focused reproduction.
+5. **Fix lifecycle and reporting before larger experiments.** Bound cleanup after successful final output, preserve result/check collection, and surface timed-out or manually terminated CLI lifecycles alongside graph success. Report discarded-attempt usage and failures explicitly. Fix the underlying handle/cleanup cause rather than treating forced process termination as a successful runtime fix.
+
+These are evidence-based follow-ups, not implemented or validated token optimizations. A subsequent change should run the whole paired suite under a new set name, retain all attempts, preserve check success, and compare quality, cached/uncached usage, output tokens and lifecycle outcomes independently.
+

package/docs/concepts/limits.md

@@ -0,0 +1,43 @@
+# Limits
+
+By default a run has **no model-iteration ceiling, no attempt deadline, no tool-call ceiling**, a model-derived context allowance (unless explicitly tightened), and two completion repairs. A run continues until it finishes, the same tool call fails repeatedly, its context exceeds the bound, or you cancel it. This is deliberate: a task that legitimately runs for hours must not be killed for being slow, and time spent waiting on you is never charged to a deadline.
+
+## Configuring limits
+
+To bound an installation, add a `limits` block to `config.json`:
+
+```json
+{
+  "limits": {
+    "wallTimeMs": 3600000,
+    "maxIterations": 200,
+    "maxToolCalls": 500,
+    "maxContextChars": 400000,
+    "maxCompletionRepairs": 2
+  }
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `wallTimeMs` | Wall-clock bound per run. `0` means unlimited. |
+| `maxIterations` | Model-iteration ceiling per Agent invocation. `0` means unlimited. |
+| `maxToolCalls` | Tool-call ceiling per run. `0` is a real ceiling that refuses every tool call. |
+| `maxContextChars` | Context bound. Exceeding it stops the run with the specific reason. |
+| `maxCompletionRepairs` | How many times an invalid completion object may be repaired. |
+
+A graph carries its own `limits` block, and its `maxNodeVisits` is the ceiling on how many times one node may run. It is **unlimited by default**: absent, or `0`, means no ceiling. A graph with a return connection still needs a ceiling of some kind — a finite `maxNodeVisits`, or the run's `wallTimeMs` — and is rejected at validation without one.
+
+A graph or node limit can tighten whatever the configuration sets but never loosen it.
+
+## Request-level bounds
+
+- **File reads** return at most 2,000 lines per call, truncate any single displayed line beyond 2,000 characters, and always stay inside the 24,000-character tool-output budget — a page with long lines stops at the last whole line that fits. A longer file is read by following the `Use offset=N to continue` line each page reports until the whole file has been read; `Write` and `Edit` accept an existing file only after that complete read, so an agent that stops half-way is told which lines are still unread. Those offsets are only suggested while the file still matches the last read; a file that changed means reading it again. The window is fixed, not a configuration key.
+- **Shell timeout** defaults to 30 seconds, capped at 120 seconds, with process-tree cancellation.
+- **Provider HTTP requests** are bounded at 10 minutes by default so an endpoint that never answers cannot hang a run. Set `requestTimeoutMs` on a provider (milliseconds, up to one day), or `0` to remove it for an endpoint you would rather cancel by hand. This bound ends one unanswered request; it is not a run budget.
+- **Stream inactivity** (`streamIdleTimeoutMs` per provider) stays armed even when `requestTimeoutMs` is `0`: a stream that stops delivering bytes ends the call instead of hanging the run. Keep it above the endpoint's normal thinking pause.
+- **Model discovery** keeps its own 30-second bound regardless, so `/model` cannot wait minutes on an unresponsive endpoint.
+
+## Token totals are telemetry, not budgets
+
+There is no cumulative token budget. Every ReAct iteration resends the whole conversation, so a running input+output total measures repeated context rather than one giant prompt — search loops can inflate it quickly while each individual request still fits. Configured iteration, wall-time, tool-call, and context limits bound a run instead. Totals remain visible through `/usage` and the footer purely as provider-reported telemetry.

package/docs/concepts/memory.md

@@ -0,0 +1,30 @@
+# Memory
+
+Andorra can keep durable project memory across runs with an external [Graphiti](https://github.com/getzep/graphiti) service. Memory stores architecture decisions and their reasons, user instructions, conventions, verified bug fixes, procedures, and lessons.
+
+## Behavior
+
+- **Temporal.** When a fact changes, the old fact is kept as history and the new one becomes current.
+- **Per repository.** Memory is isolated per repository; projects do not see each other's facts.
+- **Advisory.** Agents receive a small ranked memory block automatically and can search deeper with the `memory_search` tool. The current repository is always authoritative.
+- **Policy-gated writes.** Memory writes happen only through a distillation step after a successful run — agents do not scribble into memory mid-task.
+
+CodeGraph separately indexes current code structure and is the primary source-discovery path when available; native grep/search remains the textual fallback. The two systems complement each other: memory holds what happened and why, CodeGraph holds what the code is now.
+
+## Enabling
+
+Graphiti runs as its own HTTP service (Python + a graph database); Andorra never installs or spawns Python. Start the service locally, then either add a `memory` block to `config.json`:
+
+```json
+"memory": {
+  "enabled": true,
+  "provider": "graphiti",
+  "graphiti": { "endpoint": "http://localhost:8000" }
+}
+```
+
+or set `ANDORRA_GRAPHITI_URL=http://localhost:8000`. If the service is unavailable, the harness warns and continues without persistent memory.
+
+**Permission requirement.** Persistent memory talks to the network, so it operates only when the workspace permission mode is **Full Access** (`/permissions full-access`) or unset. A workspace with an explicitly saved non-Full-Access mode (`read-only`, `ask-for-approval`, or `approve-for-me`) suspends the memory provider: no initialization, retrieval, search, or writes. Full Access also means automatic approval of write and shell tools — weigh that against the convenience of memory before enabling it on a workspace.
+
+Tuning knobs in the `memory` block include `automaticRetrieval`, `maxRetrievedMemories` (default 8), and `memoryContextChars` (default 4000).

package/docs/concepts/security.md

@@ -0,0 +1,40 @@
+# Security and permissions
+
+Andorra Code runs on your machine with your credentials. This page describes the boundaries it enforces — and the ones it does not.
+
+## Tool boundaries
+
+File tools validate workspace containment, including symlink resolution, in both approval and YOLO modes. Reads, searches, and output are bounded; searches skip `.git`, `node_modules`, `.andorracode`, and symlinks. These checks are not a hardened OS sandbox and do not protect against concurrent hostile filesystem changes.
+
+Shell executes as your OS user with host and network access. It requires approval on every invocation unless YOLO is enabled, and receives an allowlisted environment without provider credential variables — but shell commands can still access credential files on disk.
+
+**Use a disposable environment for untrusted repositories.**
+
+## Approvals and YOLO
+
+Write and shell tools prompt for approval by default. `/yolo` (or `--yolo`) bypasses the approval prompt for the current session only. YOLO retains tool allowlists, argument checks, file-tool containment, and execution limits — it is not a separate graph and not a sandbox. It is never persisted.
+
+Headless runs without `--yolo` receive permission-denied observations for writes and shell calls, because no interactive approver is present; read tools remain usable.
+
+## Workspace permissions
+
+`/permissions` chooses a permission mode and remembers it per workspace (`workspacePermissions` in `config.json`).
+
+## Secrets
+
+- Provider API keys are stored locally in `config.json` (plaintext — keep the file private) or referenced by environment-variable name. They are never added to command history or displayed in provider summaries.
+- Andorra account tokens live in the operating system credential store, never in plaintext files. A missing or locked credential store is an error; there is no fallback.
+- Codex provider sign-in is delegated to the official Codex CLI app-server; subscription tokens are never copied into Andorra configuration.
+- Do not put credentials in handoff data, graph JSON, `--run-input`/`--run-state` files, or workspace instruction files.
+
+## Completion validation
+
+Completion is a validated `{ "summary": "...", "tests": [] }` object. This validates the output contract, not the truth of model claims. Todo updates and progress describe reported progress, not independent proof that tests or implementation succeeded.
+
+## Destructive actions
+
+Treat every shell command and every file write you did not expect as a destructive action. Read the approval prompt before approving it: the prompt carries the full arguments, so you can see the exact command or path that is about to run.
+
+An approval is an explicit action, and only an explicit action counts. Text typed into the conversation — by you or by the agent — never satisfies an approval gate on its own, and a report that permission was granted is not the same as a granted permission. When a run is asked to do something irreversible, narrow the scope yourself — a disposable workspace, a branch you can discard — rather than relying on the prompt to catch it.
+
+Because the agent reads and writes files with your credentials and your network access, content inside a repository can attempt to steer a run: instructions found in a file, an issue, or a web page are data, not orders. The tool boundaries above limit what such content can reach, but they are not a substitute for reviewing approvals.

package/docs/concepts/workspace-instructions.md

@@ -0,0 +1,28 @@
+# Workspace instructions
+
+Andorra reads workspace instructions — persistent guidance for every agent in a project — from the repository root, before each task.
+
+## File selection
+
+The default agent reads project-root `ANDORRA.md`, falling back to `AGENTS.md` and then lowercase `agents.md`, **only when the preferred file is absent**:
+
+1. `ANDORRA.md` — preferred.
+2. `AGENTS.md` — used only if `ANDORRA.md` does not exist.
+3. `agents.md` — used only if neither above exists.
+
+The files are never combined. An existing unreadable or empty `ANDORRA.md` does not activate a fallback. Nested instruction discovery (instructions in subdirectories) is not yet implemented.
+
+## What goes in the file
+
+Anything a teammate would need before touching the codebase:
+
+- Build, test, and lint commands.
+- Branch, commit, and PR conventions.
+- Architectural constraints and cautions.
+- Roles: what the Orchestrator should clarify, what the Engineer should verify.
+
+Guidance is delivered through the bounded workspace reader and limited to **16,000 characters**; unreadable or unsafe guidance is omitted. Keep the file concise and put detail in files the agent can read on demand.
+
+## Overriding per node
+
+Workspace instructions apply to all agents in a project. A specific Agent node's instructions are edited in the Graph Builder: select the node and change its **Prompt** (saved before that graph runs). Node prompts refine the agent's role; workspace instructions and runtime permissions still apply.

package/docs/getting-started/README.md

@@ -0,0 +1,82 @@
+# Getting started
+
+This page installs Andorra Code from npm, configures one model provider, and runs your first task. Total time is a few minutes on a machine that already has Node.js.
+
+If you want another AI coding agent to do this for you, skip to [Give these instructions to an AI agent](../agents/install-for-agents.md).
+
+## What you need
+
+| Requirement | Notes |
+| --- | --- |
+| Node.js 22.19 or newer | The engine declares `node >=22.19.0`. Check with `node --version`. |
+| npm | Ships with Node.js. |
+| git | Andorra reads Git state for its status displays; also needed to install from source. |
+| A model provider | An API key for an OpenAI-compatible or Anthropic endpoint, a ChatGPT subscription (Codex provider), or a local server such as LM Studio. See [Configure providers](configure-providers.md). |
+
+## Install
+
+```sh
+npm install -g @andorra-labs/code
+```
+
+This installs two global commands, `andorra` and the alias `andorracode`. Keep them current with `andorra update`, which installs the latest npm release; see [Update](../guides/update.md).
+
+### Install from source
+
+To run unreleased changes, build the GitHub repository instead:
+
+```sh
+git clone https://github.com/Andorra-Labs/Andorra-Code
+cd Andorra-Code
+npm ci
+npm run build
+npm link
+```
+
+`npm link` points `andorra` and `andorracode` at this checkout. `andorra update` does not update a checkout; pull and rebuild it yourself (`git pull --ff-only`, `npm ci`, `npm run build`), or switch to the npm release with `npm install -g @andorra-labs/code@latest`.
+
+Alternatives without linking:
+
+```sh
+# run the built CLI directly
+node /path/to/Andorra-Code/dist/src/cli.js --cwd /path/to/project
+
+# or from inside the repository, after building
+npm start
+```
+
+## Configure a provider
+
+Providers are configured inside the TUI — there is no separate setup wizard.
+
+1. Run `andorra` in any folder. On first launch nothing is configured yet.
+2. Type `/providers` and press Enter.
+3. Choose **Add provider**, select a preset (DeepSeek, Kimi, Kimi For Coding, GLM Coding Plan, OpenAI, Anthropic, local, or Codex), and edit its connection and model.
+4. For hosted APIs choose **API key** and paste the key. Choose **Save changes**.
+
+Keys are stored locally in `config.json` under `~/.andorracode` (see [Reference: configuration](../reference/config.md)); keep that file private. You can also use an environment-variable name such as `OPENAI_API_KEY` instead of a stored key.
+
+Full details, including local servers and model discovery: [Configure providers](configure-providers.md).
+
+## Run your first task
+
+```sh
+cd /path/to/your/project
+andorra
+```
+
+The default command opens a full-screen terminal UI with a welcome panel, conversation and tool transcript, an input composer, and a live status bar. Out of the box it runs a single Software Engineer agent on the bundled default graph; paid members can select the Orchestrator intake workflow with `/graph` or `--graph :andorra` (see [Accounts](accounts.md)).
+
+- Answer questions with Up/Down + Enter; Escape cancels.
+- Approve file writes and shell commands when prompted, or enable `/yolo on` for the session to skip approvals.
+- Press Ctrl+C to stop a run; Ctrl+C again to exit.
+- Type `/help` for every command.
+
+An Andorra account is optional: signing in enables hosted Jev decision routing and, custom graphs in the graph editor: one small graph on the free tier, and any number with paid membership. See [Accounts, membership, and hosted Jev](accounts.md).
+
+## Where to go next
+
+- [Concepts](../concepts/README.md) — how the graph, agents, and context routing fit together.
+- [Guides](../guides/README.md) — the TUI in depth, the Graph Builder, headless automation, skills/MCP/plugins.
+- [Reference](../reference/README.md) — every CLI flag, slash command, and configuration file.
+- [Update an existing installation](../guides/update.md) — `andorra update` installs the latest npm release.

package/docs/getting-started/accounts.md

@@ -0,0 +1,67 @@
+# Andorra accounts and managed decisions
+
+Andorra runs the agent loop and tools on your machine. Your configured LLM provider still receives LLM requests directly. An Andorra account enables the hosted Jev decision service without distributing the shared Jev API key.
+
+## Sign in
+
+Passwords require at least 8 characters, including uppercase, lowercase, a number, and a symbol. MFA is disabled. Email verification is still required for new accounts.
+
+Run `andorra login` before starting the harness, or enter `/login` in an interactive session. Your browser opens the Andorra sign-in page; choose **Sign up** to create an account and verify your email. After successful login the browser returns to a loopback callback on your machine. You can close that browser tab.
+
+After login, the account label shows `Signed in | Free | your@email.com` (or `Legacy`, or `Paid`) using your verified email address. The same identity appears in the welcome screen, the persistent account label, and the output of the account commands. If the service cannot supply an email, the label still shows the verified membership status. Logout removes the email from the displayed account status.
+
+Run `andorra auth status` or `/auth status` to inspect your saved session. Run `andorra logout`, `/logout` or `/auth logout` to remove it from this machine and revoke its refresh token. These standalone commands do not require an LLM provider, and none of them signs out of an LLM provider; `/logout codex` does that for Codex.
+
+To switch accounts, run `/logout`, then `/login`. Sign-in always asks for credentials, even when the browser still has a session for the previous account, so you can enter another account's email or create a new one.
+
+The harness stores tokens in the operating system credential store, not in `config.json`. It renews access tokens automatically. Sessions have no application idle timeout. Expiration, administrative revocation, disabled accounts, or credential-store removal require signing in again. Other machines have separate sessions. A missing or locked credential store is an error; the harness never falls back to plaintext token files.
+
+Login needs an available local callback port 43187, a browser, and HTTPS access to the hosted account service. Headless machines without a usable operating system credential store can still use their own LLM providers, but cannot persist an Andorra account session.
+
+## Plans
+
+There are three plans, and the account label names the one you are on: `Signed in | Free`, `Signed in | Legacy`, or `Signed in | Paid`.
+
+- **Free** is the standard plan. It unlocks hosted Jev decisions at 100 per UTC day. The premium features stay locked.
+- **Legacy** is the free plan that carries the premium features, and it is the plan every account that signs up now is on. It is **free of charge** and carries the premium features: the Orchestrator workflow, saved custom graphs, and the graph editor, at the paid daily allowance. The accounts that were created before Andorra Code was released keep it when the promotion ends.
+- **Paid** is a paying account, and carries the same premium features.
+
+Legacy needs nothing to request or migrate: the premium promotion puts every account on it while it runs, and the accounts created before Andorra Code was released keep it afterwards, decided from your account's own creation date.
+
+Default always runs the single Software Engineer agent, for signed-out, free, legacy, and paid users. Legacy and paid users can explicitly select Andorra from `/graph` (or use `--graph :andorra`) for the Orchestrator workflow. Legacy and paid membership enables the Orchestrator workflow, saved custom graphs, and the graph editor (`andorra graph`, `--configure`, `/graph`, and custom `--graph` selections). Free accounts can build one custom graph of up to 3 nodes, not counting Done, without the Orchestrator; after a downgrade the oldest custom graph is the one that stays editable and runnable. Membership is checked against the authenticated service. Editing local configuration or cached token claims does not grant premium access. If the membership service is unavailable, premium-only entry points fail closed and the default workflow uses the free agent.
+
+There is no checkout or automated billing integration in this release: paid access is granted on the account, not purchased from the app.
+
+## Your account, your profile, and your usage
+
+The desktop app has an **account portal**: open it from the account name in the rail, or from **Account** in the rail's list. It shows three things.
+
+**Profile.** Your name, first name, and last name are stored with the account, so they are the same on every machine you sign in on. Your email address is your identity and cannot be changed there. Saving writes to the account service, not to this machine.
+
+**Usage.** Hosted Jev decisions are counted by the account service: how many you have used today against your allowance, and how many have been counted since the counter was introduced. Sessions, turns, projects, tokens, and model requests are counted on this machine, because that is where the work ran. Saved sessions are the ones still on disk, so deleting one takes it out of the count.
+
+**Billing.** Your plan, and the control that opens your billing page once subscription billing exists. There is no checkout in this release, so no payment method is on file and there is nothing to manage yet; the portal says so rather than showing a control that does nothing.
+
+The CLI shows the same plan in its account label, and `/auth status` prints the membership and the daily quota.
+
+## Hosted Jev decisions
+
+Jev needs a signed-in account, free or paid. Sign in with `/login` and start a task. With global Jev enabled and no explicit `decisions` override, the CLI checks your membership for each run and uses hosted Jev in **active** mode by default for signed-in free, legacy, and paid members. No personal Jev API key is needed. Signed-out users, and users whose membership cannot be verified, get no decision service at all, hosted or a configured local one, and keep ordinary retrieval routing.
+
+Free, legacy, and paid users can enter `/jev on` to enable Jev, `/jev off` to disable it, or `/jev status` (or a bare `/jev`, which changes nothing) to inspect the setting. The desktop app's **Jev** switch in the chat composer changes the same setting. This persists the global `jevEnabled` preference in CLI configuration; omission means enabled. Off suppresses both hosted and local calls on every node; On resumes the stored provider/mode, including explicit off/none, for the nodes that turn Jev on. Changing the setting while a task runs saves it at once, but that task keeps the setting it started with until it ends or is interrupted; the CLI and the desktop both say so. The footer shows `[Enabled]` or `[Disabled]` alongside server-provided quota. Enabled is a preference, not proof of a successful request: login, quota and service availability still apply.
+
+Active Jev decides whether eligible Agent invocations should retrieve automatic CodeGraph context or automatic Graphiti memory. The coding LLM still runs the agent loop and implements the task. Jev cannot grant tool permissions, change graph edges, bypass approval, or remove required verification. Skipping unnecessary retrieval can reduce context sent to the coding model, but token savings and prediction quality have not been measured.
+
+Jev runs only on Agent nodes that turn it on. Select an Agent in the graph builder and tick **Jev decisions**; this stores `jevEnabled: true` on the node. Unticked nodes, and nodes in graphs saved before this setting was opt-in, carry no setting and do not use Jev until they are ticked. The bundled Software Engineer ("Default") and Andorra presets cannot be edited, so their Agents ship with Jev turned on and the global switch is their control. Free, legacy, and paid accounts all get per-node control.
+
+The CLI honors top-level `decisions` selections, including off, shadow, direct Jev and Laya. Local Laya/Jev uses its configured endpoint and model and needs a signed-in account like the hosted service; direct Jev remains shadow-only. Global `jevEnabled: false` disables both hosted and local decisions. Configure local details in **Settings > Runtime > Jev decisions > Configure decisions**, or follow [decision-provider configuration](../../design/decision-engine.md). With no override, verified signed-in members retain the hosted default.
+
+For the hosted `andorra` selection, the managed endpoint, model, and shared credentials are controlled by the service: do not put a Jev key, custom endpoint or model alias in that configuration block. Local providers instead use their own endpoint/model and optional credential environment-variable name. Authentication failures, an exhausted quota, service errors, invalid answers, low-confidence answers, timeouts and cancellation all fall back to ordinary routing, so a run is never blocked by the hosted service. Public `[Jev]` activity shows requests, completion and safe fallback reasons; completion alone does not prove routing changed.
+
+Task runs using the enabled hosted service send a compact, question-scoped routing snapshot to that service: bounded excerpts of the task text and the node instructions, plus only the capability metadata the current questions need. Retrieved source, memory payloads and conversation history are not included. The service does not log request bodies or credentials. The default allowance is 250 requests per free member per UTC day and 1,000 per legacy or paid member per UTC day; failed upstream attempts can consume quota. Unavailable usage is shown as unknown rather than zero.
+
+Hosted decisions are skipped when no enabled retrieval capability is available, including for internal subagents. Long task and instruction prose is compacted before it is sent, and ordinary context routing stays available.
+
+The interactive terminal shows account status and a sign-in notice when signed out. Run `/login` for hosted Jev access; legacy or paid membership additionally enables the Orchestrator and graph features. `/auth status` refreshes the displayed membership and the server-provided daily quota. Limits count batched API requests, reset at midnight UTC, and retain the same usage counter across membership upgrades or downgrades. These quotas apply to the hosted Andorra service; direct provider use through an embedded runtime is not billed to the shared service.
+
+In the interactive CLI, open `/graph` and choose **Create new graph** to open a new draft in the browser. After saving, reopen `/graph` to select it. Creating a draft leaves the current conversation and graph selection unchanged. The editor server closes when the CLI exits.