@mmmbuto/nexuscrew 0.9.16 → 0.9.18

package/CHANGELOG.md

@@ -2,6 +2,133 @@
 
 All notable changes to NexusCrew are tracked here.
 
+## 0.9.18 — 2026-09-04
+
+### Upstream Rust 0.153.2
+
+- **New upstream capabilities.** The GPT-6-Astra model catalogue is included,
+  hook activity is visible in the TUI, and app-server supports asynchronous user
+  input with thread metadata.
+- **Smoother daily use.** Vim undo/redo and app-server reconnect improve the
+  interactive experience, while `[tui].disable_paste_burst` is documented in
+  its canonical configuration location.
+- **More context control.** Experimental context management is available for
+  evaluation alongside the upstream release changes.
+
+### Codex VL fixes
+
+- **Loops stay responsive.** Failed `/loop` owner and delegate preconditions
+  report an error without terminating the TUI; `/loop` usage also lists the
+  delegate, strategy, delegation and owner commands.
+- **Vivling and fleet metadata recover cleanly.** `manage_loops` sees its jobs
+  after resume, and Vivling accepts fenced or prefixed JSON replies from any
+  provider while model metadata is resolved by engine identity.
+- **Quieter, clearer operation.** The expression planner no longer floods the
+  log database, terminal state reconciles after every terminal event, and Esc
+  interrupts a running task even during a long tool call.
+
+## 0.9.17 — 2026-09-01 — "The Package Reads Like The Product"
+
+- **The installed files no longer carry the workshop's notes.** In the payload
+  of 0.9.16 and earlier, a reader of the installed package could find traces of
+  the environment that builds NexusCrew: device and node names, working paths
+  and hostnames, and the markers of the internal review process, sitting in
+  comments and metadata next to the product's own code. Nothing secret and
+  nothing functional — but writing addressed to the builders has no business
+  shipping to the users, and a version is never republished, so it stayed.
+  The payload has been swept: the installed tree now reads as the product
+  only. The sweep covers the classes above, and says so rather than claiming
+  every sentence of every comment was rewritten.
+
+- **The promise is checked by tests that read the artifact, not by a
+  checklist.** The npm payload and the published git surface are both
+  inspected by the suite: every forbidden pattern is listed with its reason,
+  a file that cannot be read fails the check instead of being skipped, and a
+  pattern list emptied to make the suite pass fails with it. What the package
+  ships is now a tested property, not a step someone remembers to do.
+
+- **The guides it points to travel with the package.** The README and three
+  built-in skills cite thirteen documentation files that an npm install never
+  contained: all twenty-six relative links were dead out of the box, sending
+  the reader to files that were not there. The thirteen guides now ship with
+  the package — those and no others.
+
+## 0.9.16 — 2026-08-28 — "The Cap Becomes One Hundred"
+
+- **The fleet engine cap is 100, and the backup reads its own exports.** The
+  server accepted up to 100 engines and refused the 101st with an explicit
+  reason, but the fleet-backup parser on the frontend still enforced the old
+  cap of 24: `createFleetBackup` happily produced documents with 25–100
+  engines that `parseFleetBackup` then rejected as `invalid-format`. The
+  frontend copy is now aligned with the backend cap, and the parser names the
+  cap in its refusal instead of reporting a generic format error — a fleet of
+  any valid size round-trips.
+
+- **WebSocket closures are classified, counted, and visible.** Inter-cell
+  sends and drop counters land in the observability surface, so a connection
+  that keeps falling can be told apart from one that was never stable.
+
+- **The first health sample that says down means down.** Hysteresis only
+  protects a previously authoritative `transport: up`; without one, the first
+  failed probe is a real failure and is reported as such, instead of leaving
+  a dead node labelled unknown.
+
+- **Catalog and skills surface sanitized**: internal cell names are gone from
+  skills, UI placeholders and comments.
+
+## 0.9.15 — 2026-08-27 — "The Terminals Survive A Flaky Connection"
+
+- **Terminal panes no longer rebuild because of one late health probe.** A
+  single slow peer-health check declared a live node dead; the roster
+  emptied, and when the node came back every terminal window was rebuilt from
+  scratch — new socket, new attach, full repaint — whose traffic then caused
+  the next drop on an already queued line. Transient peer-health failures are
+  tolerated instead of tearing the node down.
+
+- **PTYs survive transient terminal disconnects**, and resumes are authorized
+  before scope checks, so a reconnecting pane picks its session back up
+  instead of starting over.
+
+- **The Live star distinguishes a started thread from an active one**, the
+  Live bridge declares its Fleet identity on initialize, and thread status
+  labels are guarded against Live claims.
+
+- **MCP identity failures are no longer cached for life**: a blocked tool
+  names the cause and gets a fresh chance instead of being failed forever.
+
+## 0.9.14 — 2026-08-27 — "The Bundle Builds After The Bump"
+
+- **The package installs.** 0.9.13 shipped with `frontend/dist/version.json`
+  still saying `0.9.12` while the server reported `0.9.13`, so nodes refused
+  to start with «incomplete installation: frontend and server do not match».
+  The bundle had been rebuilt before the version was raised and carried the
+  old number. No functional change against 0.9.13 — the same two fixes ship
+  again, with both sides agreeing on the version.
+
+## 0.9.13 — 2026-08-27 — "The Cells Stay When The Connection Drops"
+
+- **One deadline per lease.** The supervisor's lease read the clock three
+  times for a single transaction: the persisted bound and the proof expiry
+  were taken at different instants, and a one-millisecond gap invalidated the
+  proof at the next check, dropping the lease and letting cells detach and
+  reattach on their own. The deadline is now computed once and the proof
+  expiry derives from it.
+
+- **The roster distinguishes "could not ask" from "nothing is there".** A
+  skipped poll or a fallen node no longer empties the cell list; the last
+  known roster is kept until a real state replaces it.
+
+- **A cell's identity is refused, not borrowed.** Identity resolution fails
+  closed instead of attributing a cell to another one, and a remote `vl`
+  variant that is missing its Ollama pair refuses naming the offending field
+  rather than silently falling back to local Ollama. A `vl` cell can live
+  outside the local Ollama too, and `vl.native` no longer overrides the
+  operator's choices.
+
+- **New skill `cellforge`** (create, modify and audit a cell) and
+  **opencode-go**: `deepseek-v4-flash-vision-exp` added with real
+  measurements; the git publish surface now has the same gate the npm one had.
+
 ## 0.9.12 — 2026-08-22 — "Build After The Bump"
 
 - **Fixes 0.9.11, which would not start.** `frontend/dist/version.json` said
@@ -2199,7 +2326,7 @@ nothing anywhere said so.
   injection. Persistent offline queues, attachments and delegated capability workers remain
   explicitly deferred rather than being represented as implemented.
 - Tests: **770 total** (769 pass / 1 platform-dependent skip) in the isolated Node harness plus
-  5 passing frontend component tests; production build PASS. Real Mac–hub–Pixel end-to-end
+  5 passing frontend component tests; production build PASS. Real nodo-A–hub–nodo-B end-to-end
   pairing and delivery remain an operator field test and are not represented as automated.
 
 ## 0.8.12 — 2026-07-13 — "Mobile Roster"
@@ -2223,7 +2350,7 @@ nothing anywhere said so.
   is disabled and explains that a Termux boot script still requires the Termux:Boot app to be
   installed and launched once.
 - Tests: **749 total** (748 pass / 1 platform-dependent skip), production build PASS, root and
-  frontend dependency audits clean. Mac–Pixel–hub end-to-end pairing was not executed in this
+  frontend dependency audits clean. nodo-A–nodo-B–hub end-to-end pairing was not executed in this
   release gate.
 
 ## 0.8.11 — 2026-07-13 — "Tmux Survival"
@@ -2281,7 +2408,7 @@ nothing anywhere said so.
   HTTP-port move when paired peers depend on the configured endpoint.
 - Tests: **726 total** (725 pass / 1 platform-dependent skip), frontend production build PASS,
   dependency audit clean, isolated HOME clean, and package/public-tree verification required
-  before publication. Real Mac–Pixel–hub interoperability remains an external follow-up and is
+  before publication. Real nodo-A–nodo-B–hub interoperability remains an external follow-up and is
   not represented as an automated test.
 
 ## 0.8.9 — 2026-07-12 — "Hydra Workspaces"
@@ -2309,6 +2436,11 @@ nothing anywhere said so.
 
 ## 0.8.8 — 2026-07-12 — "Reliable Composer"
 
+> **Never published.** Only a preparation commit exists for this version and
+> npm has no 0.8.8 — the next published release is 0.8.9. The entry stays
+> because the changes it describes are real; a reader looking for the version
+> on the registry should know why it is not there.
+
 - The PWA composer now sends long and multiline drafts through xterm's explicit paste path,
   preserving the terminal application's bracketed-paste mode. Enter travels as a separate
   input only after the complete paste was accepted, so agent TUIs no longer absorb submission
@@ -2625,6 +2757,19 @@ Core rewrite from screenshot-and-poll to a faithful tmux client.
   backpressure cutoff, JSON errors with codes
 - token delivered via URL fragment (never logged), 0600 file, constant-time compare
 
+## 0.2.5 — 2026-04-09 — "Discovery, Routes, Selector"
+
+Reconstructed from the release commit and its tree: this entry was missing
+from the file at the time, and the history before 0.7.1 survives only in the
+`v0.2.5` tag and on npm.
+
+- Engine discovery and explicit send routes in the runtime — the release
+  commit's own summary — with the chat flow and the status bar wired to them.
+- A dedicated model selector interface: new `ModelSelector` component and
+  styles wired into the chat.
+- A prebuilt SQLite library travels with the package instead of requiring a
+  local build.
+
 ## 0.2.4
 
 - added host-scoped tmux/session discovery so active session truth comes from the selected host
@@ -2649,3 +2794,12 @@ Core rewrite from screenshot-and-poll to a faithful tmux client.
 ## 0.2.1
 
 - older release line, now deprecated in favor of the current stable line
+
+## 0.2.0 — 2026-04-01 — "First Published"
+
+- The first version of the 0.2 line to reach npm: a tmux-based cockpit with
+  persistent sessions for Claude Code, Codex CLI, Gemini CLI and Qwen Code,
+  with remote SSH host support.
+- Reconstructed from the published package's own description — no release
+  notes from that date survive in this history. The line was later superseded
+  by the 0.4 rewrite and deprecated.

package/docs/ALIBABA_TOKEN_PLAN.md

@@ -0,0 +1,70 @@
+# Alibaba Token Plan Personal engines
+
+NexusCrew exposes three first-class managed profiles backed by one fixed local
+credential name, `ALIBABA_CODE_API_KEY`:
+
+- `claude.alibaba-token-plan`
+- `codex-vl.alibaba-token-plan`
+- `pi.alibaba-token-plan`
+
+The credential value is resolved by the NexusCrew credential layer and is
+passed only in the selected child process environment. Engine definitions,
+generated extensions, argv, status responses and logs contain only the
+environment-variable name, never its value. The default model is
+`qwen3.8-max` for all three profiles.
+
+## Claude Code
+
+- Anthropic-compatible base URL:
+  `https://token-plan.ap-southeast-1.maas.aliyuncs.com/apps/anthropic`
+  (Claude appends `/v1/messages`; the configured base must not include it).
+- Authentication: `ANTHROPIC_AUTH_TOKEN` receives the locally resolved value;
+  `ANTHROPIC_API_KEY` is deliberately empty.
+- Aliases: MODEL/SONNET/OPUS/FABLE = `qwen3.8-max`, HAIKU =
+  `qwen3.6-flash`, SUBAGENT = `qwen3.7-max`.
+- Context: `983616`; effort: `xhigh`. Qwen Cloud documents qwen3.8 thinking
+  as always enabled and not user-disableable.
+- State is isolated under
+  `~/.nexuscrew/claude-profiles/alibaba-token-plan/` with private modes; the
+  native Claude configuration is not modified and no credential is written
+  there.
+
+## Codex-VL
+
+- Compatible base URL:
+  `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1`.
+- Provider wire API: `responses`; provider `env_key`:
+  `ALIBABA_CODE_API_KEY`. `OPENAI_API_KEY` is neither read nor forwarded by
+  this profile, and there is no OpenAI/PAYG fallback.
+- Latest-Codex allowlist: `qwen3.8-max`, `qwen3.7-max`,
+  `qwen3.7-plus`, `qwen3.6-flash`. GLM and DeepSeek are intentionally absent.
+- The bundled qwen3.8 catalog pins context `983616`, effective context `95%`,
+  reasoning levels `low/high/xhigh` with `xhigh` default, parallel tools off,
+  text+image input and original image detail.
+- Offline compatibility target: `codex-vl 0.144.7`.
+
+## Pi
+
+- Dedicated provider ID `alibaba-token-plan`, standard permissions only.
+- A generated private extension refers to `$ALIBABA_CODE_API_KEY`; it contains
+  no credential value.
+- Qwen response-capable models use Pi's `openai-responses` adapter. `glm-5.2`
+  and `deepseek-v4-pro` use Pi's `openai-completions` adapter, whose compatibility
+  path preserves `reasoning_content` in replayed assistant/tool turns.
+- `qwen3.8-max` is reasoning-enabled, accepts text+image, uses context
+  `983616`, and launches with `--thinking xhigh`.
+- Offline compatibility target: `pi 0.80.10`.
+
+## Verification boundary
+
+Catalog, normalization, credential resolution, generated config/extension,
+argv/env separation and local runtime loading are tested without network
+access. No provider request is part of this candidate. Endpoint acceptance,
+stream completion, vision input, tool round-trip and Token Plan quota behavior
+remain post-reboot interactive smoke gates.
+
+Primary references:
+
+- https://docs.qwencloud.com/developer-guides/clients-and-developer-tools/claude-code
+- https://docs.qwencloud.com/developer-guides/clients-and-developer-tools/codex
+- https://docs.qwencloud.com/developer-guides/clients-and-developer-tools/openclaw

package/docs/AUDIO_SHARE.md

@@ -0,0 +1,119 @@
+# Audio Share and native TTS
+
+[← Documentation index](README.md)
+
+Audio Share lets an authorized Fleet cell ask a **specific node with a real
+speaker** to synthesize a short utterance. It is separate from browser spoken
+notifications: browser speech remains a visible-and-focused PWA convenience,
+while Audio Share is a node-local backend capability.
+
+There is no cloud speech provider, central voice service, browser relay, or
+`play arbitrary audio file` command in this feature.
+
+## Consent and routing are separate
+
+Three independent controls must all permit delivery:
+
+1. **Share** publishes a node to the authorized transport topology.
+2. **Visibility** controls which peers may route through it.
+3. **Audio consent** is local to the node that would make sound, defaults to
+   off, and is never mutable through federation.
+
+Turning on Share never grants permission to make a device speak. A target node
+also applies its own ACL, `READONLY` state, rate limit, native-adapter
+availability and local consent immediately before synthesis.
+
+Configure consent under **Settings → Audio** on the device that owns the
+speaker. The panel exposes only redacted capability metadata, an explicit
+fixed-text local test, and a local Stop button. Stop remains available in
+`READONLY`; speaking does not.
+
+## Exact targets and groups
+
+`nc_speak` accepts one exact 32-character node instance ID. There is no
+wildcard, `all`, label or route-name target.
+
+Settings can also save local named groups of up to eight exact node IDs:
+
+- **Primary + failover** is the default. It tries the ordered primary, waits up
+  to five seconds for a start acknowledgement, then tries the next endpoint on
+  `refused`, `unreachable`, or `unknown`.
+- **Fan-out** is explicit. It tries all configured endpoints in parallel.
+
+A group is only an origin-side delivery preference. It cannot override consent,
+ACL, liveness, `READONLY`, or a local Stop on any member. A temporarily absent
+member remains visible in group editing but is not treated as ready.
+
+## MCP commands
+
+The caller must be an active local Fleet cell. NexusCrew signs the bridge
+request with a node-local HMAC and resolves the real tmux/Fleet identity; a UI
+bearer token, a request header, or a body field cannot declare a cell identity.
+
+| Tool | Purpose |
+|---|---|
+| `nc_speak` | Speak to one exact node ID. |
+| `nc_speak_status` | Read the caller-scoped receipt for one exact-target utterance. |
+| `nc_speak_stop` | Stop an exact-target utterance, or all caller-owned utterances on that target. |
+| `nc_speak_group` | Start a local named primary/failover or explicit fan-out group. |
+| `nc_speak_group_status` | Read the caller-scoped per-endpoint group receipt. |
+| `nc_speak_group_stop` | Prevent later failover candidates and send Stop to endpoints already admitted. |
+
+Text is limited to 320 characters. Receipts intentionally never retain text,
+language, voice, binary path, route, secret, or an aggregate success boolean.
+Each endpoint is reported independently as:
+
+```text
+refused | unreachable | accepted | spoken | unknown
+```
+
+`spoken` means only that the native adapter confirmed it started synthesis. It
+does **not** prove that a person heard anything: an output sink can be muted,
+null, disconnected, or unavailable. `accepted` is transitional; the caller
+queries status by immutable utterance ID for later state changes.
+
+## Native platform adapters
+
+| Platform | Preferred native command | Important limitation |
+|---|---|---|
+| Android / Termux | `termux-tts-speak` | Requires Termux:API and its permissions; Android Doze can suspend the process. |
+| macOS | `say` | Requires an active GUI/CoreAudio output path; command success is not an audibility test. |
+| Linux | `espeak-ng`, then `spd-say` | Requires a real output sink; a null or headless sink can return exit 0 without sound. |
+
+The implementation probes executable availability without playing sound. It
+sends text on stdin whenever the command supports it; `spd-say` is a declared
+fallback whose text must be placed in argv. Automatic tests use fakes and do
+not claim physical audibility on any platform.
+
+## Safety behavior
+
+- One node serializes its own utterances; normal pending work is bounded.
+- A high-urgency utterance may preempt queue order but never bypasses rate
+  limits or consent.
+- An adapter-start watchdog reports `unknown`, not a fabricated success.
+- Remote Stop is scoped by origin and utterance ID. Local Stop is sovereign and
+  works without network, hub, credentials, or a running caller.
+- Audio receipt and group receipt storage are bounded to 512 records with a
+  24-hour TTL.
+- An utterance ID cannot be reused between group and single-target commands by
+  the same caller while its receipt remains live.
+
+## Local state
+
+All Audio Share state remains local to the node:
+
+| File | Contents |
+|---|---|
+| `~/.nexuscrew/audio.json` | Closed-schema local audio consent. |
+| `~/.nexuscrew/audio-groups.json` | Local named target groups, user-only and atomic. |
+| `~/.nexuscrew/audio-bridge.key` | User-only HMAC secret for MCP-to-server origin proof. |
+
+These files are not Fleet credentials, are not federated, and must not be
+copied into logs, tickets, or a shared repository.
+
+## Related guides
+
+- [MCP bridge](MCP.md)
+- [Notifications](NOTIFICATIONS.md)
+- [Connect nodes](NODES.md)
+- [Security](SECURITY.md)

package/docs/CELL_PANEL.md

@@ -0,0 +1,156 @@
+# The cell panel
+
+A cell can carry a **panel**: a web interface of its own that NexusCrew serves
+inside the app, next to the terminal. A remote desktop, a notebook, a dashboard
+— anything that speaks HTTP.
+
+The panel is opt-in and off by default. A cell without `panelUrl` simply has no
+panel button.
+
+## Configuring it
+
+`panelUrl` is a **property of the cell**, a sibling of `engine` and `cwd`. It is
+not a command, not an argument, and not something the cell runs:
+
+```json
+{
+  "cells": [
+    {
+      "id": "Design",
+      "engine": "shell.local",
+      "commands": { "shell.local": "zsh" },
+      "panelUrl": "http://127.0.0.1:6080/vnc.html"
+    }
+  ]
+}
+```
+
+Put it on an **engine** instead, and it becomes the default for every cell using
+that engine.
+
+The value must be an `http:` or `https:` URL pointing at **loopback** —
+`127.0.0.1`, `[::1]` or `localhost`. Anything else is rejected when the
+definition is read, and the cell keeps working without a panel. A container's
+own address does not count as loopback: publish the port to `127.0.0.1` on the
+host and point the panel there.
+
+### The mistake to avoid
+
+Do not put the URL in the cell's **command**. The command is what the cell
+executes, so this:
+
+```json
+"commands": { "shell.local": "panelUrl: http://127.0.0.1:6900/" }
+```
+
+makes the cell try to run `panelUrl:` as a program. It fails to start, and
+because no `panelUrl` property was ever set, no panel button appears either —
+two symptoms, one cause, and neither of them says "wrong field".
+
+### Setting it from the app
+
+The cell and engine editors carry a `panelUrl` field. It anticipates the same
+loopback rule the backend enforces, so a non-loopback value is flagged before
+you save — but that check is not authoritative: the definition is validated
+again, the same way, the moment it is actually read.
+
+You can still set it by editing the fleet definition directly, or by exporting
+a fleet backup, adding the property, and importing it back.
+
+## A worked example
+
+A container publishing a remote desktop on the host's loopback:
+
+```
+127.0.0.1:6900  ->  the desktop's web interface
+```
+
+Then, on the cell you want to watch it from:
+
+```json
+"panelUrl": "http://127.0.0.1:6900/"
+```
+
+Start the cell and open it: the panel button sits next to the terminal.
+
+If the desktop asks for a password, you will be asked for it inside the panel —
+the forwarder carries no credentials of its own, in either direction.
+
+## Checking it worked
+
+| What you see | What it means |
+|---|---|
+| No panel button at all | The cell has no valid `panelUrl`. Either it was never set, or it was rejected — a non-loopback host, or a value that is not a URL. |
+| Button present, frame says the panel is unavailable | The cell was found but the destination did not answer. Check the service is listening **on loopback of the machine running the node**. |
+| Button present, frame shows the page | Working. Sub-resources and WebSocket travel on the viewing cookie described below. |
+| "This node does not grant the panel to the requester" | The panel lives on a paired node that has not granted access. It is granted there, not here — see the last section. |
+
+Note the difference between the first two rows: a missing button is a
+**configuration** problem, an unavailable frame is a **reachability** one. They
+look similar and have nothing to do with each other.
+
+## Why loopback only
+
+This is the constraint that shapes everything else, so it is worth stating
+plainly: **the panel forwarder is not a port-forward.**
+
+The caller picks *which cell* to open, never *where to connect*. The
+destination is resolved from that cell's own `panelUrl`, on the machine that
+runs the node. Without this rule, a route that opens "a panel" would be a way
+to reach any address the node can reach — including services that trust the
+network they sit on.
+
+The panel is also a service that already holds sessions: behind a remote
+desktop there is usually a browser with accounts logged in. That kind of access
+is not revoked by rotating a key, which is why access is granted per peer and
+denied by default.
+
+## Where it runs
+
+| Platform | State |
+|---|---|
+| Linux server / VPS | **In use.** Any loopback service works; the common case is a container exposing noVNC on `127.0.0.1`. |
+| Termux / Android | **Expected to work, not verified.** The forwarder needs nothing but a loopback HTTP service — no container runtime, no specific desktop. It has not been tried, and until it is, treat it as untested rather than supported. |
+
+Nothing in the forwarder is platform-specific: it proxies HTTP and WebSocket to
+a URL. If a platform can run a web service on loopback, it can host a panel.
+
+## How the browser gets in
+
+Worth knowing, because it explains a design that would otherwise look odd.
+
+An `<iframe src>` is a browser navigation: it carries no application headers.
+So the panel cannot sit behind the usual bearer-token gate — the one consumer
+it exists for would be locked out. Putting the token in the query string does
+not help either: the panel's own pages request their sub-resources with
+relative URLs and no query, so everything after the first request would fail
+and the frame would stay blank.
+
+Instead:
+
+1. the authenticated app asks for a **ticket** — opaque, one-use, valid for
+   seconds, bound to one cell;
+2. the frame's first request spends it, and the answer sets a **viewing
+   cookie**: `HttpOnly`, `SameSite=Strict`, scoped by `Path` to that cell's
+   panel subtree;
+3. the relative sub-resources travel on that cookie, and nothing else does.
+
+The node's token never reaches the browser, a log, or a `Referer` header, and
+no credential of ours is forwarded to the panel itself.
+
+## Panels on another machine
+
+A panel can be opened toward a node you have paired, but **only if that node
+granted it**:
+
+```
+nexuscrew nodes panel <node> on
+```
+
+The default is off, and it is off deliberately: in the pairing model a peer is
+otherwise treated much like the operator, and that is a coherent choice for
+everything except a panel, for the reason given above.
+
+The decision is always made by the node that **owns** the panel, never by the
+one asking. When it says no, the interface says so by name — you get "panel not
+granted", not a blank rectangle you have to guess about.

package/docs/CONFIGURATION.md

@@ -0,0 +1,122 @@
+# Configuration
+
+[← Documentation index](README.md)
+
+Most setup lives in the PWA. Runtime state is local to the current user and is
+never synchronized to a hosted control service.
+
+## Local paths
+
+| Path | Contents |
+|---|---|
+| `~/.nexuscrew/config.json` | Port, Fleet mode and runtime options |
+| `~/.nexuscrew/token` | Local PWA bearer token |
+| `~/.nexuscrew/credentials.json` | Optional node-local write-only provider store |
+| `~/.nexuscrew/audio.json` | Local Audio Share consent (default off) |
+| `~/.nexuscrew/audio-groups.json` | Local named Audio Share target groups |
+| `~/.nexuscrew/audio-bridge.key` | Local HMAC proof for MCP Audio Share calls |
+| `~/.nexuscrew/tunnels/` | Managed SSH supervisor state and owner-only logs |
+| `~/NexusFiles/<session>/` | Per-session inbox and outbox |
+
+Sensitive files are created with user-only permissions. The credential store is
+optional; NexusCrew can also resolve compatible provider variables from its
+service environment.
+
+## Precedence
+
+Runtime values follow:
+
+```text
+defaults < config file < environment
+```
+
+Common overrides:
+
+| Variable | Purpose |
+|---|---|
+| `NEXUSCREW_PORT` | Loopback HTTP port |
+| `NEXUSCREW_CONFIG_FILE` | Alternate config file, useful for isolated tests |
+| `NEXUSCREW_TOKEN_FILE` | Alternate bearer-token file |
+| `NEXUSCREW_FILES_ROOT` | Alternate per-session file root |
+| `NEXUSCREW_TMUX` | tmux executable |
+| `NEXUSCREW_FLEET=0` | Disable Fleet management |
+| `NEXUSCREW_ALTERNATE_SCREEN=1` | Keep tmux's standard alternate-screen behavior for newly created NexusCrew sessions |
+| `NEXUSCREW_READONLY=1` | Disable server-side mutations |
+| `NEXUSCREW_AUTO_UPDATE=0` | Disable the stable update scheduler |
+| `NEXUSCREW_DEBUG=1` | Enable bounded verbose diagnostics |
+| `NEXUSCREW_VOICE_URL` | Optional server-side speech-to-text endpoint |
+| `NEXUSCREW_VOICE_TOKEN_FILE` | Token file for the optional STT endpoint |
+
+Use `NEXUSCREW_CONFIG_FILE`, `NEXUSCREW_TOKEN_FILE`, `NEXUSCREW_FILES_ROOT`
+and a separate `HOME`/XDG root when creating an isolated test runtime.
+
+## Session and Fleet settings
+
+| `config.json` key | Default | Effect |
+|---|---:|---|
+| `alternateScreen` | `false` | New sessions created through Fleet or the PWA keep full-screen TUI output on the normal screen, where it enters tmux history and remains scrollable. Set `true` to restore the standard tmux alternate screen. |
+
+The setting applies only when NexusCrew creates a session through Fleet or the
+PWA; active and unmanaged sessions are not changed. `NEXUSCREW_ALTERNATE_SCREEN=1` has the usual
+environment precedence. For the normal-screen mode, keep the user-owned tmux
+`history-limit` at least 10000 (100000 is a practical value). `nexuscrew doctor`
+warns when it observes a lower value but never changes `~/.tmux.conf`.
+In the PWA, the same local setting is available at **Settings → System →
+Diagnostics**.
+
+Fleet cells and engines are managed in **Settings → Fleet**. A cell records:
+
+- logical cell name and tmux session
+- working directory
+- engine, provider and model
+- permission policy
+- optional system prompt or trusted Shell command
+- boot state
+
+Provider key values are not stored in cell or engine definitions. The PWA
+reports whether a required variable is configured, but never returns its value.
+
+## Browser-local settings
+
+The following are local to the browser origin:
+
+- deck layout and node collapse state
+- session ordering and pins
+- mobile key-bar and keyboard preferences
+- per-cell draft, composer size and bounded prompt history
+- spoken-notification opt-in and successful per-page voice priming
+
+Browser-local state is not included in Fleet backups and can be cleared from
+**Settings → System**.
+
+## Speech input
+
+Speech-to-text has two independent paths:
+
+- Browser Web Speech where the browser exposes it.
+- Optional server STT through `NEXUSCREW_VOICE_URL`.
+
+If neither path is available, the microphone control is hidden. Server STT is
+separate from optional spoken notifications, which use the device's browser
+speech engine and send no text to a speech service.
+
+## Token rotation
+
+The browser token travels in the URL fragment (`#token=...`), not in the
+initial HTTP request. To rotate it:
+
+```bash
+nexuscrew stop
+rm ~/.nexuscrew/token
+nexuscrew
+```
+
+Review the exact target before removing any alternate token file.
+
+## Related guides
+
+- [Fleet and terminals](FLEET.md)
+- [Notifications](NOTIFICATIONS.md)
+- [Audio Share and native TTS](AUDIO_SHARE.md)
+- [Security](SECURITY.md)
+- [Operations](OPERATIONS.md)