docs: align backend and release-readiness guidance

Author: eddiman

docs/architecture/backends.md

@@ -73,13 +73,13 @@ Reads `llm.backend` from `adjutant.yaml` (via `load_typed_config()`) and returns
 
 Wraps the existing `core/opencode.py` module. Delegates to `opencode_run()` for async calls and `_find_opencode()` for binary lookup. Parses NDJSON output via `lib/ndjson.py`.
 
-**Capabilities:** vision, model_listing, reaping, web_server, streaming.
+**Capabilities:** vision, model_listing, reaping, streaming.
 
 ### `ClaudeCLIBackend` (`backend_claude_cli.py`)
 
 Invokes `claude -p --output-format json` directly. Parses JSON output via `lib/claude_json.py`. Handles agent prompts by stripping YAML frontmatter from `.opencode/agents/*.md` and passing the body via `--system-prompt-file`.
 
-**Capabilities:** web_server, cost_tracking.
+**Capabilities:** model_listing, cost_tracking.
 
 ---
 
@@ -124,6 +124,8 @@ At startup, `lifecycle/control.py` compares `adjutant.yaml`'s `llm.backend` agai
 4. Update `state/backend.txt`
 5. Log the switch
 
+Backend-native web servers are retired on both backends, so the switch now translates model/session state only.
+
 This is handled by `_detect_backend_change()` and `_handle_backend_switch()`.
 
 ---

docs/architecture/identity.md

@@ -38,7 +38,7 @@ Natural language processing and long-running agent tasks use the LLM backend. Al
 
 Two backends are supported:
 - **OpenCode** (`opencode`): Uses the OpenCode CLI with an Anthropic API key. Supports vision, streaming, model listing, and process reaping.
-- **Claude Code CLI** (`claude-cli`): Uses the Claude Code CLI with a Claude subscription. Supports cost tracking and a web server (CloudCLI).
+- **Claude Code CLI** (`claude-cli`): Uses the Claude Code CLI with a Claude subscription. Supports cost tracking and model listing.
 
 The backend is configured in `adjutant.yaml` under `llm.backend`. See [Backend Architecture](backends.md) for the full protocol and capability system.
 

docs/development/backend-guide.md

@@ -243,22 +243,9 @@ See `portfolio-kb/src/pipeline/analyze.py` for a complete working example of a K
 
 ---
 
-## Web server services
+## Web UI
 
-Each backend has a web server that provides a browser-based UI for remote development:
-
-| Backend | Web server | Binary | Default port | PID file | Health check |
-|---------|-----------|--------|-------------|----------|-------------|
-| `opencode` | OpenCode web | `opencode web --mdns` | 4096 (`OPENCODE_WEB_PORT`) | `state/opencode_web.pid` | HTTP GET `http://localhost:{port}/` |
-| `claude-cli` | CloudCLI | `cloudcli --port {port}` | 3001 (`CLOUDCLI_PORT`) | `state/cloudcli_web.pid` | HTTP GET `http://localhost:{port}/health` |
-
-The web server is managed by `lifecycle/control.py`:
-- **Start**: `start_backend_service()` dispatches to `start_opencode_web()` or `_start_cloudcli_web()` based on the active backend
-- **Stop**: `restart()` and `emergency_kill()` terminate both web servers (handles mid-switch state)
-- **Watchdog**: `listener.py` checks the PID file every ~5 minutes and restarts if dead
-- **Backend switch**: `_handle_backend_switch()` kills the old backend's web server
-
-CloudCLI receives `WORKSPACES_ROOT` (set to `adj_dir`) and `CLAUDE_CLI_PATH` (set to the `claude` binary) as environment variables so it discovers the correct project directory and CLI binary.
+Backend-native web servers are retired on both backends. Adjutant's browser UI is the `web/` app in this monorepo, started with `adjutant web` during development.
 
 ---
 

docs/development/testing.md

@@ -10,7 +10,7 @@ Adjutant uses [pytest](https://pytest.org) as its test framework. Tests are orga
 
 | Tier | Location | Tests | Runtime | Description |
 |------|----------|-------|---------|-------------|
-| Unit | `tests/unit/` | ~1139 | ~75s | Fast, fully mocked, no external calls |
+| Unit | `tests/unit/` | ~1420+ | ~75s | Fast, fully mocked, no external calls |
 | Integration | `tests/integration/` | ~20 | ~5s | Real process spawning, mocked external services |
 
 ---
@@ -70,7 +70,7 @@ All tests must pass. Any failure blocks the release. This is enforced by discipl
 
 ```
 tests/
-└── unit/                    # All tests (~52 files, ~1081 tests)
+└── unit/                    # All tests (~61 files, ~1420+ tests)
     ├── test_lockfiles.py
     ├── test_env.py
     ├── test_paths.py
@@ -90,7 +90,7 @@ tests/
     ├── test_journal_rotate.py
     ├── test_screenshot.py
     ├── test_search.py
-    └── ... (52 files total)
+    └── ... (61 files total)
 ```
 
 ---

docs/guides/backends.md

@@ -48,7 +48,6 @@ adjutant setup
 2. Restart Adjutant: `adjutant restart`
 
 On restart, Adjutant detects the backend change and automatically:
-- Stops the old backend's service (OpenCode web server or CloudCLI web server)
 - Translates the active model ID to the new backend's format
 - Clears the Telegram session (new backend, new conversation)
 - Records the switch in `state/backend.txt`
@@ -64,7 +63,7 @@ No data is lost. You can switch back at any time.
 | Vision (image analysis) | Yes (native) | Yes (via Read tool image injection) |
 | Dynamic model listing | Yes | Yes |
 | Process reaping | Yes | No (not needed) |
-| Web server (remote access) | Yes (`opencode web`) | Yes (CloudCLI) |
+| Backend-native web server | No | No |
 | Streaming output | Yes | No (single-shot JSON) |
 | Cost tracking per request | No | Yes |
 | Session resume | Yes (`--session`) | Yes (`--resume`) |
@@ -87,48 +86,25 @@ npm install -g @anthropic-ai/claude-code
 claude login
 ```
 
-### 3. Install CloudCLI (web UI)
-
-CloudCLI provides a browser-based web UI for the Claude CLI backend, equivalent to `opencode web` for the OpenCode backend. It starts automatically when the `claude-cli` backend is active.
-
-```bash
-npm install -g @siteboon/claude-code-ui
-```
-
-Verify it's installed:
-
-```bash
-cloudcli version
-```
-
-**Configuration** (optional — defaults work out of the box):
-
-| Environment variable | Default | Description |
-|---------------------|---------|-------------|
-| `CLOUDCLI_PORT` | `3001` | Port for the CloudCLI web server |
-| `CLOUDCLI_BIN` | auto-detected from PATH | Explicit path to the `cloudcli` binary |
-
-Adjutant sets `WORKSPACES_ROOT` and `CLAUDE_CLI_PATH` automatically so CloudCLI sees the correct project directory and Claude binary.
-
-### 4. Configure Adjutant
+### 3. Configure Adjutant
 
 ```yaml
 # adjutant.yaml
 llm:
   backend: "claude-cli"
 ```
 
-### 5. Verify
+### 4. Verify
 
 ```bash
 adjutant doctor
 ```
 
 The doctor command checks that the `claude` binary is on PATH, hooks are executable, and the backend is healthy.
 
-### 6. Access the web UI
+### 5. Access the web UI
 
-After `adjutant start`, CloudCLI is available at `http://localhost:3001` (or your configured `CLOUDCLI_PORT`). Access it over VPN or local network to develop on Adjutant remotely from another device.
+Use `adjutant web` to start Adjutant's own web dashboard from the monorepo checkout. Backend-native web servers are retired on both backends.
 
 ---
 

docs/guides/commands.md

@@ -202,7 +202,6 @@ Dependencies:
   jq           OK (jq-1.7)
   python3      OK (Python 3.12.0)
   claude       OK (/opt/homebrew/bin/claude)    # or opencode, depending on llm.backend
-  cloudcli     OK (/opt/homebrew/bin/cloudcli)  # claude-cli backend only
 
 Optional:
   playwright   not installed (needed for screenshot)
@@ -221,6 +220,6 @@ State:
   Listener: Running (PID 12345)
 ```
 
-The backend-specific binaries shown depend on `llm.backend` in `adjutant.yaml`. With `opencode`, doctor checks for the `opencode` binary. With `claude-cli`, it checks for `claude` and `cloudcli`.
+The backend-specific binaries shown depend on `llm.backend` in `adjutant.yaml`. With `opencode`, doctor checks for the `opencode` binary. With `claude-cli`, it checks for `claude`.
 
 If `adjutant doctor` reports missing dependencies or configuration, run `adjutant setup --repair` to fix them interactively.

docs/guides/configuration.md

@@ -61,6 +61,7 @@ features:
     enabled: false
   vision:
     enabled: false
+    model: "cheap"                    # must be cheap|medium|expensive
   search:
     enabled: false                    # requires BRAVE_API_KEY in .env
   usage_tracking:
@@ -171,17 +172,14 @@ The `.env` file is never `source`d directly — Adjutant uses grep-based extract
 
 ### Backend environment variables
 
-These are optional overrides for backend binary paths and web server configuration. They're set in `.env` or your shell environment, not in `adjutant.yaml`.
+These are optional overrides for backend binary paths. They're set in `.env` or your shell environment, not in `adjutant.yaml`.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `OPENCODE_BIN` | auto-detected | Explicit path to the `opencode` binary |
-| `OPENCODE_WEB_PORT` | `4096` | Port for the OpenCode web server |
 | `CLAUDE_CODE_BIN` | auto-detected | Explicit path to the `claude` binary |
-| `CLOUDCLI_BIN` | auto-detected | Explicit path to the `cloudcli` binary |
-| `CLOUDCLI_PORT` | `3001` | Port for the CloudCLI web server (claude-cli backend) |
 
-Adjutant auto-detects binaries from PATH. Only set these if the binary is installed in a non-standard location or you need to override the default port.
+Adjutant auto-detects binaries from PATH. Only set these if the binary is installed in a non-standard location.
 
 ---
 

docs/guides/memory.md

@@ -6,7 +6,7 @@ Adjutant has persistent long-term memory stored as plain Markdown files. The mem
 
 Memory is stored under `memory/` in the Adjutant directory. Each category has its own file. When you tell Adjutant to remember something, it auto-classifies the content and appends it to the right file with a timestamp.
 
-The agent loads `memory/memory.md` (the index) at startup so it knows what's available. Individual memory files are loaded on demand when relevant to the current conversation.
+The agent loads `memory/memory.md` on demand when a conversation touches past decisions, corrections, preferences, or other memory-backed topics. Individual memory files are then loaded as needed.
 
 ## Directory Structure
 

docs/guides/troubleshooting.md

@@ -98,8 +98,8 @@ Look for `[control] Emergency kill` entries.
 
 Cron runs with a minimal `PATH` (`/usr/bin:/bin`), which typically excludes
 directories like `/opt/homebrew/bin` where your LLM backend binary is installed. Adjutant
-snapshots your interactive shell's `PATH` when installing cron entries (via
-`adjutant schedule sync`), so re-syncing usually fixes this:
+installs cron entries with a minimal explicit PATH that includes standard system
+paths plus common package-manager locations, so re-syncing usually fixes this:
 
 ```bash
 adjutant schedule sync
@@ -125,50 +125,6 @@ On macOS, cron needs Full Disk Access to run scripts that access files outside s
 
 Check the job's log file (shown in `adjutant schedule list`). The log path is defined in the schedule's YAML config.
 
-## CloudCLI Web Server Issues
-
-### CloudCLI not found on PATH
-
-CloudCLI is the web UI for the `claude-cli` backend. Install it:
-
-```bash
-npm install -g @siteboon/claude-code-ui
-```
-
-Or set the binary path explicitly:
-
-```bash
-export CLOUDCLI_BIN=/path/to/cloudcli
-```
-
-### CloudCLI web server won't start
-
-Check the log:
-
-```bash
-cat state/cloudcli_web.log
-```
-
-Common causes:
-
-| Cause | Fix |
-|-------|-----|
-| Port already in use | Set a different port: `export CLOUDCLI_PORT=4000` |
-| Binary not found | Install CloudCLI or set `CLOUDCLI_BIN` |
-| Node.js version mismatch | CloudCLI requires Node.js 18+. Check `node --version` |
-
-### CloudCLI starts but is unreachable
-
-CloudCLI binds to `0.0.0.0` by default (all interfaces). If accessing over VPN, ensure the VPN routes traffic to the correct IP. Check:
-
-```bash
-curl http://localhost:3001/health
-```
-
-Should return `{"status":"ok",...}`.
-
----
-
 ## Model / AI Issues
 
 ### "Model not found" errors

docs/reference/2026-04-14-deployment-readiness.md

@@ -202,13 +202,15 @@ working local install via the published setup or installer path.
      `src/adjutant/messaging/telegram/commands.py`
    - **Action:** Align public command docs to actual shipped handlers, or
      implement the missing commands before release.
+   - **Resolved 2026-04-18:** Aligned the public command surface to the actual Telegram dispatcher and handlers. Removed stale `/models`, `/memory`, and `/news` references from `README.md` and `docs/getting-started/first-message.md`, and documented the shipped `/brief`, `/recall`, and `/digest` commands instead.
 
 2. **Release and install story is not coherent end-to-end**
    - **Files:** `.github/workflows/release.yml`, `src/adjutant/setup/install.py`,
      `README.md`
    - **Action:** Pick one supported public install path and document it
      consistently. If the Python installer is the intended story, wire and
      publish it as such. If not, stop presenting it as part of release readiness.
+   - **Resolved 2026-04-18:** Promoted the installer to the canonical public path. Added a repo-root `install.py` entrypoint so a fresh clone or extracted release tarball can run `python3 install.py` directly, updated `src/adjutant/setup/install.py` to create `.venv` and install Adjutant into it before launching the wizard, and rewrote the release body plus getting-started docs to use that single flow consistently.
 
 3. **Shell-based scheduled command execution needs hardening before public ship**
    - **Files:** `src/adjutant/cli.py`,
@@ -217,11 +219,13 @@ working local install via the published setup or installer path.
    - **Action:** Replace shell-string execution with argument-list execution where
      possible, or constrain and validate command generation so no user- or
      config-derived string reaches `shell=True` unsafely.
+   - **Resolved 2026-04-18:** Reworked scheduled-command resolution around structured argv. `schedule.manage.resolve_command_argv()` now parses `script:` entries safely, `schedule.install.run_now()` and `notify_wrap.py` execute argv lists instead of `shell=True`, `adjutant schedule run` now uses the shared runner, and the schedule wizard now installs jobs through the same hardened schedule API. Cron entries still use `/bin/bash -lc`, but only to execute a fully quoted command built from structured argv plus explicit env assignments, not a raw user-derived shell string.
 
 4. **Release gate requires a clearly recorded clean full test run**
    - **Files:** `tests/`, release/testing docs, backend and schedule test paths
    - **Action:** Run the full suite, resolve any failures, and make a clean full
      pass the explicit release gate before tagging.
+   - **Resolved 2026-04-18:** Ran `.venv/bin/pytest tests/ -q` and got `1428 passed, 73 skipped, 1 warning in 8.02s`. Also updated `docs/development/testing.md` to stop advertising the stale lower approximate test counts.
 
 ### P1 — degrades quality
 
@@ -230,22 +234,26 @@ working local install via the published setup or installer path.
      `docs/guides/configuration.md`, `README.md`
    - **Action:** Remove CloudCLI or opencode-web-era references and align docs to
      the current `web/` architecture.
+   - **Resolved 2026-04-18:** Removed backend-native web-server guidance from `docs/guides/backends.md`, `docs/guides/configuration.md`, `docs/guides/troubleshooting.md`, `docs/guides/commands.md`, and `docs/development/backend-guide.md`, and replaced it with the current `adjutant web` / `web/` dashboard architecture where relevant.
 
 2. **Unused runtime dependency likely remains**
    - **Files:** `pyproject.toml`
    - **Action:** Remove `rich` if it is truly unused, or add the missing usage
      intentionally.
+   - **Resolved 2026-04-18:** Removed `rich` from `pyproject.toml` after confirming there are no runtime imports in `src/`.
 
 3. **Private helper imports weaken code boundaries**
    - **Files:** `src/adjutant/capabilities/schedule/install.py`,
      `src/adjutant/capabilities/kb/query.py`
    - **Action:** Promote these helpers to public APIs or stop importing
      underscore-prefixed functions across modules.
+   - **Resolved 2026-04-18:** Promoted `resolve_path()` in `schedule.manage` and `get_kb()` in `kb.run` to public helpers, then updated the importing modules to use the public names instead of underscore-prefixed internals.
 
 4. **Exception swallowing remains high**
    - **Files:** distributed across `src/`
    - **Action:** Review silent-swallow and fallback-default cases, especially
      around config, filesystem, and subprocess branches.
+   - **Status 2026-04-18:** Not addressed in this pass. The release-blocking and release-facing issues above were fixed first; broad exception-audit work remains follow-up debt rather than a blocker for the corrected deployment path.
 
 ### P2 — acceptable to defer