archymedes-cli 2.0.0

package/I18N.md

@@ -0,0 +1,46 @@
+# Internationalization
+
+Archymedes CLI localizes its control surfaces into **16 languages**, chosen for global reach with
+deliberate weight on the Americas and Asia:
+
+`en` English · `es` Español · `pt` Português · `fr` Français · `de` Deutsch · `ru` Русский ·
+`ar` العربية · `tr` Türkçe · `zh` 中文 · `ja` 日本語 · `ko` 한국어 · `hi` हिन्दी · `bn` বাংলা ·
+`ur` اردو · `id` Bahasa Indonesia · `vi` Tiếng Việt
+
+Select one with `archymedes --language <code>`, `ARCHYMEDES_LANGUAGE=<code>`, or from `/settings`.
+An unset language falls back to the host locale (`LANG`), then to English. A locale variant
+(`pt-BR`, `zh_CN`) resolves to its base.
+
+## What is translated
+
+`src/i18n.ts` is the catalog. Every language has:
+
+- **Control labels** (`LABELS`) — the words on the prompt tagline, the settings menu, `/keys`.
+- **Slash-command descriptions** (`COMMANDS`) — the right-hand column of `/help`'s in-session list.
+- **Keyboard-shortcut descriptions** (`TRANSLATED_KEYBOARD_IDS`) — keyed by shortcut id, not row.
+- **Core messages** (`MESSAGES`, via `t()`) — the `--help` page's section headers and tagline, the
+  mode labels on the prompt, the first-run "not configured" line, and the connectivity doctor's
+  header and verdicts.
+
+A key a language has not translated renders its English source — never an empty string. This is
+enforced by `i18n.test.ts`.
+
+## What is not translated yet
+
+These stay English and are the next tranche of work:
+
+- The **dense flag-reference rows** in `--help` (`archymedes --json "task"`, `--sandbox-minutes N`,
+  …). The section headers around them are localized; the one-line descriptions are not.
+- The **`/guide`** topic prose (`src/guide.ts`) — 17 multi-paragraph topics.
+- `/settings` **field labels** beyond the menu chrome.
+- Low-frequency **runtime status, approval, and error** strings scattered through `src/archymedes.ts`.
+- **Defender / security** long-form copy.
+
+## Adding a language or a key
+
+1. Add the code + display name to `CONTROL_LANGUAGES`.
+2. Fill `LABELS`, `COMMANDS`, `TRANSLATED_KEYBOARD_IDS`, and the `MESSAGES` entries for it.
+3. `bun run test` — `i18n.test.ts` fails until every language has label + command + shortcut cover.
+
+The six most recently added languages (`ja ko de id vi tr`) were machine-translated and are pending
+native review.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+Archymedes CLI
+Copyright 2026 Archymedes CLI contributors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Portions of this software are derived from the Nova CLI ("Circuit-Nova"),
+Copyright 2026 Circuit-Nova, originally licensed under the MIT License. Those
+portions remain available from their origin under the MIT License; the combined
+work and all subsequent changes are distributed under the Apache License, 2.0.
+
+Bundled and dependent third-party components retain their own licenses; see each
+package's metadata for details.

package/README.md

@@ -0,0 +1,309 @@
+# archymedes
+
+A coding agent that runs in your terminal — against your working tree, or inside an isolated remote sandbox when the work shouldn't touch your machine.
+
+```bash
+npm install -g archymedes-cli
+archymedes "fix the failing test in src/parser.ts"
+```
+
+## What it does
+
+Archymedes reads, searches, edits and runs commands in a real project, then reports what actually happened. It guards effectful work according to the selected mode, snapshots the workspace so you can undo a turn, and tells you what each request cost.
+
+```
+archymedes                        Interactive session
+archymedes "add a health check"   One request, then exit
+archymedes --plan                 Read and reason only — the write tools aren't loaded
+archymedes --auto                 Auto-apply ordinary edits; sensitive actions still ask
+archymedes --defender             Security review — find and fix real issues; every change still asks
+archymedes --allow-sensitive      Approve a flagged task preflight; tool guards remain active
+archymedes --sandbox              Work in a remote sandbox; your files are never touched
+archymedes --resume               Continue the last session
+archymedes history                Browse past sessions without starting a model
+archymedes history search "text"  Search indexed snapshot and journal evidence
+archymedes history status         Show native-index or portable-fallback status
+archymedes --providers            Show which model providers are configured
+archymedes --location EG          Use the country's local currency (locale-detected by default)
+archymedes --currency EGP         Override with any supported ISO currency
+archymedes --budget 500           Approve and enforce a session spend cap in that currency
+archymedes --estimate "task"      Forecast input/output tokens and cost without calling a model
+archymedes settings               Configure keys, URLs, models, pricing, language and voice
+archymedes --language ar          Localize controls (also: en zh hi es fr bn pt ru ur)
+archymedes acp                    Speak the Agent Client Protocol on stdio, for an editor
+archymedes update                 Check and install the latest published CLI
+archymedes update --check         Check without changing the installed version
+```
+
+With a CircuitNotion key, Archymedes defaults to `circuit-2-turbo`. `/models refresh` asks configured
+providers for their current catalog; ordinary `/models` uses the cache so opening a menu does not
+wait on the network. Slash commands belong inside an interactive session. Passing one as a one-shot
+objective is rejected before model contact, preventing an invocation mistake from becoming a paid
+prompt.
+
+In a session: `/mode` shows the current permission posture, `/mode plan|build|auto|defender` switches it, and `/plan` `/build` `/auto` `/defender` remain quick shortcuts. Defender mode turns Archymedes into a security reviewer — the full tool set to actually run a scanner (including a built-in `scan_secrets` that matches likely credentials by pattern and always masks what it finds) and propose a fix, gated exactly like build so nothing is ever auto-approved. It works from a bundled, OWASP-2025-aligned set of playbooks: access control, security misconfiguration, software supply chain & CI/CD integrity, injection, client-side & browser security, auth/session handling, API security, SSRF, secrets, dependency risk, cryptography misuse, IaC/container hardening, exceptional-condition handling, business logic & race conditions, fuzzing and invariant-based testing, logging/monitoring/deterrence, and LLM/AI application security. `/undo` reverts the last turn, `/cost` shows the breakdown — totals, a table of every turn's tokens, tools, seconds and spend, and the shape of it as charts — `/pull` copies sandbox work back to disk, `/settings` opens configuration, `/voice` records a prompt, and `/keys` shows keyboard controls.
+
+## Setup
+
+Archymedes needs one model provider. It uses the one you last switched to, or the first one configured, unless `--provider` says otherwise.
+
+The easiest interactive setup is:
+
+```bash
+archymedes settings
+```
+
+The menu is navigable with the arrow keys — Up/Down, PageUp/PageDown, Home/End — and Enter opens the highlighted setting. Values with a knowable set of answers (location, language, display currency, default provider) are picked from a list rather than typed, so choosing Rwanda does not require knowing it is `RW`, and each country shows the currency it selects. Typing letters filters a long list. Every row is still numbered and a typed number still jumps to it, which is the path that works with a screen reader; piped and scripted runs keep the plain numbered menu.
+
+Settings use the native per-user config directory on Windows, macOS, and Linux. Secret values are masked in the menu and the file is written with user-only permissions where the operating system supports POSIX modes. Environment variables always override saved settings, which keeps CI and one-off shell configuration predictable.
+
+```bash
+export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, or CIRCUITNOTION_API_KEY
+archymedes --providers                    # shows exactly what's set and what's missing
+```
+
+Anthropic models are priced in this build, so costs are reported without further setup. For any other model, set its published rate — otherwise Archymedes reports `cost unknown` rather than inventing a number:
+
+```bash
+export MODEL_INPUT_PER_MILLION=1.5      # per million tokens, in MODEL_PRICE_CURRENCY (default USD)
+export MODEL_OUTPUT_PER_MILLION=6
+export ARCHYMEDES_COUNTRY=RW                  # optional; otherwise LANG/LC_MONETARY is used
+export ARCHYMEDES_CURRENCY=RWF                # optional manual override; any supported ISO currency
+# Both are also in `archymedes settings`, where changing your location takes effect immediately
+export ARCHYMEDES_FX_RWF_PER_USD=1320         # required to show USD-priced models in RWF
+# Generic offline/manual pair: ARCHYMEDES_FX_FROM=USD ARCHYMEDES_FX_TO=EGP ARCHYMEDES_FX_RATE=48.5
+```
+
+Remote sandboxes additionally need `E2B_API_KEY`.
+
+Optional web search uses Exa. Add `EXA_API_KEY` through `archymedes settings` or your environment; `/providers` then reports `Exa search · web_search enabled`, and the agent receives a bounded highlights-only `web_search` tool. `EXA_BASE_URL` supports an Exa-compatible gateway without changing the tool contract.
+
+## Updating Archymedes
+
+Archymedes updates its global installation automatically by default in an interactive terminal. Once a day at startup it checks the public registry, pins the exact version it found, and installs it through npm, pnpm, Yarn, or Bun without another acceptance prompt. The running session remains on its starting version until restart. Piped/headless runs and CI never check or install. Use `/update check` for notification-only behavior or `/update off` to disable checks:
+
+```bash
+archymedes update
+archymedes --update
+archymedes update --check
+archymedes update --yes
+archymedes update --package-manager pnpm
+archymedes --version
+```
+
+Manual `archymedes update` still asks before installing; use `--yes` for an explicitly unattended manual update. Set `ARCHYMEDES_UPDATE_PACKAGE_MANAGER` to choose a persistent package-manager override.
+
+## How it behaves
+
+**Plan mode cannot write.** The write and command tools are not offered to the model at all — it's a capability boundary, not an instruction.
+
+**Approvals start with a consequence-based safety preflight.** Before estimation or model contact, build and auto modes detect credential disclosure or high-impact credential lifecycle changes, destructive data operations, production releases, financial transactions, private-data export, external publication, or weakened access controls. Interactive runs ask whether to continue; unattended runs fail closed unless the operator explicitly passes `--allow-sensitive`. Merely reading a project-local `.env`, inspecting a project-owned environment variable, or configuring a local token the user intentionally supplied is ordinary development work and does not trip this task-level gate.
+
+**Auto approval is guarded.** Auto mode skips prompts only for ordinary workspace-local edits and commands. It inspects the exact proposed command, file path, and new content first. Local secret reads such as `cat .env` may run, but credential-file writes, secret-like new content, likely credential transmission, production configuration, destructive or privileged commands, deploys, package publication, pushes, and network mutations still require a separate tool approval. Archymedes may use a pasted secret for the task the user named, but is instructed not to repeat it in prose, logs, summaries, examples, commits, or unrelated files, and never to send it to an unnamed external destination. `--allow-sensitive` acknowledges the task preflight; it never bypasses these operation-level gates. Build mode continues to ask for every effectful call. Decisions use `[y]es / [n]o / [a]lways / [d]eny always` and are remembered only for the exact action.
+
+**Locally, an approved command runs as you.** This is the part worth being plain about: on your own machine there is no sandbox around `run_command`. Once you approve it, it has exactly the authority your shell has — it can read and write files outside the project and reach the network. Archymedes narrows *what gets proposed* (plan mode cannot run commands at all, a small set are refused outright, and auto mode still stops for anything sensitive), and Archymedes contains the process *tree* on Linux so a cancelled or timed-out command cannot leave background processes behind. Neither of those is a security boundary. The approval prompt is the boundary, which is why it shows the exact command and why a tool that did not ship with Archymedes always says where it came from. When you need a real one, `--sandbox` and `--sandbox docker` put the work inside a container.
+
+**Spending is bounded before work starts.** `--budget N` is expressed in the selected local currency. In an interactive session Archymedes confirms that cap before starting a sandbox or calling a model; in a one-shot command the explicit flag is the approval. If the required FX rate is unavailable, Archymedes refuses to pretend it can enforce a converted cap.
+
+**Switching models is a menu, not a lookup.** `/model` opens a picker: arrow to a model and press Enter, with each one's price beside it and the cursor starting on the one in use. Press `t` and the same models become a table — input and output price in columns of their own, `←`/`→` to aim at a column and `s` to order by it, so "which of these is cheapest" is a keystroke rather than a read-through. Each row keeps the number `/model <n>` takes, so sorting never renumbers anything; `Esc` returns to the menu, and Enter switches from either view. Providers you have no key for are rows you can select, and selecting one opens settings — so a missing key is something you fix from where you noticed it. Typed forms skip the menu entirely: `/model opus` matches on any part of a model id and says which candidates it meant if the name is ambiguous. The transcript carries across the switch, and your choice is remembered for the next launch.
+
+**Large output leaves the conversation instead of being cut off.** A tool result too big for the transcript is written to `.archymedes/artifacts/`, and the model receives the beginning, the end, and the path. The end is the half that matters — a failing test says what failed on its last line — and the rest stays reachable through `read_file` with an offset, so nothing is lost to make room. Artifacts are content-addressed, so the same output repeated three times is one file.
+
+**Compaction happens at a boundary, and cannot quietly drop the rules.** Past 70% of the context window Archymedes summarizes as soon as the work reaches a clean stopping point; past 90% it summarizes regardless. A summary is lossy by design, so the governing facts are never left inside one: the permission mode, the original request, every action you approved or refused, and the plan's open items are re-derived from live state at each compaction and restated verbatim above the summary. A constraint that survives only as a sentence in a summary is a constraint that stops existing a few compactions later.
+
+**Undo is real.** Each turn snapshots the workspace into a private git index. `/undo` reverts modified files *and* removes files the agent created, without touching your staged changes.
+
+**Verification is required.** An agent that changes files and then declares success without running anything is reported as `needs_verification`, not `completed`.
+
+Passing targeted tests finish a focused change. Archymedes does not automatically pay another model
+round to demand new property tests and an assembled-app smoke test after every small fix; when no
+verification ran, it asks once for the smallest relevant existing check. If a model names a tool
+the current mode does not expose, the runtime returns that fact once so Plan mode can recover with
+a useful answer, then fails closed if the model repeats it.
+
+**Paying happens on the provider's page, never in the terminal.** `/pay 5000` tops up your Archymedes credit: Archymedes creates a checkout, shows the link, a short code and a reference, and waits. Your card, PIN and mobile-money confirmation are entered on Circuit Pay's own page — Archymedes never sees them and never asks. Nothing is created until you answer the confirmation, amounts are whole RWF (a decimal is refused, not rounded), and every attempt carries an idempotency key so a retried request cannot become a second charge. Ctrl+C stops waiting without cancelling the payment; if it is still unconfirmed, Archymedes says so and keeps the reference for `/pay status <ref>` rather than calling it failed. `/pay` on its own shows the gateway balance. If that endpoint is unavailable, `/balance 5000` stores the balance the user sees in their account and bypasses the endpoint; Archymedes labels it as locally estimated and subtracts measured token costs after every completed turn. `/balance clear` returns to the endpoint. Both sources power the low/critical alerts and pre-turn affordability check, but only an endpoint reading is called confirmed. Archymedes never tops up automatically.
+
+**Costs are honest.** Sub-cent amounts display as `$0.0034` rather than `$0.00`, converted amounts name the daily rate and its date, and an unpriced model says so instead of showing zero. Automatic conversion uses the keyless daily [exchange-api](https://github.com/fawazahmed0/exchange-api) endpoints with their fallback host; set `ARCHYMEDES_FX_OFFLINE=true` to disable lookup.
+
+**Estimates are token-based.** Before a turn, Archymedes counts the actual system prompt, conversation history, objective, and tool schemas, then forecasts cumulative input growth across the expected agent loop. `archymedes --estimate "task"` performs that preflight without starting a sandbox or calling a model. Provider-reported usage remains the final accounting truth.
+
+## Memory and recall
+
+Archymedes keeps durable memory in plain markdown you can inspect, commit, edit, or delete: project knowledge lives in `.archymedes/memory.md`; personal preferences live beside your Archymedes settings. `# we use bun, not npm` records a project fact. `/memory` shows both stores and their budgets.
+
+Memory is deliberately smaller than history. Core facts marked with `--core` are always recalled; everything else is selected locally for the current request by matching repository names, commands, files, and domain terms. Already-recalled entries are not sent again in the same thread. This keeps prompt cost bounded without an embedding service or sending memory to another provider.
+
+```text
+/memory add --kind convention we use bun, not npm
+/memory add --core --user --kind preference keep explanations concise
+/memory replace use bun => use bun 1.3 and never npm
+/memory recall package scripts
+/memory forget 2
+```
+
+Kinds are `preference`, `convention`, `decision`, `lesson`, and `fact`. Memory writes reject invisible formatting and instruction-shaped injection content. A unique text fragment can replace an entry, avoiding fragile row numbers when correcting knowledge. `/history search <text>` uses the local native SQLite + FTS5 index when its platform package is installed, returning ranked snapshot or journal evidence with context. It falls back automatically to verified session JSON when the native engine is unavailable. `/history status` shows which path is active. This is the larger episodic layer for details that do not deserve permanent prompt space.
+
+`/history resume` opens a searchable conversation chooser and works across processes. The saved
+permission mode returns with the transcript, while an explicit startup flag such as
+`archymedes --auto --resume …` deliberately overrides it. Archymedes's verification nudges are internal: they
+are neither counted as user turns nor indexed as things you said.
+
+Defender mode has a second, security-only memory layer. `query_defensive_brain` searches Archymedes's
+native Rust + SQLite FTS5 index and returns only a few reviewed records with confidence, review and
+expiry dates, and primary-source provenance. The reviewed corpus covers red teaming, vulnerability
+assessment and safe impact validation, application/cloud security testing, detection-evasion gap
+investigation, malware reverse engineering, cryptographic research, and threat intelligence.
+Existing `read_playbook` checklists remain the portable fallback when the native sidecar is absent.
+Web/Exa refreshes are quarantined candidates and never become active knowledge automatically.
+
+## Reliability evidence
+
+Archymedes's scheduled end-to-end suite runs build, debug, scoped search, Defender review, and
+cross-process resume journeys. It independently validates the result and scores completion,
+verification, valid tools, token economy, estimate calibration, scope, and state. The repository's
+`reliability/` directory contains the raw report and animated spectator UI. False success and
+silent permission escalation impose hard score caps.
+
+## Voice, language and keyboard input
+
+Run `/voice` to record from the default microphone, or `/voice path/to/audio.wav` to transcribe an existing file. The transcript is shown and can be edited or cancelled before it becomes a prompt. Voice transcription uses `OPENAI_API_KEY`, `gpt-4o-mini-transcribe` by default, and an OpenAI-compatible `/audio/transcriptions` endpoint. Set `VOICE_TRANSCRIPTION_URL` or `VOICE_MODEL` in `archymedes settings` when needed.
+
+Microphone recording uses `ffmpeg` because it provides one maintained capture path across operating systems. Install it with your normal package manager and set `VOICE_INPUT_DEVICE` if the default device is not correct. Archymedes uses PulseAudio on Linux, AVFoundation on macOS, and DirectShow on Windows; `ARCHYMEDES_FFMPEG_PATH` can point to a non-standard executable.
+
+Controls are available in English, Mandarin Chinese, Hindi, Spanish, French, Arabic, Bengali, Portuguese, Russian, and Urdu. Choose one in `archymedes settings`, set `ARCHYMEDES_LANGUAGE`, or pass `--language`. Stable slash-command names remain unchanged for scripts and muscle memory; `/help` and `/keys` localize their descriptions.
+
+Prompt history is persisted per user, deduplicated, and filters likely credentials. Tab completes commands, `@path` completes project files, arrow keys search history, Home/End navigate, Alt-Backspace/Ctrl-U delete, Ctrl-L redraws, and Ctrl-C interrupts the active turn.
+
+### Suggestions as you type
+
+Typing `/` opens a list above the input bar, narrowing with every letter and showing what each command does — plus the key that also runs it, so the list teaches its own shortcuts. Up and Down move through it and Enter takes a row; keep typing and it keeps narrowing; press Return and the command runs. It is never modal: every keystroke still reaches the line editor, so `/model haiku` types straight through the list that is offering `/model`. Greyed-out ghost text completes the rest of the name inline, and `→` accepts it.
+
+The list draws upward, into the rows directly above the bar. That is not a style choice — readline redraws its own line by erasing everything below it, so the rows above the bar are the only ones a list can occupy and survive a keystroke.
+
+### Keys
+
+The commands people reach for most are on Ctrl:
+
+| | | | |
+|---|---|---|---|
+| `Ctrl+A` auto mode | `Ctrl+W` wander | `Ctrl+S` settings | `Ctrl+G` palette |
+
+Every command with a shortcut also has an Alt mnemonic, which is the fuller set:
+
+| | | | |
+|---|---|---|---|
+| `Alt+W` wander | `Alt+M` model | `Alt+A` auto mode | `Alt+P` plan mode |
+| `Alt+D` diff | `Alt+U` undo | `Alt+C` cost | `Alt+O` tools |
+| `Alt+H` help | `Alt+T` new tab | `Alt+←` `Alt+→` tabs | `Alt+B` detach |
+
+**Tabs hold several pieces of work; the one in front is the one that runs.** Each tab keeps its own
+conversation, model, mode, cost and location, and switching away pauses that piece of work rather
+than leaving it running — a terminal transcript has one bottom, and two agents printing into it at
+once would interleave into something neither of them said. When you want work that keeps going while
+you do something else, that is `/detach`, `/jobs` and `/watch`: a detached job survives the terminal
+closing and streams into the session without taking the prompt. (Archymedes's desktop window is the other
+way round — it has a transcript per tab, so its tabs do run at the same time.)
+
+The function keys still work for the commands that had them (`F1` help, `F2` mode, `F3` model, `F4` wander, `F6` jobs, `F8` diff, `F9` todos) — several routes to the same command, so a terminal that swallows one does not cost you the feature. That redundancy is the reason there is a Ctrl layer at all: Alt is the modifier terminals are worst at delivering (tmux eats it by default, and macOS Terminal sends Option as a composition modifier unless you have found the "Use Option as Meta key" checkbox), so the most-used commands get a route that does not depend on it.
+
+Three of those Ctrl chords were readline line-editing keys, and taking them is not free. Each function moved to a key readline already handles natively, and `/keys` prints the move beside the chord that took it:
+
+| Was | Now | Still available as |
+|---|---|---|
+| `Ctrl+A` move to start of line | `/auto` | `Home` |
+| `Ctrl+W` delete the previous word | `/wander` | `Alt+Backspace` |
+| `Ctrl+S` XOFF flow control | `/settings` | — (raw mode disables flow control, so this key was inert) |
+
+A line-editing key can only be taken when its function has somewhere else to live, which is why `Ctrl+U` (delete to start of line) and `Ctrl+K` (delete to end) stay refused — nothing else does their job. `Ctrl+C`, `Ctrl+D`, Tab and Enter can never be rebound at all.
+
+There is no `Ctrl+M`. It is byte `0x0D`, which is exactly what Return sends, so no terminal can tell the two apart — binding it would fire the shortcut on every message you send. The same is true of `Ctrl+I` (Tab) and `Ctrl+J`. `/model` is on `Alt+M` and `F3`; asking for `ctrl+m` in your configuration reports this rather than failing silently.
+
+Bare letters are not shortcuts, for a reason worth knowing: this prompt is where you type your request, so a bare `w` for wander would cost you every message beginning with "write".
+
+`Ctrl+G` opens the command palette, which searches every command by name *or* by what it does — typing `revert` finds `/undo`, and letters that are not adjacent still match, so `wndr` finds `/wander`. Arrow keys, `Ctrl+P`/`Ctrl+N`, PageUp/PageDown and Home/End all move through it.
+
+`/keys` shows the live table, including anything your terminal is unlikely to deliver. To rebind, set `ARCHYMEDES_KEYS` (or the key-bindings entry in `archymedes settings`) to a comma-separated list like `/diff=alt+x, /wander=off`. An override replaces that command's default keys rather than adding to them.
+
+## Sandbox mode
+
+`--sandbox` runs everything in a disposable E2B container. Files exist only there; `--upload` seeds it with a copy of your project, and `/pull` brings results back.
+
+```bash
+archymedes --sandbox --upload "try upgrading to the new API and run the tests"
+```
+
+The sandbox executes commands as argv against an allowlist rather than through a shell, so pipes and redirection are unavailable there — Archymedes says so rather than failing obscurely.
+
+`--sandbox docker` uses a local Docker container instead of a remote one, for keeping work off your working tree without sending it to a third party. Pick the image with `--docker-image` or `DOCKER_CODING_IMAGE`.
+
+## Extending Archymedes: skills, hooks, plugins and MCP
+
+Everything here lives under `.archymedes/` in your project, so it travels with the repository and works the same in a local, Docker or E2B session. `/tools` lists whatever is currently loaded and where each piece came from.
+
+**Skills** are commands you name and describe, in `.archymedes/skills/<name>/skill.json`:
+
+```json
+{
+  "name": "coverage",
+  "description": "Reports test coverage for a package.",
+  "command": "npm run coverage -- --scope {{package}}",
+  "inputSchema": {
+    "type": "object",
+    "properties": { "package": { "type": "string" } },
+    "required": ["package"],
+    "additionalProperties": false
+  }
+}
+```
+
+`{{package}}` is filled in with the model's argument, quoted for the shell that will run it — arguments are never pasted into the command raw.
+
+**Hooks** are scripts that see every tool call, in `.archymedes/hooks/pre-tool-use/` and `.archymedes/hooks/post-tool-use/`. They run in filename order and receive the call as base64 JSON in `ARCHYMEDES_HOOK_EVENT_B64`. A pre-tool-use hook that exits non-zero blocks the call and its stderr becomes the reason the model is given; a post-tool-use hook can only warn, since the work has already happened.
+
+**MCP servers** go in `.archymedes/mcp.json` as `{ "servers": [{ "id": "…", "command": "…", "args": [], "env": {} }] }`. Archymedes speaks stdio JSON-RPC to them and offers their tools alongside its own.
+
+**Plugins** bundle all three under `.archymedes/plugins/<name>/`, with a `plugin.json` naming any MCP servers plus optional `skills/` and `hooks/` directories in the same formats.
+
+Every tool that does not ship with Archymedes is approval-gated on every call regardless of mode, and the approval prompt names where it came from — a tool called `deploy` from an MCP server never looks like one of Archymedes's own.
+
+On Windows, hook scripts need an extension `cmd.exe` can execute (`.cmd` or `.bat`, or a `.ps1` invoked through one); a `.sh` file will not run without a POSIX shell installed. Skill commands and hook invocations are quoted for `cmd.exe` automatically when the session is local — a sandbox session is always quoted for Linux, since that is what the container runs.
+
+## Editors: the Agent Client Protocol
+
+`archymedes acp` runs the same agent over stdio in [ACP](https://agentclientprotocol.com), the protocol Zed and JetBrains use to host an agent, so an editor can drive a Archymedes session without a bespoke integration. Streaming replies arrive as `session/update` notifications, every tool call is announced and updated, and an approval becomes a `session/request_permission` request the editor answers — the same four decisions the terminal offers, with the same rule that anything other than an explicit allow is a refusal.
+
+```jsonc
+// what an editor sends, one JSON-RPC message per line
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
+{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/path/to/project"}}
+{"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"…","prompt":[{"type":"text","text":"fix the failing test"}]}}
+```
+
+`session/load` resumes a stored session, and `session/set_mode` switches between `plan`, `build`, `auto` and `defender` — rebuilding the session under the new capability set, exactly as `/mode` does in the terminal, because plan mode is a mode in which the write tools are not loaded rather than one where they are discouraged. While `archymedes acp` is running, stdout carries only protocol messages; diagnostics go to stderr.
+
+## Requirements
+
+Node 22.5 or newer on Windows, macOS, or Linux. `git` enables checkpoints (Archymedes degrades to no-undo without it). `ffmpeg` is optional and needed only for direct microphone recording; existing audio files can still be transcribed without it.
+
+Apache-2.0 licensed.
+
+
+## The Archymedes terminal
+
+The default `archymedes` theme uses bronze instruments, limestone text and olive accents.
+The opening instrument, composer, turn status line, result cards and workspace share the active palette. Startup is
+static and uses a compact identity on short or narrow terminals, leaving room for the conversation.
+Light terminals automatically use `parchment`; `blueprint`, `chalkboard` and `high-contrast` remain
+available through `/theme list`. Use `archymedes --theme blueprint` to keep the previous palette.
+`NO_COLOR` and `--ascii` retain plain output and compatible glyphs.
+
+Result cards distinguish failed checks, interrupted work and verification still needed. Changed
+files include `/diff` and `/undo` as the next review actions. A green result requires completed work
+and passing checks recorded by the runtime.
+
+## Release validation
+
+From the repository root, run `bun run release:check`. This tests and builds the packages, inspects
+the CLI archive, installs that exact archive in a temporary consumer, and verifies Node startup and
+TUI dependency resolution. The reviewed archive and SHA256 checksum are written to `artifacts/`.
+See [the release assessment](https://github.com/chrisnkuno/archymedes-cli/blob/main/docs/RELEASE_ASSESSMENT.md) for scope and remaining release proof.