@moreai/code 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -1,337 +1,304 @@
-# More AI Code (`moreai`)
+<h1 align="center">More AI Code</h1>
 
-A terminal coding agent that runs on its own. The desktop app is optional: the CLI
-starts a bundled local engine when no More AI app is running.
+<p align="center">
+  <b>An AI coding agent for your terminal.</b><br>
+  Your own model keys, an engine on your machine, and cloud runs when you want them.
+</p>
 
-## Install the preview
+<p align="center">
+  <a href="https://www.npmjs.com/package/@moreai/code"><img alt="npm" src="https://img.shields.io/npm/v/@moreai/code/beta?label=npm%20beta&color=ff7a45"></a>
+  <img alt="Node.js 22+" src="https://img.shields.io/badge/node-%E2%89%A522-339933">
+  <img alt="macOS · Linux · Windows" src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-555">
+  <a href="https://more-ai.net"><img alt="more-ai.net" src="https://img.shields.io/badge/more--ai.net-website-111"></a>
+</p>
 
-Requires Node.js 22 or newer on macOS, Linux or Windows.
+<p align="center">
+  <img alt="More AI Code exploring a repository, editing a file, writing a test, running it and summarising the change" src="https://cdn.jsdelivr.net/npm/@moreai/code@0.1.0-beta.3/media/session.webp" width="860">
+</p>
 
-```sh
-npm install -g @moreai/code@beta
-moreai setup
-cd your-project
-moreai
-```
+More AI Code is an assistant that works in your project from the terminal.
+Describe a task in plain words — "fix the failing test", "add validation to
+the signup form", "explain how billing works" — and it reads the code, edits
+the files, runs the commands and tests, and tells you what it changed. You stay
+in control: anything risky waits for your yes.
 
-The `beta` tag follows preview releases. To check for a new version and update
-the global installation:
+It works with the AI you already have: an API key from more than 30 providers, a
+ChatGPT, GitHub Copilot or Claude subscription, or a model running on your own
+computer. No account and no desktop app are needed.
+
+## Install
 
 ```sh
-moreai update
-moreai update --install
-moreai --version
+npm install -g @moreai/code
 ```
 
-`moreai update` checks the npm release tag and shows the available version;
-`--install` runs the global npm update. You can also update manually with
-`npm install -g @moreai/code@beta`. The CLI checks for updates in the
-interactive session and shows a quiet notice when a new version is available.
-
-If you received a packaged `.tgz` archive instead of installing from npm,
-install it with `npm install -g ./moreai-code-<version>.tgz`, then run the same
-`moreai setup` step. The archive includes the headless engine. Tarball installs
-do not receive updates until you install a newer archive or switch to the npm
-`beta` tag.
-
-`moreai setup` walks through a More AI account and an AI provider:
-
-- **AI provider** gives the agent a model on this computer. Connect an API key,
-  a local model (Ollama, LM Studio) or a supported provider subscription
-  through `moreai auth`. If a key is already in your environment
-  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) the first run offers it at the top
-  of the list, and `moreai auth env` connects every one it finds. A More AI
-  account is not required to use your own provider.
-- **More AI account** is optional and adds what needs a server: cloud
-  sessions that keep working with this computer off (`moreai cloud`), session
-  and settings sync, More AI dictation, and Google services (Gmail, Calendar,
-  Drive) for the agent. Sign in with your email; approve the request on
-  another signed-in device or enter the emailed six-digit code. The account
-  session stays in the local engine, never in your shell history.
-- **External services** give the agent tools from a connector, such as an MCP
-  server. `moreai connectors` lists the catalog whenever you want one.
-
-You can run these steps separately at any time:
+> **Keep the `-g`.** The install box in npm's sidebar shows
+> `npm i @moreai/code`, which only adds the package to the current folder — the
+> `moreai` command appears only after a global install.
 
-```sh
-moreai login            # sign in to More AI
-moreai account          # show the signed-in account and plan
-moreai logout           # sign out; keeps your own provider connections
-moreai auth             # connect or change an AI provider
-moreai auth env         # connect the provider keys found in the environment
-moreai auth status      # list connected providers
-moreai connectors       # choose an external service
-moreai connectors list  # list connected services
-moreai doctor           # check the local engine and setup
-```
+Requires **Node.js 22 or newer** (`node --version`) on macOS, Linux or Windows.
+Check the install with `moreai --version`. On Linux, if npm answers `EACCES`,
+install Node with a version manager such as [nvm](https://github.com/nvm-sh/nvm)
+or [fnm](https://github.com/Schniz/fnm) instead of using `sudo`.
 
-When a provider signs in through the browser and you are on a remote machine
-over SSH, the sign-in page cannot reach back to the terminal on its own. The
-wizard prints the `ssh -L` command that forwards the sign-in port, or you can
-paste an API key instead.
-
-### External services from the terminal
-
-`moreai connectors` (or `/connectors` in a session) is one searchable list:
-what is connected — Google services from your More AI account (Gmail,
-Calendar, Meet, Tasks, Drive) and MCP servers alike, each with its state —
-then the whole catalog by category. Type to search, **Enter** connects (or
-fixes a connection that needs a new sign-in), **Space** turns a connected
-service on or off, **Ctrl+D** disconnects it (press twice). Google services
-belong to your More AI account, so a service connected on the desktop, the web
-or the phone is already on here. Choosing one while signed out explains why
-the account is needed and opens the sign-in right there; once you are in, the
-connection continues on its own. A service whose sign-in is kept with the
-account can also be connected on this computer only, without one. For a script or SSH
-session, use the commands directly:
+## Get started in three steps
+
+### 1. Open your project and connect a model
 
 ```sh
-moreai connectors catalog         # show service names and IDs
-moreai connectors add github      # connect a listed service
-moreai connectors add https://mcp.example.com/mcp  # connect a custom MCP URL
-moreai connectors list            # inspect connection IDs and status
-moreai connectors off ID          # keep a service but take its tools away
-moreai connectors on ID           # turn it back on
-moreai connectors remove ID       # disconnect by the ID shown in the list
+cd your-project
+moreai
 ```
 
-For a service that needs a token, pipe it to `--token-stdin` so the secret does
-not appear in the command arguments or shell history:
+The first launch asks how to reach a model. Pick a provider from the list (type
+to search), then paste an API key, sign in with your subscription, or choose a
+local model from Ollama or LM Studio. Keys stay on your machine.
 
-```sh
-printf '%s\n' "$MCP_TOKEN" | moreai connectors add github --token-stdin
-```
+<p align="center">
+  <img alt="The first launch: a searchable list of AI providers — Anthropic, OpenAI, ChatGPT, Google Gemini, GitHub Copilot, OpenRouter and more" src="https://cdn.jsdelivr.net/npm/@moreai/code@0.1.0-beta.3/media/connect.webp" width="760">
+</p>
+
+Already have `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or another provider key in
+your environment? It is offered at the top of the list.
+
+### 2. Say what you want done
 
-Some services open a browser to finish sign-in. `moreai connectors list` shows
-whether each connection is ready. `moreai auth` remains the command for the
-AI model that answers your questions.
+Type the task as you would tell a colleague and press **Enter**. The line under
+the prompt shows the access mode, the model and your branch.
 
-### Sign in without an interactive terminal
+<p align="center">
+  <img alt="A session in a project folder, with the task typed into the prompt" src="https://cdn.jsdelivr.net/npm/@moreai/code@0.1.0-beta.3/media/start.webp" width="760">
+</p>
 
-Starting sign-in from a script or SSH session requires an email argument:
+### 3. Follow along and approve what matters
+
+The agent shows every step: files it reads, each edit as a diff, commands and
+their output. You choose how much it may do on its own. In `accept-edits`,
+shown here, it edits files freely and stops before every command — allow it
+once, for the session, always, or deny it. In `auto`, the default, it runs
+what it can show is safe and declines the rest.
+
+<p align="center">
+  <img alt="A permission card asking to run npm test, with the choices Allow once, Allow for this session, Always allow and Deny" src="https://cdn.jsdelivr.net/npm/@moreai/code@0.1.0-beta.3/media/approve.webp" width="760">
+</p>
+
+While it works you can keep typing to steer it, **Esc** interrupts, and
+**Shift+Tab** switches the access mode (see *Access modes* below). `/help`
+lists every command.
+
+## What it does
+
+- **Works in your repository.** Reads and searches the code, edits files and
+  shows each change as a diff, runs commands and tests, keeps a checklist of
+  its own plan, and answers in plain language.
+- **Runs on your models.** More than 30 providers: Anthropic, OpenAI, Google
+  Gemini, OpenRouter, DeepSeek, Groq, local models through Ollama or LM Studio,
+  any OpenAI-compatible endpoint, and ChatGPT or GitHub Copilot subscriptions.
+  Keys stay on your machine.
+- **Asks before it acts.** Five access modes, from read-only planning to full
+  autonomy. Commands run in an OS sandbox where one is available, and risky
+  ones are held for you.
+- **Splits big questions across helpers.** Parallel helper agents research
+  different parts of the codebase at once and report back.
+- **Moves work to the cloud.** With a More AI account, a task can keep running
+  on our servers with your laptop closed and come back as a branch or a pull
+  request.
+- **Listens.** `Ctrl+T` dictates into the prompt.
+- **Speaks your language.** The interface is translated into 35 languages.
+
+## Everyday commands
 
 ```sh
-moreai login you@example.com
+moreai            # interactive session in this folder
+moreai setup      # guided setup: model, optional account and services
+moreai auth       # connect or change an AI provider
+moreai auth env   # connect every provider key found in your environment
+moreai doctor     # check that everything is ready
 ```
 
-If it sends an email code, pipe the **latest** six-digit code to the verification
-command. Piping keeps the code out of process arguments and shell history:
+## Access modes
+
+| Mode | What the agent may do |
+| --- | --- |
+| `plan` | Read the code and propose a plan for you to approve; then it builds |
+| `read-only` | Read and answer; never change anything |
+| `accept-edits` | Edit files on its own; ask before running commands |
+| `auto` *(default)* | Work on its own; anything it cannot show to be safe is declined |
+| `full` | Run everything except a small set of destructive commands |
+
+Pick one with **Shift+Tab** in a session or `--mode <mode>` on the command line.
+
+## Helper agents
+
+<p align="center">
+  <img alt="Three parallel helper agents researching webhooks, each with its result, then the combined answer" src="https://cdn.jsdelivr.net/npm/@moreai/code@0.1.0-beta.3/media/helpers.webp" width="860">
+</p>
+
+For broad questions the agent can start several **helper agents** in
+parallel. Each gets its own line — what it was asked, what it is doing now,
+and when it finishes, its tool count, tokens and time with the first line of
+its report. The run's token total shows how much of it went to helpers.
+Helpers only read; the main agent makes the changes.
+
+Start a task with `@explore`, `@scout` or `@general` to hand it to a helper
+directly:
 
 ```sh
-printf '%s\n' "$MOREAI_EMAIL_CODE" | moreai login you@example.com --code-stdin
+moreai "@explore how does the billing webhook verify signatures?"
 ```
 
-If it returns a push approval challenge, the command prints its ID. Approve the
-matching confirmation code on another device, then run:
+## Cloud sessions
+
+With a More AI account (`moreai login`), a task can run in the cloud instead
+of on this computer. You can follow it here, or answer it from the web app or
+your phone.
 
 ```sh
-moreai login --challenge <id> --wait
+moreai cloud run "add tests for the parser"   # move this folder into a cloud session
+moreai --cloud "add tests for the parser"     # the same
+moreai cloud                                  # your cloud sessions and their state
+moreai cloud open <id>                        # the conversation and its link
+moreai cloud finish <id>                      # bring the work back again
 ```
 
-To use an email code instead, run `moreai login --challenge <id> --fallback`,
-then pipe the code as above. No account token is printed by these commands.
+`moreai cloud run` uploads the folder as it is — your branch, commits and
+uncommitted changes, never files that look like secrets or are over 25 MB —
+and follows the task in the terminal. **Ctrl+C** stops following; the task
+keeps running. When it finishes, the work comes back as a **new branch**
+`more-ai/<topic>-<id>`, and your own branch and edits are never touched. In a
+GitHub or GitLab repository it is pushed and a pull request is opened with
+your own `gh` / `glab` login; `--finish push|branch|folder` chooses otherwise.
+Inside a session, `/cloud` does the same.
 
-## Work in a project
+## Scripts and pipes
 
 ```sh
-moreai                       # interactive session in the current folder
-moreai "fix the failing test" # open a session and run a task
-moreai -c                    # continue the latest session for this folder
-moreai sessions              # list this folder's sessions
-moreai -p "add types"       # run once, print the result, exit
+moreai -p "summarise the open TODOs"            # run once, print the answer, exit
 git diff | moreai -p "review this diff"
-moreai -p --json "…"         # one JSON event per line
+moreai -p --json "add types to utils.ts"        # one JSON event per line
+moreai -c                                       # continue the newest session here
+moreai sessions                                 # this folder's sessions
 ```
 
 | Option | Meaning |
 | --- | --- |
-| `-p, --print` | Run once without the interactive UI |
-| `--json` | With `-p`, output machine-readable event lines |
+| `-p, --print` | Run once without the interactive interface |
+| `--json` | With `-p`: machine-readable events, one per line |
 | `-c, --continue` | Continue this folder's newest session |
 | `--session <id>` | Resume a specific session |
-| `-m, --model <id>` | Choose a model for this run |
-| `--provider <id>` | Disambiguate the provider for a model |
-| `--mode <mode>` | `plan`, `read-only`, `accept-edits`, `auto`, or `full` |
-| `-C, --cwd <dir>` | Set the working folder |
-| `--cloud` | Run the task in a cloud session instead (see below) |
+| `-m, --model <id>` | Choose the model for this run |
+| `--provider <id>` | Say which provider serves `--model` |
+| `--mode <mode>` | Access mode (see above) |
+| `-C, --cwd <dir>` | Work in another folder |
+| `--cloud` | Run the task in a cloud session |
 | `--finish <how>` | With `--cloud`: `pr`, `push`, `branch` or `folder` |
-| `--detach` | With `--cloud`: start it and return without following |
+| `--detach` | With `--cloud`: start it and return immediately |
+| `--lang <id>` | Interface language for this run |
 
-In the session, press **Enter** to send, **Ctrl+J** (or a trailing `\`) for a
-newline, **Esc** to interrupt, and **Shift+Tab** to change access mode. Use
-`/help` to see the available commands. You can type while the agent is working
-to steer its run. The status line shows the model, how much of its context
-window is left (yellow under 25 %, red under 10 %), the branch and the access
-mode.
+## In the session
 
-While the agent works, what it reads and searches folds into one
-**Explored** line, edits show as diffs, and its checklist stays above the input.
+| Key | Action |
+| --- | --- |
+| Enter | Send (or steer the running task) |
+| Ctrl+J, or `\` at line end | New line |
+| Esc | Interrupt the run; twice clears the draft |
+| Shift+Tab | Change the access mode |
+| Ctrl+T | Dictate (Enter or Ctrl+T to insert, Esc to discard) |
+| ↑ ↓ | Move between lines, then through your history |
+| Ctrl+O | Expand a large paste back into editable text |
+| Ctrl+D, or Ctrl+C twice | Leave; the command to resume is printed |
 
-### Helper agents
+Useful commands: `/model` (pick a model; **Ctrl+F** pins it), `/sessions`,
+`/connectors` (Gmail, Calendar, Drive, GitHub and other services for the
+agent), `/cloud`, `/language`, `/login`, `/status`, `/help`.
 
-The agent can split broad research across parallel **helper agents**. Each one
-gets its own line under the step that started it — what it was asked, what it
-is doing now, and when it finishes, its tool count, tokens and time with the
-first line of its report. The run's token total says how much of it the helpers
-spent. Helpers only read; the main agent makes the changes.
+## Voice input
 
-Start a task with `@explore`, `@scout` or `@general` to hand it to that helper
-directly, even when automatic delegation is off:
+**Ctrl+T** (or `/voice`) records from the microphone and puts the text at the
+cursor without sending it. Transcription uses More AI dictation once you sign
+in, your own transcription service, or an on-device model set up in the More
+AI desktop app. Recording uses the ffmpeg that comes with the desktop app, or
+`ffmpeg`, `sox`, `parecord` or `arecord` from your `PATH`.
 
-```sh
-moreai "@explore how does the billing webhook verify signatures?"
-```
+## Account and services
 
-### Voice input
-
-**Ctrl+T** (or `/voice`) records from the microphone: a red dot, a timer and a
-level meter show it is listening. **Enter** or **Ctrl+T** stops and puts the
-text at the cursor — it is not sent, so you can read it first — and **Esc**
-throws the recording away. A recording stops by itself after two minutes.
-
-Transcription uses whatever the More AI app's dictation is set to: More AI
-dictation once you `/login`, your own transcription service, or an on-device
-model (Settings → Dictation in the app). The audio is recorded by this terminal,
-so the first time the system asks whether your terminal app may use the
-microphone. If a transcription fails, the recording is kept: **Ctrl+T** tries
-again.
-
-To record, `moreai` uses the ffmpeg that comes with the More AI app, or one of
-`ffmpeg`, `sox`, `parecord`, `arecord` on your PATH. `MOREAI_VOICE_RECORDER`
-names any other command that prints raw 16-bit 16 kHz mono audio on stdout
-(arguments separated by spaces).
-
-### Leaving a session
-
-**Ctrl+D** on an empty draft, **Ctrl+C** twice or `/quit` ends the session and
-hands the terminal back: the screen is cleared and one line remains with the
-command that resumes the session. Only the visible screen is cleared — what you
-ran before `moreai` stays in the scrollback — and the terminal gets its own
-title back. `MOREAI_KEEP_SCREEN=1` leaves the session on screen instead. A
-crash never clears the screen, so the error stays readable.
-
-### Choosing a model
-
-`/model` (or `/models`) opens the model picker: the current model, the models
-you pinned (shared with the desktop app's picker), your recent picks, then every
-connected provider — a large catalog such as OpenRouter grouped by vendor, with
-the context window and price where the provider reports them.
-
-- **Type** to search model names, providers and vendors (`sonnet`,
-  `or claude` for OpenRouter's Claude models, `anthropic`).
-- **↑ ↓** move, **PgUp PgDn** page, **← →** switch the provider tab.
-- **Enter** uses the model for this session and remembers it as your latest
-  pick, so a new session — here or in the desktop app — starts on it.
-- **Ctrl+F** pins or unpins a model; **Ctrl+A** connects another provider;
-  **Esc** clears the search, then closes.
-
-`/model <text>` switches immediately when the text names exactly one model
-(`/model glm-4.5`, `/model openrouter/anthropic/claude-sonnet-4.6`); anything
-else opens the picker with that search.
-
-### Editing and pasting
-
-The input box is a multi-line editor: **↑ ↓** move between lines (and reach your
-history from the first or last line of an empty or recalled draft),
-**Alt+← →** move by word, **Ctrl+A / Ctrl+E** jump to the line start or end,
-**Ctrl+U / Ctrl+K / Ctrl+W** delete. A long draft scrolls inside the box.
-
-A large paste (more than 8 lines or 800 characters) becomes a single
-`[Pasted text #1 · 200 lines]` item: **Backspace** removes it whole,
-**Ctrl+O** turns it back into editable text, and the agent receives the full
-text when you send. **Ctrl+C** clears the draft and keeps it in history; **Esc**
-twice clears it too.
-
-### Language
-
-The terminal agent speaks the same 35 languages as the desktop app and picks
-one without asking: `--lang` or `MOREAI_LANG` first, then your `/language`
-choice, then the desktop app's language, then the terminal's locale
-(`LC_ALL` / `LANG`) and finally the system language. `/language` lists them all
-(type to search; **Automatic** follows the app and the system), and
-`/language de` switches straight away. Slash commands, flags and key names stay
-in English everywhere, and `--json` output is always English.
+A More AI account is optional. It adds cloud sessions, sync of your sessions to
+the web and phone apps, More AI dictation, and Google services (Gmail,
+Calendar, Drive) for the agent.
 
 ```sh
-moreai --lang ja        # this run only
-MOREAI_LANG=ru moreai   # the same, from the environment
+moreai login                 # sign in with your email (a code or an approval on another device)
+moreai account               # the signed-in account and plan
+moreai connectors            # connect a service; `moreai connectors list` shows them
+moreai logout                # sign out; your own provider keys stay
 ```
 
-## Cloud sessions
+From a script or an SSH session: `moreai login you@example.com`, then pipe the
+emailed code to `moreai login you@example.com --code-stdin`. When a provider
+signs in through the browser on a remote machine, the CLI prints the
+`ssh -L` command that forwards the sign-in back to your terminal.
+
+## How it runs
+
+`moreai` starts a small background engine on your machine the first time it
+needs one; later sessions, the More AI desktop app and the VS Code extension
+share it, so a session started in one place continues in another. If the
+desktop app is running with **Settings → Agent tools → External clients** on,
+the CLI uses the app's engine instead.
 
-With a More AI account, a task can run in the cloud instead of on this
-computer — it keeps going when you close the laptop, and you can follow it or
-answer it from the web app or your phone.
+Provider keys are encrypted with a key kept in the system keyring (macOS
+Keychain, Windows Credential Manager, or the Secret Service on Linux). A Linux
+server without a keyring service stores them in a file only your user can read
+(`~/.config/More AI/secrets.json`), the way most command-line tools keep tokens.
+
+## Privacy
+
+Your code and keys stay on your machine unless you move a task to the cloud.
+More AI collects usage analytics to find bugs; with AI traces on (the default)
+the content of runs is included so failed runs can be debugged. API keys are
+never sent. The first interactive session asks once; change it any time:
 
 ```sh
-moreai cloud run "add tests for the parser"   # move this folder into a cloud session
-moreai --cloud "add tests for the parser"     # the same
-moreai cloud                                  # your cloud sessions and their state
-moreai cloud open <id>                        # the conversation and its link
-moreai cloud finish <id>                      # bring the work back again
-moreai cloud cancel <id>                      # stop the running task
-moreai cloud models                           # models a cloud run can use
+moreai analytics off       # nothing is sent
+moreai analytics usage     # usage only, no conversation content
+moreai analytics on        # usage and AI traces
 ```
 
-`moreai cloud run` packages the folder as it is — your branch, commits and
-uncommitted changes, never files that look like secrets or are larger than
-25 MB — uploads it and starts the task, then follows it in the terminal: the
-current step, the answer when it is done. **Ctrl+C** stops following; the task
-keeps running (`--detach` returns straight away).
-
-When the task finishes, the work comes back on its own as a **new branch**
-`more-ai/<topic>-<id>`; your own branch and uncommitted edits are never
-touched. In a repository on GitHub or GitLab it is then pushed and a pull
-request is opened with your own `gh` / `glab` login; `--finish` chooses
-otherwise: `push`, `branch` (local only) or `folder` (copy the changed files
-into this folder, keeping your edits). The cloud runs on your plan's models,
-or on your own provider key if you uploaded it in the More AI app
-(Settings → Privacy); `-m` picks one of `moreai cloud models`.
-
-Inside a session, `/cloud` lists the cloud sessions (Enter shows one) and
-`/cloud <task>` moves the task there.
-
-## Engine and data
-
-`moreai doctor` and `/status` name the backend this build talks to. Installed
-packages use production (`api.more-ai.net`); only `MOREAI_ENV=dev`, at build or
-run time, points the CLI and its engine at the test tier, and the session's
-welcome screen then shows a `DEV` badge.
-
-
-Without the desktop app, `moreai` launches a bundled headless engine on this
-machine. Provider credentials are encrypted with a key kept in the operating
-system's keyring (macOS Keychain, Windows Credential Manager, or the Secret
-Service on Linux — GNOME Keyring or KWallet). A Linux server with no keyring
-service stores them unencrypted in a file only your user can read
-(`~/.config/More AI/secrets.json`), the way most command-line tools keep
-tokens. The CLI and VS Code can connect to the same running engine; sessions
-and settings persist across CLI restarts.
-
-If the desktop app is running with **External clients** enabled, the CLI attaches
-to its engine, so sessions appear on both surfaces. If the app is running with
-External clients disabled, enable it in **Settings → Agent tools**, or close the
-app so the CLI can start its own engine. `moreai doctor` reports this condition.
-
-## Usage analytics
-
-More AI collects usage analytics to find bugs and see which features work:
-commands you use, errors, and how agent runs go. With AI traces on (the
-default), the content of runs is included too, so failed runs can be debugged.
-API keys are never sent. The first interactive session asks once; you can
-change it at any time:
+`DO_NOT_TRACK=1` or `MOREAI_TELEMETRY=0` turns analytics off for any process
+that sees it.
+
+## Update and uninstall
 
 ```sh
-moreai analytics           # show the current setting
-moreai analytics usage     # analytics without conversation content
-moreai analytics off       # turn analytics off
-moreai analytics on        # analytics and AI traces
+moreai update              # is there a newer version?
+moreai update --install    # install it
+npm uninstall -g @moreai/code
 ```
 
-Inside a session, `/analytics` opens the same choice. `DO_NOT_TRACK=1` or
-`MOREAI_TELEMETRY=0` turns analytics off for any process that sees it. The
-setting belongs to this machine's engine, so it is shared with the More AI
-desktop app (Settings → Privacy) when both are installed.
+The background engine notices an update or uninstall and stops by itself once
+nothing is using it, so the next session runs the new version.
+
+Version 0.1.0-beta.1 cannot see newer versions: update it once with
+`npm install -g @moreai/code@latest`. Its engine predates the self-stop and
+keeps running until you restart the computer or run
+`pkill -f @moreai/code/dist/daemon.mjs` (macOS, Linux).
+
+## Troubleshooting
+
+- **`moreai doctor`** checks the engine, the connection and your setup, and says
+  what to fix.
+- **"No AI provider is connected"**: run `moreai auth`, or `moreai auth env` if
+  your key is in an environment variable.
+- **The desktop app is running but the CLI cannot attach**: turn on
+  **Settings → Agent tools → External clients** in the app, or close the app.
+- **Commands are held on a Linux server**: in `auto` the agent runs commands
+  on its own only inside a sandbox (bubblewrap on Linux). Without one, switch to
+  `accept-edits` (**Shift+Tab**) to approve each command, or use `--mode full`
+  in an environment you trust.
+
+Questions and bug reports: [support@more-ai.net](mailto:support@more-ai.net).
+
+## License
 
-© 2026 More AI. All rights reserved. Proprietary software — see `LICENSE`;
-the open-source components it bundles are listed in `THIRD_PARTY_LICENSES.txt`.
+© 2026 More AI. All rights reserved. Proprietary software — see `LICENSE`.
+The open-source components it bundles are listed in `THIRD_PARTY_LICENSES.txt`.