@datalabrotterdam/nova-ai-cli 1.1.0 → 1.2.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# [@datalabrotterdam/nova-ai-cli-v1.2.0-alpha.2](https://github.com/Datalab-Rotterdam/nova-ai-cli/compare/@datalabrotterdam/nova-ai-cli@1.2.0-alpha.1...@datalabrotterdam/nova-ai-cli@1.2.0-alpha.2) (2026-10-03)
+
+
+### Features
+
+* release the agent separately as @datalabrotterdam/nova-ai-agent ([32ecfc0](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/32ecfc0faa99bd5bb80cb2eaf2363abc050978f0))
+
+# [1.2.0-alpha.1](https://github.com/Datalab-Rotterdam/nova-ai-cli/compare/v1.1.0...v1.2.0-alpha.1) (2026-10-03)
+
+
+### Bug Fixes
+
+* **acp:** bounded, cancellable client terminals in the workspace ([81f7099](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/81f70996d9dfc8d78e12282def1582ea859f2784))
+* **acp:** isolate background prompt jobs from live session history ([8328a8b](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/8328a8bfa1f22871ef36ec38247987e6effcd044))
+* **acp:** replay loaded sessions faithfully; page session/list ([d576171](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/d5761710890f7b2f5d1b340cdce7faafcd2e3561))
+* **env:** no shells or Docker probes when a session starts ([dc3a449](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/dc3a4495f394c1a16e48e282efd76b765af09999))
+* **mcp:** connect servers in parallel with timeouts and diagnostics ([db4c62c](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/db4c62cd9c8ec0f197ea1ae1ce76adcf9d397ed5))
+* **models:** offer and default to chat models only ([5d3ade2](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/5d3ade2727110ca7555bfdfa5b174c9e75b151f9))
+* **security:** harden sessions, setup auth, credentials, processes and file access ([7f02a1d](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/7f02a1d203128555c4d00e5ab4dc4786329b6225))
+* **tui:** keep printed lines inside the terminal width ([dd5cd0a](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/dd5cd0a40592af392eca797399ce56c0e672110e))
+* **tui:** redraw cleanly after the terminal width changes ([f0b2ec6](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/f0b2ec6d01b0bd8ebcf087330c8bfd82072aa08d))
+
+
+### Features
+
+* **acp:** agentInfo and env_var authentication in initialize ([b736e11](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/b736e115542b8fef083f9fc75514586327d3ac49))
+* **acp:** namespace Nova extensions under _nova/ ([bf56cb9](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/bf56cb9e093dc90fc43b44008f1ddd86446a8cd0))
+* **acp:** serialized turns, cancel, shutdown and proper error codes ([6688470](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/66884701af129ff2c1e9ad78b9e572d7ec64cc4b))
+* **acp:** the agent owns permissions; clients only answer its questions ([7db651d](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/7db651d8d4883da2c170a831aeaa2952dc4444ac))
+* **acp:** usage, session info, commands and model options as updates ([21d0816](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/21d08160c558ca9431deff8f8ead25e89a93d21c))
+* added alpha stage on TUI ([3415411](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/3415411986ef4aefc2aa94dbb66fc73710fb6a5d))
+* **cli:** proper entry point, -p/--print, login/logout, help and version ([73c8f94](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/73c8f9472099fa7c3cedccdd3c6a315d809e6a00))
+* **core:** allow multiple tool calls per round ([f6a2171](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/f6a217145efac0722fddc49995808a7ad7bb2508))
+* **core:** compact proactively at 80% of the model context window ([96afcbb](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/96afcbb7b68f4686a9b769bb80a73b00eebfe4a4))
+* **core:** native tool calling with learned per-model text fallback ([6d71193](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/6d7119395b39a45026d676813ad3596382e2611a))
+* **core:** share the ~/.nova-ai project layout with the VS Code extension ([aa75dde](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/aa75dde65218fdbd16b9f329bd849cc9ec608a28))
+* **core:** validate tool args centrally before dispatch ([0a88e3e](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/0a88e3efb0d7c32611979e408b95e659873ec1e5))
+* expand ACP runtime and terminal workflows ([bfbae15](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/bfbae157c301fbc1b7e88f5e267d25c8da126008))
+* **mcp:** surface tool schemas, respect readOnlyHint, hint cwd args ([2b22be3](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/2b22be327b052788936e4badb010844f7ca3d057))
+* **memory:** shared MEMORY.md index + typed notes, compatible with VS Code ([474c916](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/474c91694f4da58400426f39c290ac6888f4aa19))
+* **modes:** plan mode can read, ask and keep the task list ([e253eaa](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/e253eaa66fd02478d61f34e734a27883068bf357))
+* **policy:** agent-side permission policy with trust-gated rule sources ([234cd3a](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/234cd3adf06423c973c52497e5e31f6868d6b19a))
+* **policy:** rule subjects for the extension's tool names ([5c188b6](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/5c188b610ff6e4ba8a715cc2ee10960736493b86))
+* **tools:** add JSON schema validator for tool args ([24764ef](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/24764ef5100c14404f1923f89cc87c3d64de510d))
+* **tools:** declare args schemas on every built-in tool ([79f6283](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/79f62833144f1a6aba9aaa65a2a19f18eb8793ca))
+* **tools:** whitespace-tolerant edit_file with self-correction hints ([a350e14](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/a350e140e92c8469249d4c6297aad8f8161a217f))
+* **tui:** Ink TUI with inline scrollback replaces pi-tui ([0725bae](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/0725bae27790829fd756afbdb5dd20574a1e0f00))
+* **tui:** Shift+Enter inserts a new line where the terminal can report it ([b9c0b70](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/b9c0b7041057e2bdeb1675bbfa33a12fc3a664b9))
+
+# [1.1.0](https://github.com/Datalab-Rotterdam/nova-ai-cli/compare/v1.0.1...v1.1.0) (2026-06-23)
+
+
+### Features
+
+* **acp-web:** theme support, favicon, font, and dep bumps ([0576402](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/0576402b6888a2cf6bc93123d733c4163358c63f))
+* **acp:** add MCP server support (stdio/http/sse) ([ba98b0c](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/ba98b0c0b2e2461e8553331cafa1985e7673ee43))
+
+## [1.0.1](https://github.com/Datalab-Rotterdam/nova-ai-cli/compare/v1.0.0...v1.0.1) (2026-06-22)
+
+
+### Bug Fixes
+
+* correct npm scope to [@datalabrotterdam](https://github.com/datalabrotterdam) ([6ab6bf8](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/6ab6bf88506cc1d4b778c1a30b123cd532a0a8de))
+
+# 1.0.0 (2026-06-22)
+
+
+### Features
+
+* add ACP agent, tool calling, and alpha release channel ([15d19a7](https://github.com/Datalab-Rotterdam/nova-ai-cli/commit/15d19a7998b4651ba9ad279fc2607006ea14ed49))

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-<img src="./assets/logo.png" width="96" height="96" alt="Nova logo" />
+<img src="https://raw.githubusercontent.com/Datalab-Rotterdam/nova-ai-cli/main/assets/logo.png" width="96" height="96" alt="Nova logo" />
 
 # @datalabrotterdam/nova-ai-cli
 
-**CLI for DataLab Rotterdam's Nova AI — also speaks Agent Client Protocol**
+**Agentic coding with DataLab Rotterdam's Nova AI: in your terminal, in scripts, and in your editor over the Agent Client Protocol**
 
 [![npm version](https://img.shields.io/npm/v/@datalabrotterdam/nova-ai-cli?style=flat-square&color=f96743)](https://www.npmjs.com/package/@datalabrotterdam/nova-ai-cli)
 [![npm downloads](https://img.shields.io/npm/dm/@datalabrotterdam/nova-ai-cli?style=flat-square)](https://www.npmjs.com/package/@datalabrotterdam/nova-ai-cli)
@@ -12,136 +12,195 @@
 [![ACP](https://img.shields.io/badge/ACP-agent-blue?style=flat-square)](https://agentclientprotocol.com)
 [![issues](https://img.shields.io/github/issues/Datalab-Rotterdam/nova-ai-cli?style=flat-square)](https://github.com/Datalab-Rotterdam/nova-ai-cli/issues)
 
-Talk to DataLab Rotterdam's Nova AI from your terminal, or point your editor/IDE at it via [Agent Client Protocol](https://agentclientprotocol.com) — both modes share the same auth and run on [`@datalabrotterdam/nova-sdk`](https://www.npmjs.com/package/@datalabrotterdam/nova-sdk).
-
-[npm](https://www.npmjs.com/package/@datalabrotterdam/nova-ai-cli) · [Issues](https://github.com/Datalab-Rotterdam/nova-ai-cli/issues) · [ACP docs](https://agentclientprotocol.com)
+[npm](https://www.npmjs.com/package/@datalabrotterdam/nova-ai-cli) · [Issues](https://github.com/Datalab-Rotterdam/nova-ai-cli/issues) · [ACP reference](https://github.com/Datalab-Rotterdam/nova-ai-cli/blob/main/docs/ACP.md) · [Settings and memory](https://github.com/Datalab-Rotterdam/nova-ai-cli/blob/main/docs/NOVA_HOME.md)
 
 </div>
 
-> **⚠️ Work in progress.** ACP mode (`--acp`) is the only fully implemented mode today — agentic tool use, permissions, and session persistence all work there. Interactive terminal chat (no flags) and the standalone browser UI (`--web`) are stubs that print a "not built yet" message. Expect breaking changes before a 1.0.
+`nova-ai` is a coding agent in the spirit of `claude` and `codex`, backed by
+[Nova AI](https://platform.nova.datalabrotterdam.nl). It reads and edits your
+code, runs commands with your permission, asks when a decision is yours, and
+keeps a task list for longer work. One agent, three front ends:
 
----
+- **Terminal UI**: `nova-ai`
+- **Headless**: `nova-ai -p "…"` for scripts, CI and machines without a GUI
+- **ACP agent**: `nova-ai --acp` for Zed, JetBrains, VS Code and any other
+  [Agent Client Protocol](https://agentclientprotocol.com) client
 
-## Installation
+The terminal UI and headless mode talk to the agent over the same protocol an
+editor uses, so all three behave the same: same tools, permissions, sessions,
+memory, MCP servers and settings.
 
-No install needed — run directly with `npx`:
+## Install
 
-```sh
-npx @datalabrotterdam/nova-ai-cli --setup   # store your Nova API key
-npx @datalabrotterdam/nova-ai-cli           # interactive chat (WIP, stub)
-npx @datalabrotterdam/nova-ai-cli --acp     # speak ACP over stdio (editors/IDEs) — fully working
-npx @datalabrotterdam/nova-ai-cli --web     # standalone browser UI (WIP, stub)
-```
-
-Or install globally / as a project dependency:
+Requires Node.js 22.19 or newer and a Nova AI API key
+([get one](https://platform.nova.datalabrotterdam.nl/dashboard/api-keys)).
 
 ```sh
 npm install -g @datalabrotterdam/nova-ai-cli
+nova-ai login          # opens a local page to enter the key; --no-browser asks in the terminal
+nova-ai                # start the terminal UI in your project
 ```
 
-**Requires:** Node.js >= 18, a [Nova AI](https://api.nova.datalabrotterdam.nl) API key.
-
----
+Or without installing: `npx @datalabrotterdam/nova-ai-cli login`, then
+`npx @datalabrotterdam/nova-ai-cli`.
 
-## Overview
+```
+nova-ai [options]                 Interactive terminal UI
+nova-ai -p [options] [prompt]     Run one request headless (see nova-ai -p --help)
+nova-ai --acp                     Agent Client Protocol over stdio (for editors)
+nova-ai login [--no-browser]      Connect your Nova AI account
+nova-ai logout                    Remove the stored API key
+
+Interactive options:
+      --resume <session-id>       Continue a saved session
+  -c, --continue                  Continue the most recent session in this folder
+      --model <id>                Use this model
+```
 
-`nova-ai-cli` is a terminal client for Nova AI, in the same spirit as `claude`/`codex`. Pass `--acp` to run it in Agent Client Protocol mode, where it reads JSON-RPC requests from stdin and writes responses/notifications to stdout so any ACP-aware editor/IDE can drive it like any other coding agent — with tool calling, permission prompts, and persisted session history. Bare/`--web` modes are placeholders for now. All modes share the same stored credentials.
+## Terminal UI
+
+The UI renders inline below your shell prompt. Finished messages go to the
+terminal's own scrollback (scroll, search and copy as usual); only the
+streaming answer, running tools, the prompt and the status rows are redrawn.
+
+- **Modes** (Shift+Tab): `agent` does the work; `plan` reads the code, asks
+  questions and builds a task list but changes nothing; `ask` only answers.
+- **Permissions**: before an edit or command you choose once, for this
+  session, always (saved as an exact rule) or deny. Ctrl+K switches between
+  asking, accepting edits, and bypass (never remembered).
+- **Questions and tasks**: the agent can ask 1–4 multiple-choice questions
+  (with descriptions, a recommended option and your own answer) and shows a
+  live checklist for multi-step work.
+- **Prompt**: history, `@file` mentions, `/command` completion, large pastes
+  as compact markers, Alt+V to paste an image (for models that accept
+  images). Messages typed while Nova works are queued; ↑ edits them.
+  `/steer <text>` reaches the running turn at the next tool boundary.
+
+| Key | Action |
+|---|---|
+| Enter / Shift+Enter | Send / new line (Shift+Enter where the terminal supports the kitty keyboard protocol: VS Code, kitty, WezTerm, Ghostty, foot, Alacritty, recent iTerm2; Alt+Enter, Ctrl+J or a trailing `\` work everywhere) |
+| Esc | Cancel the running turn |
+| Ctrl+C twice | Exit; prints `nova-ai --resume <id>` |
+| Shift+Tab | Cycle agent / ask / plan |
+| Ctrl+R / Ctrl+P / Ctrl+K | Sessions / models / permission mode |
+| Ctrl+O / Ctrl+T / Ctrl+B | Verbose tool output / tool inspector / background jobs |
+| Alt+V | Paste a clipboard image |
+
+Slash commands: `/help`, `/model`, `/mode`, `/permission`, `/session`,
+`/resume`, `/clear`, `/compact`, `/rewind [n]`, `/queue`, `/steer`, `/usage`,
+`/tools`, `/mcp`, `/skills`, `/shell` and `/agent` (background jobs), `/trust`
+and `/exit`. Details:
+[`src/tui/README.md`](https://github.com/Datalab-Rotterdam/nova-ai-cli/blob/main/packages/cli/src/tui/README.md).
+
+## Headless
 
 ```sh
-# 1. one-time setup — opens a browser page to verify the key against Nova AI and store it locally
-npx @datalabrotterdam/nova-ai-cli --setup
-
-# 2. point your ACP client at this binary
-npx @datalabrotterdam/nova-ai-cli --acp
+nova-ai -p "review the changed files"
+git diff | nova-ai -p --output-format json "summarize this diff"
+nova-ai -p --json --permission-mode accept-edits "fix the failing test"
+nova-ai -p -c "and now add a changelog entry"
 ```
 
-Most editors invoke `--acp` for you once configured as an agent — `--setup` is the one command you run by hand first.
-
-**Status:** `--setup` and `--acp` (including tool calling and session persistence) are fully implemented. Interactive terminal chat (no flags) and `--web` are stubs — see the WIP note above.
+| Option | |
+|---|---|
+| `--output-format text\|json\|stream-json` | `text` prints the answer; `json` one object at the end (text, tools, permissions); `stream-json` (or `--json`) JSON Lines while it runs: `session.started`, `message.delta`, `tool.started`/`tool.updated`/`tool.finished`, `permission`, `queue.changed`, `background.update`, `result`, `error` |
+| `--permission-mode` | `read-only` (default): anything that needs approval is refused, since nobody can approve it. `accept-edits`: file edits are accepted, commands still refused. `bypass-all`: everything is accepted. Deny rules always win. |
+| `--resume <id>`, `-c` | Continue a session |
+| `--model`, `--cwd` | Model and workspace |
+| `--trust-workspace` | Trust the workspace (remembered): start the MCP servers and apply the allow rules it declares |
+| `--no-mcp` | Ignore workspace MCP configuration |
 
----
+Exit codes: `0` success, `1` configuration or runtime error, `2` cancelled,
+`3` tool-turn safety limit, `130` interrupted.
 
-## Auth
+## Editors (ACP)
 
-This agent advertises **Agent Auth** (per [`AUTHENTICATION.md`](https://github.com/agentclientprotocol/registry/blob/main/AUTHENTICATION.md)): when the client calls `authenticate`, the agent itself spins up a local HTTP server, opens your browser to it, and resolves once you've connected your account.
+Configure `nova-ai --acp` as a custom agent. For Zed:
 
 ```json
 {
-  "id": "nova-api-key",
-  "name": "Nova API Key"
+  "agent_servers": {
+    "Nova AI": { "command": "npx", "args": ["-y", "@datalabrotterdam/nova-ai-cli", "--acp"] }
+  }
 }
 ```
 
-Today the page served at that local URL is a small Svelte form that:
-1. Collects your Nova API key.
-2. Validates it against `client.models.list()`.
-3. Picks a default model (first enabled model) and stores `{ apiKey, defaultModel }` in `~/.nova-ai/credentials.json`.
-
-You can also trigger this manually:
-
-```sh
-npx @datalabrotterdam/nova-ai-cli --setup
-```
-
-Overrides, no browser flow required:
-
-| Env var | Purpose |
+The agent supports session load/list/resume/fork/close/delete, modes, a
+permission-mode and model selector, permission requests with once / session /
+always options, client file system and terminals, form questions, plans, usage
+and title updates, MCP servers (stdio, HTTP, SSE), image prompts, and three
+login methods (browser, `NOVA_API_KEY`, or `nova-ai login` in a terminal).
+Nova-specific features (prompt queue, rewind, compaction, context usage,
+background jobs) are `_nova/…` extension methods. The agent is also published
+on its own as
+[`@datalabrotterdam/nova-ai-agent`](https://www.npmjs.com/package/@datalabrotterdam/nova-ai-agent)
+(command `nova-ai-agent`), without the terminal UI, for integrations that only
+need ACP. Everything is documented in
+[docs/ACP.md](https://github.com/Datalab-Rotterdam/nova-ai-cli/blob/main/docs/ACP.md).
+
+## Security model
+
+- **The agent enforces permissions**, not the client. Every front end and
+  every editor gets the same policy; a client can only answer the questions
+  it is asked. Anything other than an explicit "allow" counts as "deny".
+- **Deny rules win**, also in bypass mode and for read-only tools.
+- **A repository can't approve itself.** Allow rules in a workspace's
+  `.nova-ai/settings*.json`, and MCP servers it declares (`.mcp.json`), only
+  take effect after you trust that workspace (asked once at startup, `/trust`,
+  or `--trust-workspace`). The trust decision is stored in `~/.nova-ai`, never
+  in the repository. A repository can't set the permission mode either.
+- **"Always allow" saves an exact rule** for that command or path in your
+  private `~/.nova-ai/projects/<key>/settings.json`, outside the repository.
+  Compound commands (`a && b`, pipes) are checked part by part; substitutions
+  and nested shells need an exact rule.
+- **File access stays in the workspace** (symlinks resolved); commands run in
+  their own process group with a timeout, and the whole tree is stopped on
+  cancel.
+- **Credentials** are stored in `~/.nova-ai/credentials.json` with mode 0600.
+  The browser login page only accepts a one-time token from the same origin.
+
+## Settings, memory and sessions
+
+Everything lives in `~/.nova-ai` (or `$NOVA_AI_HOME`), shared with the Nova
+VS Code extension: settings, per-project trust, sessions and memory.
+
+- **Rules**: `{"permissions": {"allow": ["run_command(npm test)", "edit_file(src/*)"], "deny": ["read_file(.env)"]}}`
+  in `~/.nova-ai/settings.json`, the private project file, or the workspace's
+  `.nova-ai/settings.json` (team, committed) and `.nova-ai/settings.local.json`
+  (personal). Claude-style aliases such as `Bash(npm run *)` and `Edit(src/**)`
+  work too.
+- **Instructions**: `NOVA.md` and `AGENTS.md` in the workspace.
+- **Memory**: a `MEMORY.md` index plus notes, globally and per project,
+  through the `memory_read` and `memory_write` tools (writes need approval).
+- **Skills**: `SKILL.md` files under `.agents/skills`, `.claude/skills` or
+  `.codex/skills`, in the workspace or your home folder.
+- **MCP servers**: `.mcp.json` or `mcpServers` in `.nova-ai/settings.json`.
+
+The complete layout and rule syntax: [docs/NOVA_HOME.md](https://github.com/Datalab-Rotterdam/nova-ai-cli/blob/main/docs/NOVA_HOME.md).
+
+## Models
+
+The model list shows the chat models of your account. On login Nova picks the
+first one with native tool calling; `/model` or Ctrl+P changes it (and
+remembers the choice), `--model` or `NOVA_MODEL` sets it for one run. Nova uses the gateway's function calling and falls back
+to a text protocol for models that don't support it. When the context window
+fills up, older messages are summarized automatically (`/compact` does it by
+hand).
+
+| Environment | |
 |---|---|
-| `NOVA_API_KEY` | Skip stored credentials, use this key |
-| `NOVA_MODEL` | Skip stored default model, use this model id |
-
-A future version will swap this for real OAuth once DataLab Rotterdam ships an OAuth provider for Nova AI — same local server (`src/acp/auth-server.ts`), same lifecycle, just a different page/flow. Credential handling stays isolated in `src/acp/credentials.ts` either way.
-
----
-
-## What it implements
-
-| ACP method | Behavior |
-|---|---|
-| `initialize` | Returns protocol version + the `nova-api-key` agent auth method |
-| `session/new` | Allocates a session id with in-memory history |
-| `session/load` | Restores a previously-persisted session and replays its turns as `*_message_chunk` notifications |
-| `session/list` | Lists stored sessions, optionally filtered by `cwd` |
-| `authenticate` | Runs the local browser auth flow (`src/acp/auth-server.ts`) and resolves once a valid key is stored |
-| `session/prompt` | Streams a `chat.completions.stream()` call, forwarding `agent_message_chunk` updates as text arrives; drives the tool-calling loop below |
-| `session/cancel` | Aborts the in-flight Nova AI request via `AbortController` |
-
-Only `text` and `resource_link` content blocks are read from prompts today — images/audio/embeddings supported by `nova-sdk` aren't wired up yet.
-
-Sessions are persisted to disk (`src/acp/sessions.ts`) so `session/load` can rehydrate history, and a title is auto-derived from the conversation.
-
-### Tool calling
-
-While streaming a response, the agent watches for a fenced tool-call marker in the model's output (`src/acp/tools/marker.ts`). When one appears, it stops streaming text and instead:
-
-1. Reports the pending call via `session/update` (`tool_call` with status `pending`).
-2. Requests permission from the client for any **mutating** tool (`allow_once` / `reject_once`), via `session/request_permission`.
-3. Executes the tool and reports the result/error via a `tool_call_update`.
-4. Feeds the tool result back into the conversation and loops (up to 10 rounds per prompt) until the model produces a plain answer.
-
-Built-in tools (`src/acp/tools/registry.ts`):
-
-| Tool | Mutating | Behavior |
-|---|---|---|
-| `read_file` | No | Reads a file's contents, gated by client `fs.readTextFile` capability |
-| `write_file` | Yes | Writes/overwrites a file, gated by client `fs.writeTextFile` capability — requires permission |
-| `run_command` | Yes | Runs a shell command in the session's `cwd` — requires permission |
-
-Tools are filtered per-session by the client's advertised `clientCapabilities`, so a client without filesystem support never sees `read_file`/`write_file` offered.
-
----
+| `NOVA_API_KEY`, `NOVA_MODEL` | Use this key / model instead of the stored ones |
+| `NOVA_BASE_URL` | Another Nova (OpenAI-compatible) gateway |
+| `NOVA_AI_HOME` | Settings folder (default `~/.nova-ai`) |
+| `NOVA_TOOL_PROTOCOL` | Force `native` or `text` tool calling |
+| `NOVA_NES_MODEL` | Separate model for next-edit suggestions (ACP) |
+| `NOVA_KITTY_KEYBOARD` | `1`/`0`: force the kitty keyboard protocol on or off |
 
 ## Development
 
-```sh
-npm install
-npm test      # tsc --noEmit + node --test on tests/
-npm run build # builds the Svelte setup page, then tsc -> dist/
-```
-
-Releases are automated via `semantic-release` on push to `main` (see `.github/workflows/ci.yml`); commit messages drive version bumps.
-
----
+This package lives in the [nova-ai-cli repository](https://github.com/Datalab-Rotterdam/nova-ai-cli)
+next to the agent package it depends on; see the repository README for
+building and testing.
 
 ## License