atom-agent 1.2.0 → 1.4.0

package/documentation/architecture.md

@@ -0,0 +1,114 @@
+# Architecture
+
+ATOM is a flat-modules codebase with a few directories where a real seam
+exists. The rule is responsibility + dependency direction, never line counts:
+coherent single-file modules stay single files.
+
+## Module map
+
+```text
+cli.tsx -> App.tsx (App) -> everything (UI root, the only React owner)
+                              |
+ui/{transcript,input,todo-panel}  (prop-driven memo leaves, no App import)
+ui/{pickers,modals,status-bar,live-tail,palette}  (presentational shells; status-bar
+    formats via context-windows, approval text arrives pre-formatted)
+ui/theme  (design tokens: every color/glyph/separator/border/spacing value;
+    components reference tokens, never literals)
+ui/markdown  (zero-dep markdown for assistant turns: headings/lists/code/
+    links/quotes; bounded parse cache; MarkdownStream auto-closes transient
+    markers mid-stream and converges to the committed shape; tool lines stay
+    full-fidelity — ToolLine renders call/warning/denied/retry/cancel states
+    from shape, suffixing `· Ns` on slow calls from display-only Turn.ms)
+ui/errors  (typed error cards for tool turns: tool/denial/network/model/
+    cancelled/config/internal; adjacent [audit label, error detail] pairs
+    merge in TranscriptView; full diagnostics stay in the inspector store)
+ui/transcript  (static scrollback: committed turns print once via <Static>
+    and are never rewritten — a full-page transcript no longer flashes on
+    every keystroke (Ink clearTerminal path); commit frontier follows by
+    default, PgUp//autoscroll-off freezes new commits with a `↓ N new`
+    indicator, End resumes the backlog; banner once per Static identity;
+    /thinking toggle is forward-only for committed blocks; global turn keys
+    keep rows stable)
+ui/tool-inspector  (Ctrl+O browse + expand panel for retained tool results:
+    capped store, windowed list, viewport-scrolled output with explicit
+    truncation; transcript untouched — expansion lives in the
+    dynamic zone)
+ui/activity  (working-state model: thinking-gap + verb-mapped tool lines;
+    liveness from ticking elapsed seconds, never animated spinners)
+ui/modals  (approval/question dialogs: arrows+Enter select, y/a/t/n pinned;
+    command preview split from the audit prefix; policy untouched)
+ui/diff, ui/highlight, ui/diff-view, ui/side-by-side  (zero-dep diff stack:
+    unified engine + line-scoped syntax tokenizer + unified view +
+    side-by-side BEFORE/AFTER view with narrow-terminal fallback; approved
+    write/edit results commit their diff on the audit turn, stripped on save)
+ui/diff-panel  (session-changes review: file list grouped by path with
+    per-file side-by-side detail; same renderer as the transcript)
+ui/input + input-model  (multiline box with line/col cursor, Ctrl+J newline,
+    bracketed paste via usePaste, readline kills, in-memory prompt history;
+    Enter always sends; slash menu stays single-line)
+slash matching  (App-owned: exact input collapses to one command;
+    otherwise prefix tier stable + fuzzy tier scored, one
+    matcher for commands and skills; skill rows carry truncated
+    descriptions; usage footer reuses the commands' own usage strings)
+                              |
+agent/loop  ->  agent/gates  ->  tools/* (getTodos)
+    |    \--->  agent/types (types only)
+    |    \--->  scheduler -> tools (validators)
+    |    \--->  config, context-manager, tools (executors)
+    v
+zen.ts (transports, dispatch, prefs, prompt assembly)
+    ├── re-exports agent/* + context-manager surface (compat)
+    └── imports agent/loop (one direction only)
+                              |
+tools.ts (pure barrel)
+    ├── tools/registry (names, validation, dispatch, schemas)
+    ├── tools/filesystem (read/write/edit + snapshots + fingerprints)
+    ├── tools/search (grep/glob)   tools/shell (bash/tasks)
+    ├── tools/web (fetch/search)   tools/todo (checklist state)
+    └── tools/shared, tools/overflow, tools/fingerprints (kernel)
+                              |
+context-manager.ts, compact.ts, prompt-cache.ts, env-block.ts, context-windows.ts   (context systems: flat files, one seam each)
+session.ts + snapshots.ts   (persistence + pre-mutation snapshots)
+policy.ts + permissions.ts + rollback.ts   (policy decisions, rule matching, turn rollback)
+skills.ts — registry, loader, matcher (intentionally one file:
+        discovery and parsing must stay byte-identical)
+providers.ts, adapters.ts, kilo.ts   (provider types, wire adapters, Kilo gateway)
+```
+
+## Dependency rules (enforced by tests/architecture.test.ts)
+
+- The runtime import graph is acyclic (type-only imports don't count —
+  they erase at compile).
+- `react`/`ink` live only in `cli.tsx`, `App.tsx`, `ui/*`. No runtime
+  module imports the UI; tools, providers, context-manager, policy,
+  scheduler, and everything under `agent/` are UI-free.
+- `policy.ts` depends only on `permissions.ts` at runtime (plus types):
+  it stays usable by future subagents with no fs/net/UI baggage.
+- Inside `tools/`, executors never import the registry — the registry
+  owns names/validation/dispatch and sits above them.
+- Inside `agent/`, loop/gates/types never import `zen` at runtime —
+  `zen.ts` re-exports them for compatibility, never the reverse.
+- The scheduler reasons from `TOOL_EFFECTS` metadata, not per-tool
+  branches; missing metadata fails safe to serial.
+
+## What was deliberately NOT split
+
+- `skills.ts`: registry + loader + matcher share one parser that must
+  stay byte-identical across paths (says so in its header).
+- `App.tsx` beyond the `ui/` leaves: the rest is hooks-entangled
+  session state — splitting it further would be prop-drilling, not
+  boundaries. Pure helpers already live at module scope and are
+  directly unit-tested (slash menu, pickers, filters).
+- `zen.ts` transports: one dispatch + per-kind wire functions belong
+  together; the loop, gates, and types now live in `agent/`.
+- Flat coherent modules (`config`, `session`, `snapshots`, `compact`,
+  `prompt-cache`, `env-block`, `auth`, `system`): renaming them into
+  directories would be motion without meaning.
+
+## Verification
+
+`tests/architecture.test.ts` scans the real source on every run, so
+drift fails loudly with the exact file + edge. Behavior is pinned by
+the full suite: every extraction above kept all
+importer paths working (barrels + re-exports), and the suite is the
+proof — no behavior change was made or needed.

package/documentation/cli.md

@@ -0,0 +1,82 @@
+# CLI and TUI
+
+ATOM is an Ink (React) TUI. Entry is `src/cli.tsx`, rendered by `src/App.tsx`. There is no persistent header, only the launch-time banner. The status line is the sole info bar.
+
+## Launch
+
+```bash
+npm start        # run the TUI from source (needs a TTY)
+atom             # run the installed binary (runs dist/cli.js)
+atom --help      # usage, env vars, commands, providers (exits, no TUI)
+atom --dashboard # write ~/.atom/telemetry/dashboard.html and exit (no TUI)
+atom --serve [--port <n>]  # serve the live observability webUI on loopback (no TUI, Ctrl+C stops)
+```
+
+`--help` (or `-h`) prints usage and exits. `--dashboard` and `--serve` handle local observability without starting the TUI (see [Observability](observability.md)). Any other invocation starts the TUI, even without a key.
+
+## Slash commands
+
+Type `/` to autocomplete as you type. Full registry (`src/App.tsx`):
+
+| Command | What it does |
+|---|---|
+| `/model` | Unified model picker: active provider first, then other keyed providers plus the always-visible keyless Kilo list (free models badged `(free)`, `free` filters them). Cross-provider pick switches provider |
+| `/models [refresh]` | Local discovery status; `refresh` re-probes local servers (or the Kilo gateway catalog while Kilo is active) |
+| `/provider` | Provider plus key picker; validates and stores in `~/.atom/auth.json` (Kilo key optional — empty Enter continues anonymously) |
+  | `/new` | Start a brand-new session (conversation plus counters reset, previous kept for `/resume`) |
+  | `/rename <name>` | Rename the current session (id and history untouched; quotes optional) |
+| `/plan`, `/yolo` | Retired as typed commands — `Tab` is the only mode switcher (normal → yolo → plan → normal); typing them explains this instead of switching |
+| `/effort` | Reasoning-effort picker (`Auto`/`Low`/`Medium`/`High`/`Max`; sent for every model on every provider — `reasoning_effort` on OpenAI-chat, thinking budget on Anthropic, thinking level on Gemini; `Auto` omits it) |
+| `/tools` | List tools with one-line descriptions |
+| `/skills` | List installed skills (project plus global) |
+| `/skill` | Invoke a skill by name (`/skill:name`; skills also complete in the `/` menu) |
+| `/context` | Show context usage by source (system, tools, history, skills, config, prefix-cache) |
+| `/queue` | List queued follow-ups (`/queue clear` wipes; cap 10, in-memory only) |
+| `/steer` | Steer the running turn, or send when idle (`/steer <text>`) |
+| `/autoscroll` | Toggle following new output (on by default; bare toggles, `on|off` sets it; off freezes the view mid-turn) |
+| `/mode` | Print the current permission mode |
+| `/trust` | Toggle session trust: auto-approve write/edit/bash without full yolo. Again revokes |
+| `/allow <tool[:glob]>` | Pre-approve a tool pattern this session |
+| `/deny <tool[:glob]>` | Forbid a tool pattern this session. Deny wins over trust/yolo |
+| `/rules` | List session allow/deny rules. `/rules clear` wipes them |
+| `/clear` | Clear conversation history (keeps session token totals) |
+| `/compact [focus]` | Summarize older turns into one summary. Optional focus text |
+| `/goal <objective>` | Pin one session goal (bare shows it; `pause` / `resume` / `clear` manage it; see [Goals](goals.md)) |
+  | `/resume` | Restore the last saved session (turns, history, settings, usage) |
+  | `/session [filter]` | Switch the active session (interactive most-recent-first picker with fuzzy filter; `Enter` switches, `Esc` cancels) |
+| `/telemetry` | Show the local observability summary (sessions, tokens, tools) |
+| `/dashboard` | Write the local observability dashboard page and show its path |
+| `/rewind` | Restore files to a session checkpoint. Files only, never shell side effects |
+| `/help` | List commands with one-liners |
+| `/exit`, `/quit` | Exit ATOM |
+
+`/compact`, `/allow`, `/deny`, `/rules` accept prefix forms (`/compact focus...`, `/allow bash:npm test*`). `/rename` takes the rest of the line as the name; `/session` takes an optional initial filter.
+
+## Keyboard
+
+- `Tab`: cycle permission mode normal → yolo → plan → normal (in the `/` menu, Tab runs the highlighted command instead)
+- `Esc`: stop a running response (footer shows `esc stops` while busy); deny a pending approval/question
+- `/`: open command autocomplete (typing a full command name collapses the menu to it)
+- `Ctrl+O`: open the tool-output inspector (browse past tool calls; `↑`/`↓` select, `Enter` expands, `PgUp`/`PgDn` scroll, `Esc` closes)
+- `Ctrl+P`: command palette (searchable, same registry)
+- `Ctrl+C`: cancel the running turn; exit when idle
+- `PgUp`/`PgDn`: scroll the transcript (`End` follows latest)
+- `↑`/`↓`: recall past prompts; `Ctrl+J` inserts a newline (`Enter` always sends)
+- `y` once, `a` always, `t` trust all, `n` deny: answer write/shell approval prompts in normal mode
+
+## Status line
+
+Format when idle: provider/model │ token │ cwd[` : `branch] │ reasoning │ mode (`+trust` when session trust is on, hidden in plan mode) │ goal (only while a goal is live: `goal: <objective> [active|paused]`, truncated to fit — it yields first under width pressure and never displaces other segments). While busy: live activity │ elapsed │ token │ reasoning │ mode │ goal (same goal segment when live) │ `esc stops` (+`waiting…` / `waiting approval` flags).
+
+Token segment (`src/context-windows.ts`):
+
+- `token: n/a`: no usage reported yet. Never estimated
+- `token: (P%) NK`: known context window. NK is cumulative session spend in K (`round(total/1024)`). P% is current context load over the verified window (last POST input tokens including prefix-cache reads, else the 4 chars/token estimate)
+- `token: NK`: model has no verified window. Bare total only
+- `token: 0K` / `token: (0%) 0K`: zero usage, with/without a known window
+
+## Reasoning and streaming
+
+Tokens, tool activity, and phase status render live. Reasoning streams in its own dim block above the answer draft (transient). Tool calls execute locally and results feed back into the loop with no step cap by default (optional cap via `ATOM_MAX_TOOL_STEPS`, clamped 5-100).
+
+See [Sessions](sessions.md), [Compaction](compaction.md), and [Permissions](permissions.md) for the systems behind these commands.

package/documentation/compaction.md

@@ -0,0 +1,50 @@
+# Compaction and Token Display
+
+Claude-Code and opencode-style context management (`src/compact.ts`, `src/context-windows.ts`, `src/context-manager.ts`). History budgets derive from the model window (see [Configuration](configuration.md)); compaction mechanics below are unchanged.
+
+## Auto-compact
+
+Triggers at about 83% of the model verified context window:
+
+- Threshold fraction default `0.83`
+- Env `ATOM_COMPACT_PCT` is a percent (example `"83"`), clamped 50-95. Invalid or unset falls back to default
+- Load metric: last POST reported input-side tokens (prompt counts normalized to include exclusive prefix-cache counters like Anthropic's `cache_read`/`cache_creation`) when available, else the 4 chars/token estimate of sent history chars
+- No verified window for the model: never auto-compacts, never invents a window
+
+## Manual compact
+
+```text
+/compact [focus text]
+```
+
+Summarizes older turns into one summary with tools disabled and a 4096 output cap. Optional focus text narrows the summary (example `/compact focus auth flow`).
+
+Mechanics:
+
+- Split history (after system) into head plus retained newest tail of whole user-turns up to about 20000 estimated tokens (chars/4)
+- Tool outputs in the tail capped at 2000 chars each
+- Always keeps at least the newest turn. When everything fits but there is more than one turn, keeps only the newest turn in the tail so manual compact still has an older turn to summarize
+- Summary instruction uses fixed headings (omit a section only when empty): Objective, Important Details, Work State (Completed, Active, Blocked), Next Move, Relevant Files
+- Rules line: no tools available for the request, answer with summary text only
+- Swap is atomic plus saved. Size-overflow truncates head to budget once (drops oldest half of user-turns, preserves pairing) and retries once, then suggests `/clear`. Other failures throw with history untouched
+- Touched files: the compacted summary records the head's read/modified paths (collected from the committed tool calls the loop already recorded — no new tracking), appended as a `Touched files:` block (`Read:` / `Modified:` lines). Over-budget lists shrink oldest-first to the summary budget instead of failing compaction; the model text is never cut. `/resume` surfaces the stored block verbatim
+- Goal block: when a goal is live, compaction appends a `Goal:` line (objective, state, cumulative stats, open todos) to the summary as context for the continued run. Restore still rides the persisted session record (`goal` field, see [Sessions](sessions.md)) — the `Goal:` text keeps the objective visible in history without re-exploring the tree
+
+Thrash guard: 3 auto-compactions without the load dropping below threshold disables auto for the session (manual `/compact` still works and resets the counter on success).
+
+## Token display
+
+Exact footer format (`formatTokenSegment`):
+
+- `token: n/a`: no usage reported yet. Never estimated
+- `token: (P%) NK`: known window. NK is `round(total/1024)` plus `K` from cumulative session spend (`total_tokens`, else `prompt_tokens` plus `completion_tokens`). P is `round(100*load/window)` from current context load, not cumulative spend
+- `token: NK`: unknown window. Bare total only
+- Zero usage with known window: `token: (0%) 0K`. Without one: `token: 0K`
+
+Cumulative spend keeps growing after compaction, so it must not drive P. Load does.
+
+## Verified windows
+
+Curated per-model map in `src/context-windows.ts` (build-time vendor docs, comments cite sources). Missing models render without a percent. Examples from the map: DeepSeek V4 family 1M, Kimi K2.6 256K, GLM-5.2 1M, GPT-6/GPT-5.6 1.05M, Gemini 3 family about 1M. Read the file for the full table; do not assume a window for unlisted models.
+
+Related: [Sessions](sessions.md) for persistence, [CLI](cli.md) for the footer, [Configuration](configuration.md) for `ATOM_COMPACT_PCT`.

package/documentation/configuration.md

@@ -0,0 +1,111 @@
+# Configuration
+
+All knobs, files, and prompt layering in one place. Env vars win over stored keys. Nothing here requires code changes.
+
+## Environment variables
+
+Template lives in `.env.example`. Never commit a real key.
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `KILO_API_KEY` | Kilo key (optional — free models work anonymously). Wins over stored Kilo key | none (Kilo free models still chat; `/provider` shows the key as optional) |
+| `OPENCODE_ZEN_API_KEY` | Zen key. Wins over stored zen key | none (TUI still starts, chat errors inline with a `/provider` pointer) |
+| `OPENCODE_ZEN_MODEL` | Zen model id | `deepseek-v4-pro` |
+| `OPENCODE_ZEN_ENDPOINT` | Zen endpoint override | `https://opencode.ai/zen/v1/chat/completions` |
+| `OPENCODE_AGENTS_PATH` | Override for the AGENTS.md appended to the system prompt | `<cwd>/AGENTS.md` |
+| `OPENAI_API_KEY` | OpenAI key (env wins over stored) | none |
+| `ANTHROPIC_API_KEY` | Anthropic key | none |
+| `DEEPSEEK_API_KEY` | DeepSeek key | none |
+| `MISTRAL_API_KEY` | Mistral key | none |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Gemini key (either accepted, first non-empty wins) | none |
+| `ATOM_COMPACT_PCT` | Auto-compact percent, clamped 50-95 | `83` (about 83% of verified window) |
+| `ATOM_MAX_TOOL_STEPS` | Optional cap on tool rounds per turn, clamped 5-100 | uncapped |
+| `ATOM_HOME` | Override home for `~/.atom/` files (auth, session) | OS homedir |
+| `ATOM_TELEMETRY` | Local observability recording (`0`/`false`/`no`/`off` disables; `1`/`true`/`yes`/`on` forces on) | on (wins over `atom.json`) |
+| `ATOM_TELEMETRY_PORT` | Pinned port for the observability webUI (`atom --serve`; `--port` wins over this) | ephemeral (OS-assigned, printed on start) |
+| `ATOM_EXTENSIONS` | Extra extension directory for discovery (project, global, then this; see [Extensions](extensions.md)) | none |
+| `ATOM_OLLAMA_URL` | Ollama base URL override for local discovery | `http://localhost:11434` |
+| `ATOM_LMSTUDIO_URL` | LM Studio base URL override for local discovery | `http://localhost:1234` |
+| `ATOM_LLAMACPP_URL` | llama.cpp base URL override for local discovery | `http://localhost:8080` |
+
+`openai-compatible` uses stored key plus baseURL only. No env vars.
+
+## atom.json config file
+
+Template lives in `atom.example.json`. Two levels, merged per key (project wins over global):
+
+- Project: `<cwd>/atom.json`
+- Global: `~/.atom/atom.json` (`ATOM_HOME` overrides home)
+
+Precedence overall: env vars > saved session picks (`/model`, `/provider`, `/effort`) > project `atom.json` > global `atom.json` > compiled defaults. So `atom.json` sets first-run and project defaults; a later explicit pick (saved each turn and on exit) still wins across restarts; env always wins.
+
+| Key | Purpose | Range / values |
+|---|---|---|
+| `provider` | First-run default provider (needs its key, except keyless Kilo/local) | known provider id |
+| `model` | Default model id | non-empty string |
+| `reasoningEffort` | Default reasoning effort | `auto`/`low`/`medium`/`high`/`max` (`default` still accepted as an alias for `auto`) |
+| `maxToolSteps` | Tool rounds per turn | 5-100 (default 30) |
+| `compactPct` | Auto-compact percent of verified window | 50-95 (default 83) |
+| `network` | Webfetch SSRF policy: which network zones the model may retrieve | object with boolean `allowPublic` (default true), `allowLocalhost` (default true), `allowPrivate` (default false), `allowLinkLocal` (default false) |
+| `telemetry` | Local observability recording (see [Observability](observability.md)) | `{enabled?: boolean}` (default on; `ATOM_TELEMETRY=0` wins) |
+| `extensions` | Extension enable/disable patterns by name (see [Extensions](extensions.md); CLI `--enable-extension`/`--disable-extension` win over this) | `{enabled?: string[], disabled?: string[]}` (default load all; `disabled` wins over `enabled`) |
+
+Missing files are normal and silent. Unknown keys are ignored; invalid values fall back per key with warnings surfaced in `/context`. Reads are fresh per call, so edits apply without restart. Never commit keys here (there are no key fields — keys stay in env/`auth.json`).
+
+Example: open the LAN but keep cloud metadata closed:
+
+```json
+{ "network": { "allowPrivate": true } }
+```
+
+## Context budget (`src/context-manager.ts`)
+
+The `ContextManager` is the single place answering: how much context is available, how much is used, should we compact. History allowance derives from the model's verified window:
+
+```text
+available history = window − system prompt − tool definitions
+                    − output reserve (4096 tok) − safety margin (5%)
+```
+
+The allowance is informational only: history is never truncated — there are no message/char caps (`ATOM_MAX_HISTORY_*` env vars and `maxHistory*` config keys no longer exist; if present in `atom.json` they are ignored as unknown keys). Compaction is the only pressure valve.
+
+- Known-window models (256K, 1M, …) use their real windows — no fixed 200K-char assumption.
+- Accounting is incremental: the `ContextLedger` (`trackHistory` in `src/context-manager.ts`) keeps exact running counters (messages, chars, est. tokens, system/tool chars, per-role counts) across pushes, splices, and replacements — per-step reads are O(1) instead of rescanning history. `verifyLedger` diffs counters against an independent scan (tests enforce it; exact provider-reported usage stays separate in the token totals).
+- See `/context` for the live per-source breakdown and [Compaction](compaction.md) for the trigger mechanics.
+
+## Auth file
+
+`~/.atom/auth.json` (`ATOM_HOME` overrides home):
+
+```json
+{
+  "version": 1,
+  "providers": {
+    "<id>": { "apiKey": "...", "baseURL?": "..." }
+  }
+}
+```
+
+`0600` on POSIX, best-effort on Windows. Missing or corrupt loads as empty auth. Save via `/provider` paste flow; resolution is env-first per provider. See [Providers](providers.md).
+
+## Session file
+
+`~/.atom/session.json`, version 1, atomic temp-plus-rename saves, `0600` POSIX. See [Sessions](sessions.md).
+
+## AGENTS.md and system prompt
+
+Final system prompt is two layers (`src/system.ts`, `src/zen.ts`):
+
+```text
+<base one-liner from src/system.ts> + "\n\n" + <repo AGENTS.md>
+```
+
+- Base identity: long-horizon coding agent loop (explore, plan with todowrite for 3 or more steps, implement, verify with tests and typecheck, report with evidence)
+- Repo overlay: `AGENTS.md` in cwd, or `OPENCODE_AGENTS_PATH` override. Capped at 12KB
+- To change bot identity, edit the one-liner. To add project instructions, edit `AGENTS.md`
+
+ATOM loads the project `AGENTS.md` at startup so it knows tools, rules, and permission model. This repo own instructions live in `AGENTS.md` at the root.
+
+## Context windows
+
+Curated map in `src/context-windows.ts`. Drives the footer percent and auto-compact threshold. Never invented for unlisted models. See [Compaction](compaction.md).

package/documentation/development.md

@@ -0,0 +1,62 @@
+# Development
+
+Setup, scripts, structure, and verification for contributors. Commands below come from `package.json` scripts.
+
+## Setup
+
+```bash
+npm install
+npm start        # run the TUI from source (needs a TTY)
+```
+
+Build output goes to `dist/` (`atom` runs `dist/cli.js`). `dist/` is gitignored and shipped in the tarball.
+
+## Scripts
+
+```bash
+npm start        # tsx src/cli.tsx
+npm test         # vitest run (fully mocked, never hits live APIs)
+npm run typecheck  # tsc --noEmit
+npm run build    # tsc -p tsconfig.build.json (src -> dist)
+```
+
+Tests use `"test-key"` placeholders. Never paste a real key into fixtures, logs, or commits.
+
+## Project structure
+
+```text
+.
+├── src/
+│   ├── cli.tsx    # entry: --help/--dashboard/--serve, always starts TUI (missing key guides to /provider)
+│   ├── App.tsx    # Ink TUI: transcript, pickers (/model /provider /effort), modes, status line
+│   ├── context-windows.ts # curated per-model context windows + `token: (P%) NK` format
+│   ├── compact.ts # context compaction: load/trigger math, split, summary POST (tools off, 4096 cap)
+│   ├── zen.ts     # provider dispatch: streaming SSE, retries, agentic-loop wrappers (shared core in src/agent/loop.ts)
+│   ├── providers.ts # 8 remote providers + 3 local runtimes (kind/endpoint/env/default + fallback models; kilo default)
+│   ├── kilo.ts      # Kilo Gateway: live catalog parsing, :free detection, TTL cache, error normalization
+│   ├── auth.ts    # ~/.atom/auth.json store (env wins, 0600 POSIX)
+│   ├── adapters.ts # anthropic/gemini translation + SSE + models-list parsing + key validation
+│   └── tools.ts   # 13 local tool executors + function schemas
+├── dist/          # `npm run build` output (`atom` runs dist/cli.js; gitignored, shipped in the tarball)
+├── tests/         # fully mocked (never live APIs; keys use "test-key")
+├── AGENTS.md      # the agent's own instructions (loaded at startup)
+├── tsconfig.build.json # build-only config (src -> dist)
+└── .env.example   # env template (never commit a real key)
+```
+
+Full source adds: `env-block.ts`, `permissions.ts`, `policy.ts`, `rollback.ts`, `session.ts`, `sessions.ts`, `goal.ts`, `agent/goal-evaluator.ts`, `extensions.ts`, `extension-commands.ts`, `extension-ui.ts`, `project-trust.ts`, `skills.ts`, `snapshots.ts`, `system.ts`, `config.ts`, `scheduler.ts`, `context-manager.ts`, `prompt-cache.ts`, `local-discovery.ts`, `telemetry.ts` (local observability recorder + store), `telemetry-dashboard.ts` (self-contained HTML drill-down), `telemetry-server.ts` (loopback-only live webUI + read-only JSON API), `agent/` (shared loop core, gates, types), `tools/` (per-tool executors + registry, including `custom.ts`, `intercept.ts`, `overrides.ts`, `provider-hooks.ts`, `compaction-hooks.ts`), `ui/` (transcript, diff stack, panels, pickers, status line). Tests live in `tests/` (including `app`, `agent`, `loop-core`, `permissions`, `skills`, `compact`, `session`, `adapters`, `providers`, `kilo`, `tools`, `telemetry`, `diff`, `status-bar`, `slash` suites).
+
+## Verification standard
+
+Done means tests and typecheck pass, or the blocker is named with evidence. Minimum for a change:
+
+```bash
+npm test
+npm run typecheck
+```
+
+Add or update tests for behavior changes. A fix without a test that would have caught it is incomplete. Keep blast radius small: match existing patterns, remove dead code and debug leftovers, handle errors and edge cases explicitly.
+
+## Agent workflow in this repo
+
+The repo `AGENTS.md` defines the loop the agent follows: read before edit, 30 tool rounds per turn by default, todowrite list for 3 or more steps with exactly one `in_progress`, verify every change with the suite. Issues live as local markdown under `.scratch/` (see [Issue tracker](agents/issue-tracker.md)).

package/documentation/extensions.md

@@ -0,0 +1,160 @@
+# Extensions
+
+Write a local file, trust the project, restart — your code runs inside ATOM with the full ExtensionAPI. Three copy-paste samples under `examples/extensions/` prove each surface; the guide names them, the tests load them.
+
+## Install location (global vs project)
+
+| Scope | Directory | Trust |
+|---|---|---|
+| Global | `~/.atom/extensions/` (`ATOM_HOME` overrides home) | Implicitly trusted — user-owned, like your own config |
+| Project | `<cwd>/.atom/extensions/` | Gated — never executes until the project is trusted |
+| Explicit | `ATOM_EXTENSIONS` env (delimiter-separated paths) | Gated, like project scope |
+
+Each scope entry is a `.ts`, `.js`, `.mjs`, or `.cjs` file, or a subdirectory holding an `index.ts`/`index.js`/`index.mjs`/`index.cjs` (or a `package.json` with an `atom.extensions` manifest listing entry files). Dotfiles are skipped. Order is project, global, explicit.
+
+## Minimal file shape (factory export)
+
+One file, one factory — CJS or TS, both load same-process via jiti:
+
+```js
+// hello.js — put in ~/.atom/extensions/ (trusted) or <cwd>/.atom/extensions/ (gated)
+module.exports = function (api) {
+  api.notify("hello extension loaded");
+};
+```
+
+```ts
+// hello.ts — same contract, typed
+import type { ExtensionAPI } from "../../src/extensions.js";
+export default function (api: ExtensionAPI) {
+  api.notify("hello extension loaded");
+}
+```
+
+The export must be a function (or a default-exported function). Anything else is a recorded load error, not a crash — `loadExtensions` never throws; per-extension failures land on `runtime.errors` and the rest still load.
+
+## Trust prompt expectation
+
+With a project-scope extension present and the project not yet trusted, startup asks once via the question modal:
+
+```text
+This project contains 1 extension(s) (hello) that run unsandboxed with your full user privileges — they can read/write your files and run commands as you. Load them?
+```
+
+Answers are `Trust and load` (persists a per-project grant in `~/.atom/trusted-projects.json`) and `Keep disabled` (nothing executes, a visible skipped notice posts, asks again next boot). Esc declines. Extension code runs with your full privileges — no sandbox — so read anything you install first.
+
+## Enable, disable, lockdown
+
+- `--enable-extension <glob>` (repeatable): allowlist — only matching names load, the rest skip as `not-enabled`.
+- `--disable-extension <glob>` (repeatable): wins over enable; matches skip as `disabled`.
+- `atom.json` `extensions: { enabled: [...], disabled: [...] }`: same patterns in config; CLI wins over config when set; project config wins over global. See [Configuration](configuration.md).
+- `--no-extensions` (`--lockdown` alias): boots with zero third-party extensions — project, global, and explicit paths alike skip as `lockdown`. Builtins are untouched.
+
+Precedence, highest first: lockdown > untrusted-project > disabled > enabled > load.
+
+## How to see it loaded
+
+Startup posts one info line when anything loaded or failed:
+
+```text
+(extensions: 1 loaded (hello))
+```
+
+Skipped extensions stay visible with the fix:
+
+```text
+(extensions: 1 skipped (hello) — the project is not trusted; trust the project when asked on next startup to load them)
+```
+
+Then confirm the surface: `/tools` lists registered custom tools, the command palette (`Ctrl+P`) and the `/` menu list registered slash commands, the status line shows contributed segments.
+
+## Gallery (copy-paste samples)
+
+Single source of truth: the files under `examples/extensions/`. The guide excerpts them; the tests (`tests/extension-gallery.test.ts`) load the checked-in files through the real `loadExtensions` path — never a mock API, never a copy.
+
+**`01-audit-gate.js`** — destructive-command audit gate via `onBeforeToolCall`. Returning `{ block: reason }` vetoes the call: the reason commits as the model-visible result, approval is skipped, the tool never runs.
+
+```js
+api.onBeforeToolCall(({ name, args }) => {
+  if (name !== "bash") return;
+  const command = String(args?.command ?? "");
+  const DESTRUCTIVE = ["rm -rf /", "rm -rf ~", "rm -rf .", "mkfs", ":(){:|:&};:"];
+  if (DESTRUCTIVE.some((sig) => command.includes(sig))) {
+    return {
+      block:
+        "destructive shell commands need explicit confirmation — " +
+        "narrow the command or confirm it with the user first",
+    };
+  }
+});
+```
+
+**`02-notes-tool.js`** — model-callable tool via `registerTool` with a parameters schema and `execute`. Bad args are an inline `Error: invalid call: ...` and the implementation never runs; the tool dispatches through the shared loop like a builtin.
+
+```js
+api.registerTool({
+  name: "gallery_notes",
+  description: "Save a short note and read it back. Use it to remember user preferences across the turn.",
+  parameters: {
+    type: "object",
+    properties: { text: { type: "string" } },
+    required: ["text"],
+    additionalProperties: false,
+  },
+  execute: async (args) => {
+    notes.push(String(args.text));
+    return `saved note #${notes.length}: ${notes[notes.length - 1]}`;
+  },
+  requireApproval: false,
+});
+```
+
+**`03-custom-command.js`** — real slash command via `registerCommand` with a modal dialog plus transcript posts. The workflow logic is a pure helper (`summarizeChoice`) so the dialog flow is testable headless — tests drive the command with a stub `askUser` and unit-test the helper directly.
+
+```js
+api.registerCommand({
+  name: "gallery-plan",
+  description: "Pick a deploy target and post the plan.",
+  handler: async (ctx) => {
+    const choice = await ctx.askUser("Which environment?", ["staging", "prod"]);
+    const plan = summarizeChoice(choice, ctx.args);
+    ctx.say(plan);
+    return `plan posted for ${choice}`;
+  },
+});
+```
+
+## API surface (`src/extensions.ts`)
+
+Exact `ExtensionAPI` methods — nothing else exists:
+
+| Method | What it does |
+|---|---|
+| `on(event, handler)` | `session_start` / `session_shutdown` lifecycle |
+| `registerTool(def)` | New model-callable tool (`name`, `description`, `parameters`, `execute`, `requireApproval?`) |
+| `overrideTool(def)` | Audited, reversible builtin shadow (deny a subset or `ctx.passthrough`) |
+| `addPromptHint(hint)` | Model-facing guidance appended under "Extension hints" |
+| `registerCommand(def)` | Real `/name args` slash command (builtins always win name collisions) |
+| `onBeforeToolCall(handler)` | Rewrite `{ args }` or veto `{ block: reason }` pre-validation/pre-approval |
+| `onAfterToolCall(handler)` | Patch committed results (`string` or `{ content }`) |
+| `onBeforeSwitch(handler)` | Veto a pending session switch (throws fail open) |
+| `onTransformContext(handler)` | Replace the per-POST message array |
+| `onBeforeRequest(handler)` | Replace payload / mutate headers per POST |
+| `onAfterResponse(handler)` | Observe-only provider response hook |
+| `onBeforeCompact(handler)` | Veto compaction or replace the summary |
+| `getSessionState()` / `setSessionState(value)` | Per-session namespaced state (durable, JSON-serializable) |
+| `isProjectTrusted()` | Whether this load is trusted (degrade gracefully when false) |
+| `setStatusSegment(text)` | One status-bar slot per extension (upsert by owner) |
+| `setWidget(def)` | Panel widget (`placement: "panel"`, keyed by owner + id) |
+| `notify(message)` | Transient `(name) message` transcript line (staged queue caps at 100, drop-oldest) |
+| `promptUser(question, options?, allowCustom?)` | Modal dialog; rejects headless, during activation, or while one is open |
+
+Stores behind the API: `src/tools/custom.ts`, `intercept.ts`, `overrides.ts`, `provider-hooks.ts`, `compaction-hooks.ts`, `src/extension-commands.ts`, `src/extension-ui.ts`, `src/project-trust.ts`.
+
+## Rules that bite
+
+- **Staged activation is atomic.** Validation runs eagerly; a factory that throws (or a duplicate/colliding name at commit) leaves zero registrations behind — nothing half-loads.
+- **Stale generation.** Every session replacement invalidates handed-out APIs; captured handles throw loudly, event handlers always receive a fresh API.
+- **Approval fail-closed.** Custom tools require approval by default; opt out only with `requireApproval: false` for pure side-effect-free helpers.
+- **Serial by default.** Custom tools carry no scheduler metadata and run as serial singletons; `executionMode: "sequential"` forces the whole sibling batch one-at-a-time.
+- **Dialogs are single-flight and interactive-only.** A second request rejects, headless rejects, activation-time prompts reject — never a hang. Command `askUser` works because commands run outside activation with the TUI fulfilling the modal.

package/documentation/getting-started.md

@@ -0,0 +1,63 @@
+# Getting Started
+
+Fastest path from zero to chatting with an agent that can read, edit, and run your code.
+
+## Prerequisites
+
+- Node.js `>=18` (see `engines` in `package.json`)
+- No API key required to start: the default provider is Kilo Gateway, whose free models work anonymously
+- A TTY for `npm start` (the TUI needs an interactive terminal)
+
+## Install
+
+Global install gives you the `atom` binary:
+
+```bash
+npm i -g atom-agent
+atom
+```
+
+Or run from source:
+
+```bash
+npm install
+```
+
+## First run
+
+1. Just start it — no key needed:
+
+```powershell
+npm start
+```
+
+2. ATOM selects Kilo automatically, discovers its live model catalog, and starts on the free routing model (`kilo-auto/free`) when no Kilo key is configured. Open `/model` to see the discovered models (free ones carry a `(free)` badge) and pick one.
+3. Type `/` to see every command. Type `/provider` to paste a Kilo key once (optional — unlocks the full catalog) or to switch to another provider.
+
+No key at all: the TUI still starts, and Kilo's free models chat immediately. Providers that need a key error inline and point at `/provider` instead of posting. Nothing is posted without a usable route.
+
+To use a keyed provider instead (e.g. OpenCode Zen), get a key at `https://opencode.ai/auth` and set it for the session (PowerShell shown; use `export` on POSIX):
+
+```powershell
+$env:OPENCODE_ZEN_API_KEY="sk-your-key"
+npm start
+```
+
+## Quickstart path
+
+```text
+prerequisites
+-> npm install
+-> npm start (Kilo free model, no key)
+-> /model to pick a discovered model, ask something about your repo
+-> optional: KILO_API_KEY (or paste via /provider) for the full Kilo catalog
+```
+
+Expected result: streaming answer with live tool activity and a status line showing provider, model, token usage, reasoning effort, and mode.
+
+## Next steps
+
+- [CLI and TUI](cli.md) for slash commands and keyboard control
+- [Providers and Models](providers.md) to switch off Kilo, add a Kilo key, or use a local OpenAI-compatible server
+- [Configuration](configuration.md) for all env knobs and the auth file
+- [Troubleshooting](troubleshooting.md) if the first run fails