@aiiware/aii 0.19.0 → 0.19.3

package/README.md

@@ -9,7 +9,7 @@ An autonomous AI assistant that lives in your terminal. Ask it anything — it r
 </p>
 
 <p align="center">
-  <strong>npm:</strong> <code>@aiiware/aii</code> · <strong>Version:</strong> 0.18.0 · <strong>Node.js:</strong> >= 20
+  <strong>npm:</strong> <code>@aiiware/aii</code> · <strong>Version:</strong> 0.19.3 · <strong>Node.js:</strong> >= 20
 </p>
 
 ---
@@ -39,19 +39,9 @@ npm install -g @aiiware/aii
 aii -D hi there!
 ```
 
-<p align="center">
-  <a href="https://youtu.be/Y98DqkgdWdQ">
-    <img src="https://img.youtube.com/vi/Y98DqkgdWdQ/maxresdefault.jpg" width="600" alt="Aii CLI npm Install Demo" />
-  </a>
-  <br/>
-  <em>npm install demo</em>
-</p>
-
-On first run, Aii auto-launches a setup wizard to configure your AI provider, model, and API key. After setup completes, your command executes automatically.
-
-Already know your provider? You can also configure directly: `aii config apikey <provider> <key>`
+([npm install demo](https://youtu.be/Y98DqkgdWdQ))
 
-> **Requirements:** Node.js 18+ and Docker (both auto-installed if missing)
+On first run, Aii auto-launches a setup wizard to configure your AI provider, model, and API key. After setup completes, your command executes automatically. Already know your provider? Configure directly: `aii config apikey <provider> <key>`
 
 ---
 
@@ -77,22 +67,7 @@ echo "Hello world" | aii translate to Japanese
 aii run git commit -y
 ```
 
-It reads your staged changes, writes a Conventional Commits message, and commits — one command.
-
-Control the attribution footer (also on `aii run git pr`):
-
-```bash
-aii run git commit -y --no-signature                  # this run: no footer
-aii run git commit -y --signature "Reviewed-by: TT"   # this run: your own footer
-```
-
-```yaml
-# ~/.aii/config.yaml — persistent preference
-git:
-  commit_signature: none    # default | none | any literal footer text
-```
-
-Precedence: `--no-signature` > `--signature "<text>"` > config > default. The footer is appended by the CLI after generation (never model-written), so it is byte-identical on every run. The interactive `/commit` and `/review` skills are separate surfaces and keep their own footer.
+It reads your staged changes, writes a Conventional Commits message, and commits — one command. Control the attribution footer (also on `aii run git pr`) with `--no-signature` / `--signature "<text>"`, or persist it via `git.commit_signature` in [config](#configuration).
 
 ### Start an interactive session
 
@@ -107,10 +82,9 @@ You get a rich terminal UI with streaming responses, syntax highlighting, diff p
 ```bash
 aii --model ollama/llama3.1:8b write a bash one-liner to find large files
 aii --model deepseek/deepseek-chat explain this regex
-aii --model openai/gpt-4.1 refactor this function
 ```
 
-Or during a session: `/model anthropic:claude-sonnet-4`
+Or during a session: `/model deepseek:deepseek-chat`
 
 ### Run it autonomously
 
@@ -118,7 +92,7 @@ Or during a session: `/model anthropic:claude-sonnet-4`
 aii loop "fix all failing tests" --verify "npm test" --budget 0.50
 ```
 
-The agent loops with fresh context each iteration, stopping when your verification command passes, the budget is hit, or you press Esc. Steer it mid-run with `/pause`, `/resume`, `/stop`, `/stats`, and `/note`. Feedback appears in a dedicated toast zone — not mixed into agent output.
+The agent loops until your verification command passes or a limit is hit — see [Autonomous Loops](#autonomous-loops). Or give an interactive session a standing objective with [`/goal`](#session-goals).
 
 ---
 
@@ -128,12 +102,12 @@ The agent loops with fresh context each iteration, stopping when your verificati
 
 | Provider | What You Get |
 |----------|-------------|
-| **Anthropic** | Claude Sonnet 4, Opus 4, Haiku 4.5 |
-| **OpenAI** | GPT-5.2, GPT-4o, GPT-4.1 |
-| **Google** | Gemini 3-pro, 2.5-pro, 2.5-flash |
+| **Anthropic** | Claude (Sonnet · Opus · Haiku) |
+| **OpenAI** | GPT + o-series |
+| **Google** | Gemini (pro · flash) |
 | **DeepSeek** | deepseek-chat, deepseek-reasoner |
-| **Moonshot** | Kimi K2 Thinking, Vision |
-| **Z.ai** | GLM-4.7, GLM-4.6V, GLM-4.5 |
+| **Moonshot** | Kimi |
+| **Z.ai** | GLM family |
 | **Ollama** | Any local model — free, private, offline |
 | **OpenRouter** | 300+ models through one API key |
 
@@ -143,22 +117,18 @@ The agent loops with fresh context each iteration, stopping when your verificati
 
 ## Tools
 
-The agent autonomously picks from **10 built-in tools**:
+The agent autonomously picks from its built-in tools:
 
 | Tool | What It Does |
 |------|-------------|
-| **Read** | Read any file |
-| **Write** | Create or overwrite files |
-| **Edit** | Surgical find-and-replace edits |
-| **Glob** | Find files by pattern |
-| **Grep** | Search file contents (regex) |
-| **Bash** | Run shell commands |
-| **WebSearch** | Search the web |
-| **WebFetch** | Fetch and parse web pages |
+| **Read / Write / Edit** | Read, create, and surgically edit files |
+| **Glob / Grep** | Find files by pattern, search contents (regex) |
+| **Bash** | Run shell commands (plus background jobs) |
+| **WebSearch / WebFetch** | Search the web, fetch and parse pages |
 | **Task** | Delegate to parallel subagents |
 | **Skill** | Invoke extensible skill packages |
 
-You control what the agent can do. By default, it asks before running commands or writing files. Use `--auto` to skip confirmations.
+…plus task-planning and interaction helpers. You control what the agent can do: by default it asks before running commands or writing files. Use `--auto` to skip confirmations.
 
 ---
 
@@ -169,10 +139,7 @@ During interactive sessions, type `/` to see all commands. Highlights:
 | Command | What It Does |
 |---------|-------------|
 | `/help` | Show all commands |
-| `/model [name]` | View or switch model |
-| `/provider [name]` | View or switch provider |
-| `/soul [name]` | View or switch soul (thinker, doer, coder) |
-| `/theme [name]` | View or switch color theme |
+| `/model [name]` / `/provider [name]` | View or switch model / provider |
 | `/auto` | Toggle auto-approve mode |
 | `/plan` | Toggle plan mode (read-only) |
 | `/goal [objective]` | Set a session goal the agent works toward autonomously (see [Session Goals](#session-goals)) |
@@ -183,27 +150,17 @@ During interactive sessions, type `/` to see all commands. Highlights:
 | `/aii [question]` | Ask about Aii features, commands, and usage |
 | `/commit` | AI-powered git commit |
 | `/review-pr` | AI-powered PR review |
-| `/worktree create` | Isolated workspace for experiments |
-| `/mcp install` | Add MCP server from catalog |
-| `/mcp reconnect` | Reconnect failed MCP servers |
-| `/persona [action]` | Manage workspace personas (install, use, list, status) |
-| `/skills` | List and manage skill packages |
-| `/sessions` | Browse and resume past sessions |
 | `/exit` | End session with summary |
 
 ### Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `Enter` | Submit input |
 | `Esc` | Cancel current request |
-| `Ctrl+C` | Exit immediately |
 | `Ctrl+D` | Graceful exit with session summary |
 | `Ctrl+L` | Clear conversation |
-| `Ctrl+O` | Peek full tool output (full-screen) · toggle subagent tree — up/down to navigate, `Ctrl+O` again to close |
+| `Ctrl+O` | Peek full tool output · toggle subagent tree |
 | `Ctrl+U` | Clear type-ahead queue / input line |
-| `Up/Down` | Navigate input history |
-| `Tab` | Autocomplete commands |
 
 ---
 
@@ -211,14 +168,7 @@ During interactive sessions, type `/` to see all commands. Highlights:
 
 ### Subagents
 
-The agent delegates complex tasks to specialized subagents running in parallel:
-
-| Agent | Purpose | Tools |
-|-------|---------|-------|
-| **Explore** | Fast codebase search and analysis | Read-only |
-| **Plan** | Architecture and implementation design | Read-only |
-| **Review** | Code quality analysis | Read-only |
-| **Code** | Full implementation | All tools |
+The agent delegates complex work to specialized read-only subagents running in parallel — **explore**, **plan**, **review**, **code-reviewer**, **code-architect**, **researcher** — keeping the main context clean while they fan out.
 
 Define custom agents in `.aii/agents/<name>.md` with YAML frontmatter for custom system prompts, model tiers, and tool access.
 
@@ -248,11 +198,10 @@ Work on multiple features in parallel without stashing:
 ```bash
 aii worktree create auth-refactor    # Create isolated workspace + branch
 aii worktree list                    # See all worktrees
-aii worktree merge auth-refactor     # Merge back
 aii worktree clean                   # Remove all clean worktrees
 ```
 
-Or use `/worktree` slash commands during a session.
+During a session, `/worktree` adds `merge`, `diff`, and `commit`: `/worktree merge auth-refactor` merges back.
 
 ### Autonomous Loops
 
@@ -270,24 +219,15 @@ aii loop --budget 1.00 --duration 8h "refactor the auth module"
 
 | Command | What It Does |
 |---------|-------------|
-| `/pause [duration]` | Pause after the current tool call (e.g., `/pause 5m`, `/pause 2h`) |
-| `/resume` | Resume a paused loop |
-| `/stop` | Finish current turn, then exit cleanly |
+| `/pause [duration]` | Pause after the current tool call (e.g., `/pause 5m`); timed pauses auto-resume |
+| `/resume` / `/stop` | Resume a paused loop / finish the current turn and exit cleanly |
 | `/stats` | Live view of tokens, cost, iterations, elapsed time |
-| `/note <text>` | Inject a note immediately — the agent sees it at the next tool call boundary |
-| Plain text + Enter | Queue guidance — consumed one per iteration with visual feedback |
-
-Pause takes effect between tool calls — the agent finishes what it's doing, then waits. Timed pauses auto-resume after the duration. The status bar shows pause state with a countdown timer.
-
-**`/note` vs plain text** — `/note` delivers your message immediately within the current turn, intercepting the next tool call so the agent can pivot without waiting. Plain text queues guidance for the next iteration — the agent sees it when the new iteration starts. If the agent has no more tool calls left, `/note` falls back to the next iteration — your note is never lost.
+| `/note <text>` | Inject guidance immediately — seen at the next tool call (also works in normal sessions) |
+| Plain text + Enter | Queue guidance for the next iteration |
 
-`/note` also works in **Normal mode** (interactive sessions) — type it while the agent is processing to steer it mid-turn.
+A canceled or exhausted loop is resumable: `/loop list` shows saved loops, `/loop resume <id>` continues one with its remaining limits. The status bar tracks iterations, tokens, cost, and pause state in real time.
 
-> **Migration note:** `/now` still works as an alias in v0.13.10 but will be removed in a future version. Use `/note` instead — same behavior, clearer name.
-
-The status bar updates in real time with iteration count, token usage, estimated cost, and tool calls — you always know what the loop is doing and what it's costing.
-
-### Session Goals (`/goal`)
+### Session Goals
 
 Give the interactive session a **persistent objective it keeps working toward until evidence says it's done** — no more typing "keep going" after every turn:
 
@@ -296,23 +236,21 @@ Give the interactive session a **persistent objective it keeps working toward un
       without changing public API behavior. --budget 2.00
 ```
 
-While a goal is **active**, the agent sees the objective every turn; when a turn ends and you're not typing, Aii **auto-continues** — checking the evidence first, then either keeps working, declares `GOAL COMPLETE — evidence: …`, or declares `GOAL BLOCKED — <what it needs>`. Completion is evidence-based and shown verbatim; the lifecycle stays yours:
+While a goal is **active**, the agent sees the objective every turn and auto-continues between turns — working, then declaring `GOAL COMPLETE — evidence: …` or `GOAL BLOCKED — <what it needs>`. The lifecycle stays yours:
 
 | Command | What It Does |
 |---------|-------------|
-| `/goal <objective>` | Set the goal (`--budget <usd>`, `--auto-turns <n>` — `0` = unlimited; `--max-time 2h`, `--max-tokens 5M`; `--verify "cmd"`; `--auto` = no approval prompts) |
-| `/goal` | Status view — objective, status, verify, armed limits, time/tokens used, contextual next commands |
-| `/goal draft <plain description>` | The model proposes a strong goal contract (outcome · verification · constraints); you edit + submit it |
-| `/goal edit <text and/or flags>` | Revise in place (`/goal edit --budget 5` raises a limit without retyping) |
+| `/goal <objective>` | Set the goal — flags: `--verify "cmd"` (repeatable), `--budget`, `--auto-turns` (`0` = unlimited), `--max-time`, `--max-tokens`, `--no-proof`, `--auto` |
+| `/goal` | Status view — objective, status, verify, limits, usage |
+| `/goal draft <description>` | The model proposes a strong goal contract; you edit + submit |
+| `/goal edit <text and/or flags>` | Revise in place |
 | `/goal pause` / `resume` / `clear` | Suspend / re-arm / remove |
 
-**Verified completion** — arm `--verify "npm test"` and a `GOAL COMPLETE` claim only counts when that command exits 0: failures keep the goal active and feed the output back to the agent, so "done" means *provably* done. **Cloud-safe limits** — `--max-time` and `--max-tokens` work everywhere (including cloud mode, where `--budget` is unavailable by design).
-
-**Unattended runs**: in Normal mode, approval prompts pause the goal (it never escalates its own authority) — add `--auto` at set time (or type `/auto`) to auto-approve mutating tools for the session and let it run hands-off.
+**Verified completion** — with `--verify` armed, `GOAL COMPLETE` only counts when every command exits 0; failures keep the goal active and feed back to the agent, so "done" means *provably* done. Even without `--verify`, a bare completion isn't taken at face value: the agent gets one nudge to show proof, self-contradicting evidence is rejected, and an unlimited (`--auto-turns 0`) goal **never ends on an unverified claim** (opt out with `--no-proof` or `goal.proof_expected: false` in config).
 
-Guardrails by default: auto-continuation caps at **10 turns** per arming (raise with `--auto-turns`, or `--auto-turns 0` for the run-until-done mode — loudly warned without a budget), budgets stop between turns with an honest summary (never claimed as "done"), a continuation that stops making tool calls pauses visibly, typing always wins the turn, Esc pauses the goal, and the `◎ Goal` status-bar segment keeps the state in view the whole time. Goals are session-scoped and survive restarts via `aii agent --continue` (same project only).
+Guardrails: auto-continuation caps at **10 turns** by default, limit stops hand off with measured progress/remaining/next, typing always wins the turn, Esc pauses, and the `◎ Goal` status-bar segment keeps the state in view. Goals survive restarts via `aii agent --continue`.
 
-`/goal` vs `/loop`: a loop grinds a fixed prompt with fresh context each iteration; a goal keeps one **conversation** converging on an outcome — the evidence trail stays in context. Starting a loop auto-pauses an active goal.
+`/goal` vs `/loop`: a loop grinds a fixed prompt with fresh context each iteration; a goal keeps one **conversation** converging on an outcome. Starting a loop auto-pauses an active goal.
 
 ### Telegram Integration
 
@@ -321,25 +259,13 @@ Run the full agent from Telegram:
 ```bash
 aii telegram pair mybot <bot-token>  # Pair with @BotFather token
 aii telegram start mybot             # Start listening
-aii telegram list                    # Manage bots
 ```
 
-Responses stream live — you see the agent's reply building in real time, just like in the terminal.
-
-Start a conversation in Telegram, continue it from the CLI — or vice versa.
+Responses stream live, and conversations continue across channels — start in Telegram, pick up from the CLI, or vice versa.
 
 ### Soul System
 
-Each agent has a personality — called a **soul** — that shapes how it communicates. Built on [SoulSpec v0.4](https://soulspec.org).
-
-```bash
-aii soul help                     # See available souls
-aii soul switch doer              # Switch personality
-```
-
-Or during a session: `/soul doer`
-
-**Built-in souls:**
+Each agent has a personality — called a **soul** — that shapes how it communicates. Built on [SoulSpec v0.4](https://soulspec.org). Switch with `aii soul switch doer` or `/soul doer` in a session.
 
 | Soul | Display Name | Style |
 |------|-------------|-------|
@@ -347,40 +273,20 @@ Or during a session: `/soul doer`
 | **doer** | Aii Doer 🪼 | Direct and efficient — leads with the answer, every sentence earns its place |
 | **coder** | Aii Coder 🪼 | Pair-programming partner — reads your codebase, references specific lines |
 
-Your preference persists across sessions and channels.
-
-**Custom souls:** Create your own in `.aii/soul/` with `SOUL.md`, `STYLE.md`, `IDENTITY.md`, and an optional `soul.json` manifest. Custom souls introduce themselves as "{Name}, powered by Aii 🪼".
+Your preference persists across sessions and channels. Custom souls: drop a soul directory (`SOUL.md`, `STYLE.md`, `IDENTITY.md`) in `.aii/soul/`.
 
 ### Personas
 
 Bundle soul, skills, hooks, instructions, and theme into a single installable package — one command to load a complete AI engineering identity.
 
 ```bash
-# Install from GitHub
-aii persona install github:aiiware/aii-personas/aiiware-full-stack-engineer
-
-# Install from GitLab
-aii persona install github:aiiware/aii-personas/aiiware-full-stack-engineer
-
-# Activate it
-aii persona use aiiware/full-stack-engineer
-
-# Switch roles instantly
-aii persona use aiiware/code-reviewer
-aii persona use aiiware/mentor
-
-# Check what's active
-aii persona status
-
-# Deactivate
-aii persona use --none
+aii persona install github:aiiware/aii-personas/aiiware-full-stack-engineer   # or gitlab:
+aii persona use aiiware/full-stack-engineer     # activate (switch roles anytime)
+aii persona status                              # check what's active
+aii persona use --none                          # deactivate
 ```
 
-**Official personas:** [github.com/aiiware/aii-personas](https://github.com/aiiware/aii-personas)
-
-Or during a session: `/persona use aiiware/full-stack-engineer`, `/persona list`, `/persona status`
-
-Create your own — just a directory with a `persona.json` manifest and skill/soul files. See the [personas repo](https://github.com/aiiware/aii-personas) for examples.
+**Official personas:** [github.com/aiiware/aii-personas](https://github.com/aiiware/aii-personas) — or create your own: a directory with a `persona.json` manifest and skill/soul files. In-session: `/persona use`, `/persona list`, `/persona status`.
 
 ### Theme System
 
@@ -401,12 +307,9 @@ Extensible instruction packages you can install and invoke:
 /commit                                        # Built-in: AI git commit
 /review-pr                                     # Built-in: PR review
 /explain this function                         # Built-in: code explainer
-/<custom-skill> [args]                         # Any user-invocable skill
 ```
 
-Install accepts GitHub URLs in any format — repo paths, blob URLs, and bare repo URLs all work.
-
-Create skills in `.aii/skills/<name>/SKILL.md` with YAML frontmatter.
+Install accepts GitHub URLs in any format — repo paths, blob URLs, and bare repo URLs all work. Create skills in `.aii/skills/<name>/SKILL.md` with YAML frontmatter.
 
 ### Project Instructions (AGENTS.md)
 
@@ -423,7 +326,7 @@ Also discovers `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md
 
 Run custom scripts when the agent takes actions. Configure in `.aii/hooks.json`:
 
-**Events:** `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`, `SubagentStop`
+**Events:** `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`, `SubagentStop`, `TaskCompleted`
 
 ```bash
 /hooks                  # View configured hooks
@@ -438,11 +341,9 @@ Extend the agent with Model Context Protocol servers:
 aii mcp catalog                    # Browse available servers
 aii mcp install github             # One-command install
 aii mcp add my-server npx my-mcp   # Add custom server
-aii mcp list-tools github          # Discover tools
-aii mcp test github                # Connectivity test
 ```
 
-MCP servers connect in the background during session start — no waiting on first use. If a server drops, use `/mcp reconnect <server>` or `/mcp reconnect all` to restore it without restarting your session.
+MCP servers connect in the background during session start. If a server drops, `/mcp reconnect <server>` restores it without restarting your session.
 
 ### Server Sessions
 
@@ -451,7 +352,6 @@ Conversations persist across restarts and channels:
 ```bash
 aii sessions list                  # Browse recent sessions
 aii sessions resume <id>           # Pick up where you left off
-aii sessions info <id>             # View stats (tokens, cost, tools)
 ```
 
 ---
@@ -461,23 +361,14 @@ aii sessions info <id>             # View stats (tokens, cost, tools)
 ```bash
 aii config init                          # Interactive setup wizard
 aii config init --project                # Scaffold project config for this repo
-aii config show                          # Current settings
 aii config show --sources                # Per-key provenance (env/local/project/global)
 aii config validate                      # Check config + API key validity
 aii config set <key> <value>             # Set a specific value
-aii config provider [name]               # Show or switch provider
-aii config model [name]                  # Show or switch model
+aii config provider|model [name]         # Show or switch provider / model
 aii config apikey <provider> [key]       # Set API key (masked input)
-aii config apikey list                   # Show all provider key status
-aii config apikey remove <provider>      # Remove a provider's key
-aii config apikey help                   # Show API key help
-aii config host [host:port]              # Show or change server URL
-aii config models                        # List all available models
-aii config providers                     # List all providers with status
-aii config help                          # Show config help
 ```
 
-Config lives in `~/.aii/`:
+Run `aii config help` for the full list. Config lives in `~/.aii/`:
 
 | File | Purpose |
 |------|---------|
@@ -485,19 +376,23 @@ Config lives in `~/.aii/`:
 | `secrets.yaml` | API keys (file mode 0600) |
 | `mcp_servers.json` | MCP server configuration |
 
-**Session retention.** Past interactive sessions are saved under `~/.aii/sessions/`. On startup, Aii prunes them to the most-recent `sessions.keep` (default **50**) so the directory stays bounded. Set `sessions.keep: 0` to keep all sessions (unlimited):
+Common preference keys, one file:
 
 ```yaml
 # ~/.aii/config.yaml
+git:
+  commit_signature: none    # commit/PR footer: default | none | any literal text
 sessions:
-  keep: 50   # most-recent sessions to retain; 0 = unlimited
+  keep: 50                  # most-recent sessions to retain; 0 = unlimited
+goal:
+  proof_expected: true      # /goal demands proof before accepting completion
 ```
 
 Environment variables also work: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, etc.
 
-### Project configuration (v0.17)
+### Project-level config & commands
 
-A repository can carry its own Aii config — committed for the team, layered under your personal settings:
+A repository can carry its own Aii config and slash commands — committed for the team, layered under your personal settings:
 
 ```bash
 aii config init --project     # creates .aii/settings.json, gitignores .aii/settings.local.json
@@ -507,38 +402,13 @@ aii config init --project     # creates .aii/settings.json, gitignores .aii/sett
 // .aii/settings.json (committed)
 {
   "llm": { "model": "deepseek-v4", "provider": "deepseek" },
-  "output_modes": { "default": "clean" },
-  "permissions": {
-    "deny_write": ["db/migrations/**"],   // paths the agent may never write in this repo
-    "deny_tools": ["Bash"]                // tools the agent may never use in this repo
-  }
+  "permissions": { "deny_write": ["db/migrations/**"], "deny_tools": ["Bash"] }
 }
 ```
 
-Precedence: `flag > env > .aii/settings.local.json > .aii/settings.json > ~/.aii/config.yaml > defaults` — your env pins always win. `aii config show --sources` shows exactly where each effective value came from.
-
-**A repo can only narrow, never widen.** Only safe keys are accepted (model, provider, temperature, output mode, persona, theme, deny rules); anything that would widen authority — `api.*`, `allow_write`, auto-approve flags — is rejected with a warning. Deny rules are enforced everywhere (file tools, Bash write targets, subagents) as hard tool errors. Project values are session-effective only: `aii config set` still writes exclusively to your `~/.aii/config.yaml`.
-
-A repo's `.aii/hooks.json` never runs silently: the first interactive session shows each hook's event + command and asks for approval, remembered in `~/.aii/project-trust.json` until the file changes. Headless runs fail closed. Skip the whole project layer for one session with `aii --no-project-config`.
+Precedence: `flag > env > .aii/settings.local.json > .aii/settings.json > ~/.aii/config.yaml > defaults` — your env pins always win; `aii config show --sources` shows where each value came from. **A repo can only narrow, never widen**: only safe keys are accepted (model, provider, output mode, persona, theme, deny rules); anything that would widen authority is rejected, and deny rules are enforced everywhere as hard tool errors.
 
-### Project slash commands (v0.17.1)
-
-A repository can ship its own slash commands — one markdown file per command under `.aii/commands/`, committed and shared with the team:
-
-```markdown
-<!-- .aii/commands/deploy.md -->
----
-description: Deploy the current branch to staging
-argument-hint: <environment>
----
-Deploy the current branch to $ARGUMENTS:
-1. Run the test suite; abort on failure.
-2. Build and push the image tagged with the short sha.
-```
-
-Typing `/deploy staging` expands the file's body (with `$ARGUMENTS` → `staging`) into the agent turn. The filename is the command name; frontmatter is optional (`description` and `argument-hint` are shown in the `/` menu and `/help`, where project commands carry a `[project]` badge).
-
-**First use asks once.** A cloned repo's command is prompt content the agent will follow with your tools — so the first `/deploy` shows the file's full body and asks. Approve and it's remembered (per file content, in `~/.aii/project-trust.json`) until the file changes; decline and it's skipped. Headless runs fail closed. The same gate now also covers project `.aii/skills/` — repo-committed skills ask before they first run, and an unapproved one is never model-auto-invoked. Project commands are typed-slash only (never triggered by plain English), and `aii --no-project-config` disables commands and skills along with the rest of the project layer.
+Project slash commands live one markdown file per command under `.aii/commands/` — typing `/deploy staging` expands `.aii/commands/deploy.md` (with `$ARGUMENTS` → `staging`) into the agent turn, and project commands carry a `[project]` badge in the `/` menu. **First use asks once**: a cloned repo's command, hook, or skill shows its full content and asks before it ever runs — remembered per file content in `~/.aii/project-trust.json` until the file changes; headless runs fail closed. Skip the whole project layer with `aii --no-project-config`.
 
 ---
 
@@ -550,6 +420,7 @@ Typing `/deploy staging` expands the file's body (with `$ARGUMENTS` → `staging
 | `aii <query>` | Single-shot query |
 | `aii run git commit [-y]` | AI-powered git commit |
 | `aii loop [query] [--flags]` | Autonomous agent loop |
+| `aii cloud <action>` | Aii Cloud — connect this machine, dispatch from the web (BYOC) |
 | `aii config <action>` | Configuration management |
 | `aii mcp <action>` | MCP server management |
 | `aii telegram <action>` | Telegram bot management |
@@ -558,11 +429,12 @@ Typing `/deploy staging` expands the file's body (with `$ARGUMENTS` → `staging
 | `aii skill <action>` | Skill management (list, info, install) |
 | `aii soul <action>` | Soul (personality) management |
 | `aii worktree <action>` | Git worktree management |
+| `aii plugin <action>` | Plugin management |
 | `aii prompt <action>` | Prompt library |
 | `aii upgrade` | Self-update to latest version |
 | `aii doctor` | Health diagnostics |
-| `aii help` | Show help |
-| `aii version` | Show version |
+
+Run `aii help` for the full command list.
 
 ### Global Flags
 
@@ -600,10 +472,7 @@ aii "review the staged diff for correctness bugs" \
   --bare --max-turns 12 --max-budget-usd 1.00 --output-format json | jq -r '.result'
 ```
 
-- **`--max-turns`** is the hard cost bound for a one-shot run — it caps the agent's ReAct iterations per turn (enforced server-side). **`--max-budget-usd`** is a cumulative *between-turns* cap: fully effective for interactive / `--auto` runs; on a single one-shot turn it adds an advisory `over_budget` flag to the JSON output (pair it with `--max-turns` to bound a one-shot's cost).
-- **`--bare`** sends only the result to **stdout** and all status/chrome to **stderr**, so `RESULT=$(aii "…" --bare)` is clean. Compose with `--output-format json` for structured stdout.
-- **`--append-system-prompt[-file]`** injects an additive, escaped instruction (a review rubric, house style) without editing committed config. The file form reads only inside the workspace and rejects symlinks.
-- Ready-to-use **GitHub Actions** recipes live in [`examples/github-actions/`](examples/github-actions/): they use the `pull_request` trigger (never `pull_request_target` with a PR checkout), reference `AII_API_KEY` via `secrets.`, and consume Aii output as data (never `eval`).
+`--max-turns` bounds cost server-side; `--bare` keeps stdout pipe-clean for `RESULT=$(aii "…" --bare)`; on a single one-shot turn, `--max-budget-usd` adds an advisory `over_budget` flag (pair with `--max-turns` to hard-bound cost). Ready-to-use **GitHub Actions** recipes live in [`examples/github-actions/`](examples/github-actions/) — they use the `pull_request` trigger (never `pull_request_target` with a PR checkout), reference `AII_API_KEY` via `secrets.`, and consume Aii output as data (never `eval`).
 
 ---
 
@@ -614,7 +483,6 @@ Run `aii doctor` for automated diagnostics.
 | Problem | Fix |
 |---------|-----|
 | `aii` not found | `curl -fsSL https://aiiware.com/install.sh \| bash` |
-| Update to latest | `aii upgrade` |
 | Server won't start | Make sure Docker is running |
 | API key error | `aii config apikey <provider> <key>` or `aii config init` |
 | Wrong model | `aii config model <name>` |