@mmmbuto/nexuscrew 0.9.16 → 0.9.17

package/docs/NODES.md

@@ -0,0 +1,214 @@
+# Connect nodes
+
+[← Documentation index](README.md)
+
+Every NexusCrew installation starts as a local node. Connected nodes use
+supervised OpenSSH links; NexusCrew does not replace SSH, generate SSH keys or
+edit `authorized_keys`.
+
+## Pair a node
+
+1. On the installation that will host the new node, open
+   **Settings → Nodes → Invite a node**.
+2. Provide the OpenSSH target the joining device can use, such as `user@host`
+   or a local SSH config alias.
+3. On the joining device, paste the complete pairing link in
+   **Settings → Nodes** and choose **Test and connect**.
+4. If the portable address cannot select the correct key, open
+   **Advanced / edit** and use the SSH alias that already works on that device.
+
+An invite belongs to the installation that will host the node, so it is issued
+there and nowhere else. Minting one is not a federated operation: a node you are
+connected to cannot be asked to admit a further node on your behalf. If you are
+on a client and the interface refuses, open NexusCrew on the hub itself.
+
+The pairing payload is not a browser URL. It contains a short-lived, one-time
+invite and routing fields, but no SSH private key, provider key or PWA token.
+
+For headless installations, use:
+
+```bash
+nexuscrew nodes invite --ssh user@host
+nexuscrew nodes pair
+nexuscrew nodes join
+```
+
+Pair/join reads the one-time payload from stdin so it does not need to appear
+in process arguments.
+
+## Where a node's controls live
+
+**Settings → Nodes** lists nodes one per row: name, how it is reached, and what
+it sees of the network. Selecting a row opens that node's sheet — a panel at the
+side on a wide screen, a sheet rising from the bottom on a narrow one — and
+every per-node control lives there: reachability and transport, visibility and
+its grants, edit, test, connect or disconnect, remove.
+
+Nothing in the list itself mutates a node. Publishing *this* device, and
+inviting a new one, stay outside the list because they are not properties of a
+node you are looking at.
+
+## Labels and routes
+
+The human-readable display label is separate from the local route handle. A
+route defaults to a readable slug plus a stable node-ID suffix, so multiple
+devices reporting `localhost` still receive distinct identities.
+
+Rename an owned node from Settings or a roster; the same canonical label then
+appears everywhere without changing route, identity, credentials, Share state
+or deck identity.
+
+For a routed node the current installation does not own, Settings offers a
+local alias. That alias stays private to the viewing installation and follows
+the stable instance identity.
+
+## Private and shared state
+
+Newly joined devices are private by default. Private pairing is administrative
+inventory, not operational publication: a private client can remain listed in
+Settings while staying absent from routable topology, deck bars and MCP
+discovery.
+
+Enabling **Share this device through the selected hub** adds a verified reverse
+channel to the existing SSH process. The hub decides whether authorized peers
+see the whole network, only the hub or an explicit subset.
+
+Share is stored as desired state:
+
+- Failed activation rolls back to private.
+- Deactivation saves private intent first.
+- The hub must acknowledge withdrawal before the reverse channel is removed.
+- If acknowledgement fails, bounded boot retries reconcile the saved state
+  without claiming remote removal completed.
+
+Temporary loss of reachability does not revoke consent. An authorized node
+remains visible as stale/offline until an authoritative refresh restores it or
+confirms withdrawal.
+
+## Which cells a node may see
+
+Sharing decides whether a node is reachable. A **cell scope** decides how much
+of this installation it reaches once it is:
+
+```bash
+nexuscrew nodes cells <name|nodeId> all            # default
+nexuscrew nodes cells <name|nodeId> none
+nexuscrew nodes cells <name|nodeId> Research,Dev
+```
+
+The scope is set here, on the installation that owns the cells — never by the
+node being scoped, and never over the federation. It applies to what that node
+lists (cells, fleet status, sessions) and to what it can act on, including the
+terminal attach; a session belonging to no cell is outside every scope.
+Switching away from the explicit list clears it, so a cell revoked today does
+not come back the next time a list is set.
+
+Within its scope a node keeps full authority. Read the cell scope section of
+[Security model](SECURITY.md) before using it as a boundary against anything
+you do not trust.
+
+## Tunnel behavior
+
+NexusCrew creates one supervised private `ssh -L` process for a hub connection
+and proves the forwarded TCP endpoint before reporting success. It does not use
+`autossh` as a hidden second supervisor. A shared peer with a verified
+rotatable pool may additionally run a short-lived, per-slot reverse supervisor;
+each one has a distinct local target so the hub can prove the exact reverse
+slot it reached.
+
+Reverse ports are reserved across active and pending pairings, probed before
+use and protected by a persistent uniqueness check. A stale same-name peer or
+late collision returns an actionable conflict instead of silently consuming
+the invitation.
+
+OpenSSH restrictions still apply. A shared client may need its accepted hub key
+to allow the negotiated reverse listener:
+
+```text
+permitlisten="127.0.0.1:44002"
+```
+
+Use the exact port printed by the tunnel diagnostic.
+
+## Rotatable reverse-port pools
+
+A new shared peer receives a three-port pool with the same base and offsets
+`+100` and `+200`. Read the base this installation actually assigned — do not
+copy the one below, it is a placeholder — and grant exactly those three ports
+**on the hub**, in the `~/.ssh/authorized_keys` entry that the hub accepts from
+that device:
+
+```text
+permitlisten="127.0.0.1:<BASE>",permitlisten="127.0.0.1:<BASE+100>",permitlisten="127.0.0.1:<BASE+200>"
+```
+
+Add those options when you install or update the key. NexusCrew never writes,
+widens, removes, or otherwise edits `authorized_keys`. A legacy peer with only
+one `permitlisten` remains usable, but is reported as not rotatable until the
+operator installs its full pool.
+
+The direction is worth stating plainly, because getting it backwards sends you
+looking where nothing is wrong: **the device asks for the reverse bind, the
+hub's sshd grants or refuses it.** Nothing needs changing on the device — the
+grant lives on the hub, in the entry carrying that device's key.
+
+**Re-pairing a device changes its base.** Pool bases are monotonic and a
+removed peer retires its own, so a device paired again is assigned a new one
+while its key still carries the previous grant. Nothing warns you: the pairing
+succeeds, the private `-L` works, the device looks connected — and Share alone
+fails, because it is the only operation that needs the reverse channel. The
+symptom is `share-channel-not-ready` with HTTP 409, and no amount of re-pairing
+fixes it, because pairing is not what is broken.
+
+The hub records every refusal it issues as a `SHARE_CHANNEL_REFUSED`
+diagnostic, naming the peer, the typed failure code and **the port it probed**.
+Read it in the Diagnostics view of the PWA. Confirm the cause on the hub with
+`journalctl -u ssh` or `auth.log`:
+
+```text
+Received request ... to remote forward to host 127.0.0.1 port <BASE>, but the request was denied
+```
+
+That line names the exact port SSH policy is refusing. Grant that port on that
+key, and remove any grant pointing at a base that now belongs to another peer:
+one key must never hold a listen right on another peer's pool.
+
+Rotation is deliberately narrow:
+
+- The peer proposes a pre-authorized slot over its existing private `-L`; the
+  hub alone assigns the lease and generation.
+- Every slot is proven over a slot-specific local endpoint before automatic
+  rotation is allowed. A generic SSH failure or a missing grant stops the
+  episode after one candidate instead of consuming the pool.
+- A verified collision can switch to one ready slot at most once every ten
+  minutes. The old slot drains briefly; an unproven or unattributable listener
+  is quarantined and reported, never terminated automatically.
+- Pool bases are monotonic. Removing a peer retires its base so a key that
+  still has old `permitlisten` rights cannot claim a later peer's port.
+
+If the pool is exhausted, degraded, unverified, or not configured, NexusCrew
+does not guess a new port or change SSH policy. Correct the displayed
+`permitlisten` line, then retry Share from the device.
+
+## CLI
+
+```text
+nexuscrew nodes list [--json]
+nexuscrew nodes inspect <name|nodeId>
+nexuscrew nodes edit <name|nodeId> ...
+nexuscrew nodes test                    # every peer, plus what is only claimed
+nexuscrew nodes up|down|connect|disconnect <name|nodeId>
+nexuscrew nodes restart|reconnect <name|nodeId>
+nexuscrew nodes share <name|nodeId> on|off
+nexuscrew nodes cells <name|nodeId> all|none|Cell1,Cell2
+nexuscrew nodes remove <name|nodeId> --yes
+```
+
+Node and deck identities remain owner-qualified across the network. Routed
+HTTP and WebSocket requests recheck authorization, hop count and cycle rules.
+
+## Related guides
+
+- [Installation](INSTALLATION.md)
+- [Fleet and terminals](FLEET.md)
+- [Security](SECURITY.md)

package/docs/NOTIFICATIONS.md

@@ -0,0 +1,101 @@
+# Notifications
+
+[← Documentation index](README.md)
+
+NexusCrew can deliver live cell notifications through three independent
+surfaces:
+
+1. In-app toasts over the live event stream.
+2. Best-effort Web Push when the browser and operating system support it.
+3. Optional on-device spoken alerts while the PWA is visible and focused.
+
+## In-app and push delivery
+
+Toasts are the primary live UI signal. Web Push requires browser permission;
+on iOS it also requires an installed PWA.
+
+The service worker cannot synthesize speech. A hidden or closed PWA therefore
+uses only its normal system-notification path.
+
+Depending on the operating system, a visible toast, Web Push notification and
+spoken alert may coexist.
+
+## Spoken alerts
+
+Enable **Settings → System → Read notifications aloud**.
+
+Spoken alerts are:
+
+- off by default
+- stored as a browser-local, per-device preference
+- available even when server settings are read-only
+- synthesized by the device's browser speech engine
+- spoken in the notification's declared content language when available
+- never sent to a remote speech service
+
+For backend-delivered speech on a shared Mac, Linux host, or Termux device,
+use [Audio Share and native TTS](AUDIO_SHARE.md). It has a separate local
+consent gate and does not depend on the browser remaining foregrounded.
+
+`nc_notify` accepts an optional `lang` value for Italian, English or Spanish,
+using either a base code (`it`) or an equivalent BCP-47 locale (`it-IT`). The
+live PWA selects a matching installed voice when the browser exposes one.
+Browsers commonly report an empty voice list during startup, so NexusCrew
+refreshes its cache on `voiceschanged` and lets the browser choose until a
+matching voice is available.
+
+Notifications from older clients have no language field. For compatibility,
+NexusCrew uses a language detected from the body only when the signal is
+strong; short or mixed technical text falls back to the current UI language.
+Unknown languages leave the utterance language empty so the browser uses its
+own default rather than being forced to English.
+
+Enabling speech runs an audible preview. NexusCrew reports success only after
+the browser emits both speech start and speech end. A silent, missing or failed
+native voice reports **voice unavailable** rather than a false success.
+
+The preview must succeed once per page session, including after a reload.
+
+## Focus and privacy
+
+Speech runs only while the document is visible and has operating-system focus.
+Blur, background, opt-out and unmount cancel the current utterance and clear
+pending work. Skipped notifications are not replayed when focus returns.
+
+Focus provides one speaker among NexusCrew windows on the same device. Two
+separately opted-in devices may both speak when each PWA is visible and
+focused; this is intentional.
+
+Credential-shaped values and private home paths are redacted before speech.
+Spoken alerts do not replace the toast's accessibility status, so screen-reader
+users can keep the feature disabled if their assistive technology already
+announces notifications.
+
+## Queue behavior
+
+- Duplicate live frames are suppressed for 60 seconds.
+- At most two normal alerts remain pending.
+- A high-urgency alert interrupts the current queue.
+- A 30-second watchdog cancels a stuck browser utterance and advances.
+- Failures are isolated from the event stream and visual toast delivery.
+
+Only new live notification frames are spoken. Persisted questions and previous
+events are not replayed.
+
+## Platform notes
+
+| Platform | Expected behavior |
+|---|---|
+| Chrome / Edge desktop | System voice while the focused PWA is visible |
+| Firefox desktop | System voice where Web Speech synthesis is available |
+| Safari desktop | System voice while the page is focused |
+| Android Chrome | Visible/focused PWA can speak; background uses normal push |
+| iOS installed PWA | Visible/focused PWA can speak; lock screen relies on normal push |
+
+Browser and operating-system voice availability remains device-dependent.
+
+## Related guides
+
+- [Configuration](CONFIGURATION.md)
+- [Audio Share and native TTS](AUDIO_SHARE.md)
+- [Security](SECURITY.md)

package/docs/OPERATIONS.md

@@ -0,0 +1,114 @@
+# Operations
+
+[← Documentation index](README.md)
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `nexuscrew` | Start or reuse the background runtime and print status |
+| `nexuscrew show` | Open the authenticated PWA |
+| `nexuscrew show token` | Print the authenticated link |
+| `nexuscrew status` | Show service, port, role and node status |
+| `nexuscrew stop` | Stop NexusCrew and managed tunnels, preserving tmux |
+| `nexuscrew restart` | Restart NexusCrew and autostart links, preserving tmux |
+| `nexuscrew boot` | Enable startup persistence |
+| `nexuscrew boot off` | Disable persistence without stopping the runtime |
+| `nexuscrew doctor` | Check Node, PTY, tmux, SSH, service and platform integration |
+| `nexuscrew nodes ...` | Inspect and manage connected nodes |
+| `nexuscrew help` | Show public command help |
+| `nexuscrew version` | Show the installed version |
+
+`init`, `serve`, `fleet-boot` and `mcp` are internal entry points rather than
+the normal interactive workflow.
+
+## Boot integration
+
+| Platform | Integration |
+|---|---|
+| Linux | systemd user service |
+| macOS | per-user LaunchAgent |
+| Android / Termux | detached runtime and optional Termux:Boot script |
+
+Boot starts only cells marked `boot:true`. It is startup persistence, not a
+watchdog for the tmux server itself.
+
+Linux services use `KillMode=process` so restarting NexusCrew does not stop the
+shared tmux server. Lifecycle commands fail closed when this protection cannot
+be verified.
+
+Termux pidfiles include process identity data. If Android reuses a PID under
+another app UID, NexusCrew removes only the stale pidfile, never signals the
+foreign process, and restarts only the configured OpenSSH supervisor.
+
+## Backup and restore
+
+**Settings → Fleet** can export and restore selected cells, system prompts and
+reusable engines.
+
+Restore:
+
+- previews conflicts
+- supports per-item selection
+- reports active cells requiring restart
+- stores working directories relative to the target user's home
+- requires explicit repair for legacy or foreign absolute paths
+
+Archives contain credential variable names, never credential values, browser
+tokens or live tmux state.
+
+## Updates
+
+Global npm installs can follow stable `latest` automatically. NexusCrew:
+
+1. Serializes update attempts.
+2. Installs the selected stable version.
+3. Verifies the CLI and same-port runtime.
+4. Rolls back once to the exact previous version if health checks fail.
+
+It never installs prereleases from `latest` or silently downgrades. Use
+`NEXUSCREW_AUTO_UPDATE=0` to disable the scheduler.
+
+## Diagnostics
+
+**Settings → System → Diagnostics** shows a bounded in-memory event buffer for the
+local installation or an authorized routed node.
+
+Verbose collection is explicit and expires after 5, 15, 30 or 60 minutes.
+Operational warnings and errors remain available while verbose mode is off.
+The view supports filtering, pause, autoscroll, copy, JSON export and clear.
+
+Records are structured and redacted before storage. Raw terminal content,
+prompts, command lines, environment values, credentials and filesystem paths
+are not accepted as diagnostic metadata. Fleet launch failures expose closed
+`code` and `phase` values rather than raw stderr.
+
+## Troubleshooting
+
+- **Node older than 18** — upgrade Node before initialization.
+- **tmux missing** — install tmux and rerun `nexuscrew`.
+- **OpenSSH missing** — install `ssh`; `autossh` remains optional.
+- **systemd user service unavailable** — consider
+  `loginctl enable-linger "$USER"`.
+- **LaunchAgent failure** — inspect `nexuscrew doctor` and the user
+  `~/Library/LaunchAgents` permissions.
+- **Termux:Boot does not start** — install and open the Android app once.
+- **Voice unavailable** — distinguish browser synthesis from optional server
+  speech-to-text; see [Notifications](NOTIFICATIONS.md).
+
+## Development
+
+```bash
+npm test
+npm run build
+node bin/nexuscrew.js serve
+```
+
+Tests that exercise tmux use private sockets and must never attach to or stop
+the operator's tmux server.
+
+## Related guides
+
+- [Installation](INSTALLATION.md)
+- [Configuration](CONFIGURATION.md)
+- [Security](SECURITY.md)

package/docs/README.md

@@ -0,0 +1,55 @@
+# NexusCrew documentation
+
+[← Main README](../README.md)
+
+NexusCrew is designed around a small public entry point and focused technical
+guides. Start with installation, then open only the area you need.
+
+| Guide | Use it for |
+|---|---|
+| [Installation](INSTALLATION.md) | Platform prerequisites, first run, verification and upgrades |
+| [Fleet and terminals](FLEET.md) | Cells, engines, providers, decks, terminal input and mobile behavior |
+| [The Live per-cell prompt](LIVE_PROMPT.md) | Where `LIVE_PROMPT.md` goes, what the bridge does with it, and the ready-to-copy IT/EN/ES templates |
+| [The cell panel](CELL_PANEL.md) | A web interface next to the terminal: configuration, the loopback rule, how the frame authenticates, and granting it across nodes |
+| [Connect nodes](NODES.md) | Pairing, SSH routes, private/share state and routed aliases |
+| [Notifications](NOTIFICATIONS.md) | In-app toasts, Web Push and on-device spoken alerts |
+| [Audio Share and native TTS](AUDIO_SHARE.md) | Node-native TTS, consent, exact targets, groups and MCP commands |
+| [MCP bridge](MCP.md) | Operator tools, client configuration and cell-to-cell delivery |
+| [VL micro-device nodes](VL_MICRO_NODES.md) | Pairing, exact health, bounded management and ACK semantics |
+| [Configuration](CONFIGURATION.md) | Local paths, environment overrides and browser-local settings |
+| [Operations](OPERATIONS.md) | CLI, boot, backups, updates, diagnostics and development |
+| [Security](SECURITY.md) | Network, token, credential, file and federation boundaries |
+| [Alibaba Token Plan](ALIBABA_TOKEN_PLAN.md) | Managed Claude Code, Codex-VL and Pi profiles |
+
+Additional public references:
+
+- [MCP companions](../MCP_COMPANIONS.md)
+- [Machine-readable companion catalog](../mcp-companions.json)
+- [Changelog](../CHANGELOG.md)
+- [License](../LICENSE)
+
+## Fast paths
+
+### I want to use NexusCrew on this machine
+
+Read [Installation](INSTALLATION.md), run `nexuscrew doctor`, then open the PWA
+with `nexuscrew show`.
+
+### I want to reach another machine
+
+Read [Connect nodes](NODES.md). NexusCrew supervises OpenSSH; it does not
+replace your SSH configuration or create SSH keys.
+
+### I want to run AI CLI workers
+
+Read [Fleet and terminals](FLEET.md), then configure cells and provider
+presence in **Settings → Fleet**.
+
+### I want an AI session to contact the operator
+
+Read [MCP bridge](MCP.md) and register `nexuscrew mcp` in the client.
+
+### I want to expose NexusCrew publicly
+
+Do not. Read [Security](SECURITY.md): the supported model is loopback plus an
+SSH tunnel or VPN you control.

package/docs/SECURITY.md

@@ -0,0 +1,185 @@
+# Security model
+
+[← Documentation index](README.md)
+
+NexusCrew is local-first and fail-closed. It has no hosted control plane,
+required account or supported public-listener mode.
+
+## Network boundary
+
+NexusCrew binds only to `127.0.0.1`. Non-loopback binds are rejected.
+
+To reach a remote installation, carry its loopback port through SSH or a VPN
+you control:
+
+```bash
+ssh -L 41820:127.0.0.1:41820 user@your-host
+```
+
+Direct public exposure through a reverse proxy, public port forward or network
+bind is not supported.
+
+## Browser authentication
+
+Every API and WebSocket connection requires the local bearer token. The token
+is stored in a user-only file and passed to the browser in the URL fragment:
+
+```text
+http://127.0.0.1:41820/#token=...
+```
+
+Fragments are not sent in the initial HTTP request or written to server access
+logs. Treat the complete link as a credential and do not open it on a shared
+device.
+
+## Session and transport authority
+
+- tmux remains the session authority.
+- OpenSSH remains the network and identity authority.
+- NexusCrew supervises SSH but does not create keys or edit
+  `authorized_keys`.
+- Node and deck identities remain owner-qualified.
+- Routed HTTP and WebSocket requests recheck ACL, hop count and cycle rules.
+
+### Reverse-port recovery
+
+For a shared peer, a reverse-port pool is a fixed SSH policy boundary, not a
+permission NexusCrew can expand. The application never modifies
+`authorized_keys`; a hub operator explicitly grants the three loopback
+`permitlisten` entries for a rotatable peer.
+
+Before accepting a pool slot, the hub sends a fresh HMAC challenge to the
+specific loopback listener and verifies its instance, generation and port. The
+probe never sends the peer bearer credential to an unknown listener. A failed
+or unknown listener is quarantined for diagnosis: NexusCrew does not kill SSH
+processes or release ports it cannot prove it owns. Removed pools remain
+retired, preventing an old SSH key from binding a port reassigned to another
+peer.
+
+## Provider credentials
+
+Provider keys are resolved only on the node launching the process. NexusCrew
+can use its service environment, compatible user-owned provider files or an
+optional node-local write-only store.
+
+Credential values are excluded from:
+
+- Fleet cell and engine definitions
+- backups
+- API and status responses
+- tmux state
+- process arguments
+- temporary files
+- diagnostics and logs
+
+The PWA reports only whether a required variable is configured. Replacement
+values are transient in the browser and are written only to the selected
+node's credential store.
+
+## Files
+
+Per-session file exchange is scoped under `~/NexusFiles/<session>`. Upload and
+download operations reject traversal and symlink escapes.
+
+Clipboard images and dropped files are stored in the selected session inbox;
+their path is inserted into the terminal without automatically pressing Enter.
+
+## Pairing and sharing
+
+**Pairing grants owner-equivalent authority. Pair only devices you own.**
+
+A paired node can create tmux sessions — including a shell — attach to them over
+the federated WebSocket and write into them as the user running NexusCrew. It
+can define engines and cells, and a custom engine may name an existing
+executable with arguments of its choosing: the trust gate checks the binary's
+ownership, mode and path, not the intent of its arguments.
+
+Admission is the exception. Minting a pairing invite is not federated: an invite
+belongs to the installation that will host the new node, so it is issued there,
+locally. A paired node cannot admit a third party on your behalf.
+
+This is a deliberate boundary, not a defect list. NexusCrew was designed to put
+one person's machines on one control plane, and it treats a paired node the way
+it treats you.
+
+### Cell scope
+
+A per-node cell scope narrows what one paired node sees and can act on. It is
+set locally, on the installation that owns the cells:
+
+```bash
+nexuscrew nodes cells <node> all            # default: every cell
+nexuscrew nodes cells <node> none           # no cell at all
+nexuscrew nodes cells <node> Research,Dev   # exactly these
+```
+
+The scope is enforced on the federated request, in one place in front of the
+API router, so a listing and an action pass the same predicate. Route targets
+are declared in an explicit table rather than inferred, and a federated request
+that names a cell or a session on a route missing from that table is refused
+rather than allowed — a route added later starts closed, not open. Defining,
+editing or importing a cell is refused outright for a scoped node: it must not
+be able to create the cell it was not granted. The terminal attach is gated
+with the same predicate, and a tmux session that maps to no cell is outside
+every scope.
+
+What the scope does **not** change: the pairing itself is still
+owner-equivalent for everything it governs, and the granted cells are granted
+fully — inside its scope a node still creates sessions, attaches to them and
+writes into them as the user running NexusCrew. It attenuates reach, not the
+authority held within that reach. A capability model with proof of possession —
+authority granted, attenuated and revoked as a token rather than as
+configuration — remains on the roadmap and is not implemented.
+
+So: do not accept a pairing invite from an installation you do not own, and do
+not treat a cell scope as a sandbox for code you do not trust. It is a
+reduction of surface between machines that are already yours.
+
+Pairing links contain a short-lived one-time invite and routing data, but no
+SSH private key, provider key or PWA token.
+
+Newly paired nodes are private by default. Sharing is explicit desired state
+and uses a verified reverse channel in the supervised SSH process. Revocation
+is saved locally before the hub is asked to withdraw the node; the UI does not
+claim remote removal until acknowledgement.
+
+## Diagnostics and speech
+
+Diagnostics accept structured, bounded metadata and reject raw terminal
+content, prompts, command lines, environment values, credentials and private
+paths.
+
+Optional spoken notifications use the browser's device-local speech engine.
+Credential-shaped values and private home paths are redacted before speech;
+notification text is not sent to a speech service.
+
+Audio Share is a separate backend path for a node with a real speaker. Its
+local consent defaults to off and is independent of node Share and visibility;
+neither routing control grants permission to make sound. Calls use an
+HMAC-proven active Fleet origin, exact node IDs, target-side ACL and rate
+limits. Audio groups are local delivery preferences, never an authorization.
+See [Audio Share and native TTS](AUDIO_SHARE.md).
+
+## Updates and process safety
+
+Stable updates verify the new CLI and same-port runtime, and roll back once to
+the exact previous version on failure. tmux sessions remain outside the
+service process group.
+
+Termux process handling verifies process identity before sending a signal.
+Android PID reuse under another app UID is treated as a stale pidfile, never as
+permission to signal the foreign process.
+
+## Report a security issue
+
+Do not include live tokens, credentials, private keys or complete authenticated
+links in a public issue. Use the repository's private security-reporting
+channel when available.
+
+## Related guides
+
+- [Connect nodes](NODES.md)
+- [Configuration](CONFIGURATION.md)
+- [Notifications](NOTIFICATIONS.md)
+- [Audio Share and native TTS](AUDIO_SHARE.md)
+- [Operations](OPERATIONS.md)