@mmmbuto/nexuscrew 0.9.16 → 0.9.18

package/docs/FLEET.md

@@ -0,0 +1,222 @@
+# Fleet and terminals
+
+[← Documentation index](README.md)
+
+## Cells
+
+A **cell** is a reusable worker definition: tmux session name, working
+directory, engine, model, permission policy, optional system prompt, optional
+Shell command and boot state.
+
+Starting a stopped cell opens the same launch sheet on desktop and mobile, so
+the effective settings can be reviewed before the process starts. Cells marked
+`boot:true` are started by the platform boot integration.
+
+NexusCrew is the Fleet manager. Definitions, lifecycle, boot ownership,
+restart supervision and write-only credentials are handled by its built-in
+runtime; no external `fleet` executable is discovered or invoked.
+
+Set `NEXUSCREW_FLEET=0` to disable Fleet entirely.
+
+## Engines
+
+Clean installations include these base adapters:
+
+- Claude Code
+- Codex
+- Codex-VL
+- Pi
+- Agy on Linux and macOS
+- Kimi Code CLI
+- Shell
+
+Agy delegates authentication to its local login and supports standard or
+unsafe permission policies. On Android/Termux, use the Shell adapter with a
+per-cell `agy` command.
+
+Kimi Code CLI (`kimi.native`) runs the official `@moonshot-ai/kimi-code`
+binary directly. Authentication and providers are owned by the CLI itself
+(device-code login, `config.toml`): NexusCrew never reads, stores or injects
+Kimi credentials. The cell prompt is not passed on the command line — the CLI
+has no interactive prompt flag (`kimi -p` is non-interactive and skips the
+TUI) — so it is injected with bracketed paste after the session is ready.
+This engine is distinct from the Claude Code "Kimi Code" provider below,
+which remains the managed K3 path with an isolated Claude configuration.
+
+### Bootstrap prompt delivery (Kimi engines)
+
+For `kimi.native` and the Claude Code "Kimi Code" provider the cell prompt is
+never placed on the process command line. It is delivered to the interactive
+prompt only, at most once per process generation:
+
+- Before delivering, NexusCrew classifies the visible terminal. Login,
+  custom-API-key consent and onboarding/trust dialogs are **not ready**: no
+  text is pasted and no Enter is sent, so the prompt can never be lost behind
+  a dialog. The session stays alive and usable.
+- If the terminal is still not ready after a bounded wait, the up response
+  reports a bounded `actionRequired` code with a recovery hint. For the
+  Claude Code "Kimi Code" provider the recovery is to confirm or enable the
+  custom API key in the cell terminal (`/config` → "Use custom API key") and
+  then restart the cell — never the Anthropic `/login` flow. For `kimi.native`
+  it is the CLI's own `/login` (device code) or `/provider`.
+- Delivery itself is a single bracketed paste followed by a separate Enter,
+  targeted at the exact pane, and is owned solely by the cell's supervising
+  launcher for every process generation (the API runtime never pastes for
+  these engines; it only reads the bounded delivery outcome the launcher
+  publishes on the pane). There is no automatic retry after a paste attempt;
+  a supervised restart delivers the prompt at most once again for the new
+  process generation.
+
+MCP servers started by an AI CLI inherit that process's environment according
+to the CLI's own configuration and behavior; that inheritance is owned by the
+CLI, not by NexusCrew.
+
+Custom argv-based engines are launched directly without a shell after
+trust-boundary validation.
+
+The Shell engine resolves `$SHELL` or a trusted platform shell at start time;
+executable paths are not stored in Fleet definitions or backups. An empty
+command opens an interactive login shell. A configured command is passed as
+one opaque argument through the private launch broker, runs once without
+restart supervision and then leaves the cell stopped.
+
+## Providers
+
+Provider choices are scoped to the selected CLI:
+
+| CLI | Built-in choices |
+|---|---|
+| Claude Code | Anthropic, Alibaba Token Plan, OpenRouter, Kimi Code, Bedrock, Vertex AI, Foundry, Ollama Cloud, local Ollama, Z.AI, custom Anthropic-compatible |
+| Codex | OpenAI/ChatGPT, OpenAI API, Ollama Cloud, local Ollama, LM Studio, custom Responses endpoint |
+| Codex-VL | OpenAI/ChatGPT, OpenAI API, Alibaba Token Plan, OpenRouter, Ollama Cloud, local Ollama, LM Studio, custom Responses endpoint |
+| Pi | Native, Anthropic, OpenAI API, Alibaba Token Plan, Codex OAuth, Gemini, Copilot, OpenRouter, Ollama, DeepSeek, Z.AI, custom |
+| Kimi Code CLI | Native account via CLI login (device code); providers managed by the CLI |
+| Shell | Device-local interactive shell or one trusted per-cell command |
+
+Custom Codex-compatible endpoints use the Responses wire API; NexusCrew does
+not silently fall back to Chat Completions.
+
+OpenRouter is first-class for Claude Code and Codex-VL. Kimi Code is a separate
+Claude Code membership profile and is not interchangeable with a Moonshot
+pay-as-you-go key. It is also distinct from the native Kimi Code CLI engine:
+the provider drives Claude Code against the Kimi endpoint through the managed
+`ANTHROPIC_*` environment (K3 models, including the 1M-context profile), while
+`kimi.native` launches the official CLI with its own login and configuration.
+
+Alibaba Token Plan is available for Claude Code, Codex-VL and Pi through the
+fixed local variable `ALIBABA_CODE_API_KEY`. See
+[Alibaba Token Plan](ALIBABA_TOKEN_PLAN.md).
+
+## Credentials and permissions
+
+Permission handling is explicit:
+
+- Claude engines use standard permissions or
+  `--dangerously-skip-permissions`.
+- Codex and Codex-VL use standard permissions or
+  `--dangerously-bypass-approvals-and-sandbox`.
+- Kimi Code CLI uses standard (interactive) permissions by default; the unsafe
+  policy maps to `--yolo`, which auto-approves regular tool calls but still
+  lets the agent ask questions. The fully autonomous `--auto` mode is
+  deliberately not exposed.
+- Pi uses its native permission behavior.
+
+Provider keys are resolved on the node that launches the process. Values are
+excluded from Fleet definitions, backups, API responses, tmux state, process
+arguments, temporary files and logs.
+
+Built-in providers with a fixed variable expose a dedicated **KEY** section.
+It shows only the variable name, configured source and affected engines.
+Replacing or removing a shared key warns which engines use it.
+
+## Decks and workspaces
+
+Desktop decks place multiple live terminals in a saved tiled layout. Decks
+remain attached to the current PWA by default; `↗` detaches one into another
+browser window.
+
+Session and deck order can be changed with pointer drag-and-drop or keyboard
+controls and is saved automatically. The deck bar groups workspaces by owner
+node. Newly seen nodes start collapsed, and activity dots show current work
+without opening every group.
+
+On mobile, locations are independently collapsible and filterable by all,
+pinned, active, off or technical sessions. Managed terminals use the logical
+Fleet cell name as their visible title; tmux session and route identifiers
+remain technical context.
+
+When a mobile terminal is open, the key-bar cell control opens a bottom-left
+quick rail. Its default view contains only cells whose local or routed Fleet
+state and tmux session were freshly verified; it refreshes while open and
+checks the target again before switching. A degraded cell remains visible as a
+warning rather than disappearing. Use the explicit all-cells control for the
+complete inventory, including stopped cells.
+
+Choosing a row only selects it. Use the separate **Open cell** control to make
+the switch, so an exploratory touch cannot replace the terminal under your
+finger. Drag a row by its handle to reorder cells. That order is shared with
+the main roster and desktop sidebar, retains unmanaged tmux sessions, and
+keeps an offline cell's position for when it becomes active again.
+
+## Terminal behavior
+
+Terminal attachment uses `tmux attach -f ignore-size` by default, so a phone or
+narrow browser cannot resize a session held by another terminal client.
+
+Mobile controls expose:
+
+- copy-mode scrolling
+- window and pane navigation
+- Escape, Ctrl-C, Enter, Page Up and Page Down
+- detach
+- compact or two-row key layouts
+- speech-to-text where supported
+- expandable per-cell prompt composer
+
+Long text and multiline prompts use bracketed paste. Clipboard images and
+dropped files are stored in the selected session inbox; their paths are
+inserted without submitting Enter.
+
+New sessions created by NexusCrew disable the tmux alternate screen by default.
+Full-screen TUI output therefore remains in tmux history, so mobile finger
+drags and normal terminal scrolling can browse it. Set `alternateScreen: true`
+in the local NexusCrew config (or `NEXUSCREW_ALTERNATE_SCREEN=1`) to restore the
+standard tmux behavior for future sessions created through Fleet. Existing and unmanaged
+sessions are unchanged.
+
+Desktop wheel events always browse tmux history, including in writable TUIs
+that use the alternate screen and while Shift is held. Keep a user-owned tmux
+`history-limit` of at least 10000; `nexuscrew doctor` diagnoses a lower value
+without changing it.
+
+Each owner-qualified cell keeps its own browser-local draft, composer size and
+bounded prompt history. That state is not federated or included in Fleet
+backups.
+
+## Bundled skills
+
+The package ships portable skills, and
+[`nexuscrew`](../skills/nexuscrew/SKILL.md) is the one to read first: it
+describes the whole system, what an AI agent can do through it, and the rules
+that hold across every other skill.
+
+Two extend Fleet itself: [`live`](../skills/live/SKILL.md) covers designating
+and permitting a node's Live host cell, plus the
+[per-cell voice prompt](LIVE_PROMPT.md) it reads once a session lands, and
+[`aidesktop`](../skills/aidesktop/SKILL.md) covers a cell's web panel together
+with the AI Desktop container recipe. The rest cover one capability each — the
+operator channel ([`nexuscrew-agent`](../skills/nexuscrew-agent/SKILL.md)) and
+the optional MCP companions listed in
+[`mcp-companions.json`](../mcp-companions.json):
+[`memory`](../skills/memory/SKILL.md),
+[`vl-msa`](../skills/vl-msa/SKILL.md),
+[`crew`](../skills/crew/SKILL.md) and
+[`mail-assistant`](../skills/mail-assistant/SKILL.md). The companions are
+separate servers: absent unless installed, and never installed silently.
+
+## Related guides
+
+- [Configuration](CONFIGURATION.md)
+- [Connect nodes](NODES.md)
+- [Notifications](NOTIFICATIONS.md)
+- [Security](SECURITY.md)

package/docs/INSTALLATION.md

@@ -0,0 +1,128 @@
+# Installation
+
+[← Documentation index](README.md)
+
+## Requirements
+
+- Node.js 18 or newer
+- tmux 3.4 or newer
+- OpenSSH client (`ssh`)
+- Linux x64/ARM64, macOS x64/ARM64, or Android ARM64 through Termux
+
+NexusCrew ships scriptless PTY prebuilds for the supported targets. A normal
+global install does not need a compiler or native install-script approval.
+
+## Linux
+
+Install Node.js, tmux and OpenSSH with your distribution package manager, then:
+
+```bash
+npm install -g @mmmbuto/nexuscrew
+nexuscrew
+```
+
+NexusCrew uses a systemd user service when it is available. If user services
+cannot survive logout, enable lingering for your account:
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+## macOS
+
+```bash
+brew install node tmux
+npm install -g @mmmbuto/nexuscrew
+nexuscrew
+```
+
+NexusCrew installs a per-user LaunchAgent. It does not require a system daemon.
+
+## Android / Termux
+
+```bash
+pkg update
+pkg install nodejs-lts tmux openssh
+npm install -g @mmmbuto/nexuscrew
+nexuscrew
+```
+
+Optional boot persistence uses the Termux:Boot app. Install and open that app
+once before enabling boot from NexusCrew.
+
+On Android, `nexuscrew doctor` also verifies the Termux execution bridge.
+NexusCrew carries forward only a validated `libtermux-exec` preload from the
+active Termux prefix. Package upgrades repair enabled Termux:Boot scripts so
+they do not launch from a replaceable npm directory.
+
+## First run
+
+The first `nexuscrew` command:
+
+1. Creates the local configuration and bearer token.
+2. Selects a free loopback port, preferring `41820`.
+3. Installs the platform background integration.
+4. Starts NexusCrew without replacing or stopping tmux.
+5. Opens the authenticated PWA and setup wizard.
+
+Later runs reuse the configured service, print a compact status and exit.
+
+Use `nexuscrew show` to open the PWA again, or `nexuscrew show token` to print
+the authenticated link without opening a browser.
+
+## Verify
+
+```bash
+nexuscrew status
+nexuscrew doctor
+nexuscrew version
+```
+
+A missing OpenSSH client is a blocking diagnostic. `autossh` is optional;
+NexusCrew supervises OpenSSH directly.
+
+## Remote access
+
+NexusCrew listens only on loopback. Bring the remote loopback port to your
+device through SSH or a VPN you control:
+
+```bash
+ssh -L 41820:127.0.0.1:41820 user@your-host
+```
+
+Use the port shown by `nexuscrew status`, then open the link returned by
+`nexuscrew show token`. Do not expose NexusCrew through a public listener.
+
+## Update
+
+```bash
+npm install -g @mmmbuto/nexuscrew@latest
+nexuscrew restart
+nexuscrew doctor
+```
+
+The built-in updater can follow the stable npm `latest` tag automatically. It
+serializes updates, verifies the new CLI and same-port runtime, and rolls back
+once to the exact previous version if health checks fail. Disable its scheduler
+with `NEXUSCREW_AUTO_UPDATE=0`.
+
+## Install from source
+
+Use a release tag rather than a moving branch:
+
+```bash
+git clone https://github.com/DioNanos/nexuscrew.git
+cd nexuscrew
+git checkout vX.Y.Z
+npm ci --omit=dev
+node bin/nexuscrew.js
+```
+
+The repository includes the prebuilt frontend in `frontend/dist`. Rebuilding
+the PWA is only needed for development.
+
+## Next
+
+- [Configure the runtime](CONFIGURATION.md)
+- [Connect another node](NODES.md)
+- [Learn the operational CLI](OPERATIONS.md)

package/docs/LIVE_PROMPT.md

@@ -0,0 +1,110 @@
+# The Live per-cell prompt
+
+[← Documentation index](README.md)
+
+When Live starts a native session (engine `codex-vl*`), the bridge
+(`lib/live-host/bridge.js`) always sends `thread/start` a `developerInstructions`
+field that opens with an identity header — which cell it is attached to, and
+the exact tmux session the roster reports for it — and, if a per-cell prompt
+file exists, appends its text after a blank line. How the app-server
+combines that field with its other configured instructions is not
+established here — a separate verification of that consumer is in progress.
+This page is about the template file itself: what it must contain, exactly
+where it goes, and how to prove the bridge actually reads it. For the Live
+host designation itself (which cell a node's Live session lands on), see
+[`live`](../skills/live/SKILL.md).
+
+## Where the file goes
+
+```
+<NexusFiles>/<tmuxSession>/LIVE_PROMPT.md
+```
+
+- `<NexusFiles>` is the `filesRoot` NexusCrew resolves for the node running
+  the bridge — `~/NexusFiles` unless overridden by configuration. This is
+  the node's own home, not a remote peer's.
+- `<tmuxSession>` is the **exact tmux session name the Fleet roster reports**
+  for the designated cell (`cell.tmuxSession` in fleet status / `nc_cells`)
+  — the same value the bridge puts in the identity header, not a name
+  reconstructed from a device prefix. On a device whose sessions are named
+  `cloud-*` this is `cloud-<Cell>`; on a device using a different prefix (or
+  none) it is whatever that device actually calls the session. There is no
+  fixed prefix to guess: **until 2026-08-16 the bridge assumed `cloud-` as a
+  universal default, and on any device using a different prefix the prompt
+  was never found** — this page described that assumption as the contract
+  before it was understood to be the bug.
+- If the roster does not report a `tmuxSession` for the cell at all, the
+  bridge does not construct a path from the cell name as a fallback — see
+  "What the bridge does with it" below for what happens instead.
+
+To install a template: copy one of the files in
+[`live-prompt-templates/`](live-prompt-templates/) into that session's
+NexusFiles folder, next to that cell's `PROMPT.md` and `ACTIVE_WORK.md`, and
+rename it to `LIVE_PROMPT.md`. Nothing in the file needs editing — it never
+names the cell or the operator; the voice discovers both at runtime through
+`nc_identity`/`nc_cells`, exactly as the file tells it to.
+
+## What the bridge does with it
+
+`readCellPrompt(filesRoot, tmuxSession)` has four distinct outcomes. The
+distinction matters for anyone debugging why a Live session sounds
+unbriefed — "I don't even know where to look," "I looked and it's not
+there," and "it's there but useless" point to different fixes:
+
+| Outcome | Cause | What happens |
+|---|---|---|
+| `applied: true` | file exists, reads, non-empty after trim | its text is appended to the identity header, separated by a blank line |
+| `applied: false`, `reason: "session-unknown"` | the roster does not report a `tmuxSession` for this cell | no path is built at all — never a guess from the cell name; only the identity header (cell name, no session) is sent |
+| `applied: false`, `reason: "missing"` | the session is known, but no such file exists there (`ENOENT`) | legitimate absence — the identity header still ships, no per-cell prompt is appended, no error |
+| `applied: false`, `reason: "unreadable"` or `"empty"` | file exists but can't be read, or is blank/whitespace-only | almost certainly a mistake — worth fixing, not silent |
+
+Three things this table implies:
+
+- A missing file is not a bug. Not every cell needs one.
+- `session-unknown` is not the same failure as `missing`, and collapsing them
+  is exactly how the prefix bug hid: every session on a non-`cloud-` device
+  looked "missing" when the real cause was "never looked, wrong assumed
+  path." If this ever shows up in practice, it means the roster isn't
+  reporting a tmux session for an active cell — worth investigating on its
+  own, not something to silently fall back from.
+- An unreadable or empty file is very likely a mistake: something is there,
+  and it is not doing what its presence suggests.
+
+## Engine scope
+
+The prompt only ever reaches a **native** Live session — engine
+`codex-vl*`, where the bridge opens its own thread on the app-server's
+control socket and can pass `developerInstructions` directly. For any other
+engine the bridge runs in **tmux mode**: no thread is opened, no
+instructions are passed, and the response reports `prompt: { applied:
+false, reason: "tmux-mode" }` even if a `LIVE_PROMPT.md` file is sitting
+right there, correctly placed and readable. Placing the file for a
+non-`codex-vl` cell is not wrong, it simply has no effect yet.
+
+## Verifying it's not just a plausible story
+
+The bridge's own test suite (`tests/live-host-bridge.test.js`) builds the
+real bridge against a real HTTP hub and a real WebSocket daemon, writes a
+`LIVE_PROMPT.md` file to disk at the exact path this page describes, and
+asserts on what the fake app-server actually *received* on the wire — not on
+what the code merely appears to do reading it top to bottom. Two tests are
+the pattern to extend if this contract ever changes:
+
+- `'NATIVA con cella OCCUPATA...'` — the ordinary case, file found and
+  applied, identity header followed by the prompt text.
+- `'BUG prefisso: un device con prefisso diverso da cloud- deve trovare
+  comunque il prompt'` — a device whose sessions are named `macair-*`: the
+  file is written under that exact session name, not under `cloud-`, and the
+  bridge is expected to find it there. This is the test that would have
+  caught the original bug — it fails against the pre-fix bridge and passes
+  against the current one, with a sibling test pinning that the `cloud-`
+  case does not regress.
+
+## See also
+
+- [`live-prompt-templates/`](live-prompt-templates/) — the three template
+  files (Italian, English, Spanish).
+- [`live`](../skills/live/SKILL.md) — designating and permitting a node's
+  Live host cell.
+- [Fleet and terminals](FLEET.md) — what Live is and how a host cell is
+  chosen.

package/docs/MCP.md

@@ -0,0 +1,151 @@
+# MCP bridge
+
+[← Documentation index](README.md)
+
+`nexuscrew mcp` exposes the local authenticated runtime as a dependency-free
+stdio MCP server. It is intended for AI sessions running inside managed tmux
+cells.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `nc_notify` | Send a PWA notification, optionally declaring its text language |
+| `nc_ask` | Ask a non-blocking question and return the answer to the caller |
+| `nc_send_file` | Place a caller-owned file in the downloadable outbox |
+| `nc_status` | Read live tmux and Fleet status |
+| `nc_inbox` | List files received by the caller |
+| `nc_deck` | Discover owner-qualified decks containing the caller |
+| `nc_cells` | List authorized Fleet cells across visible nodes |
+| `nc_cell_diagnostics` | Read redacted launch state for one exact local cell |
+| `nc_send_cell` | Submit bounded text to one exact active cell |
+| `nc_vl_nodes` | List authorized owner-qualified VL micro-device nodes |
+| `nc_vl_invite` | Create a one-time invite on one exact owner |
+| `nc_vl_command` | Deliver a bounded command to one online VL node |
+| `nc_vl_revoke` | Explicitly revoke one exact VL pairing |
+| `nc_identity` | Diagnose caller identity without reading a token |
+| `nc_speak` | Speak a bounded utterance on one exact authorized node ID |
+| `nc_speak_status` | Read a caller-scoped exact-target audio receipt |
+| `nc_speak_stop` | Stop a caller-owned exact-target utterance |
+| `nc_speak_group` | Start a local named primary/failover or explicit fan-out group |
+| `nc_speak_group_status` | Read a caller-scoped per-endpoint group receipt |
+| `nc_speak_group_stop` | Stop a group and prevent untried failover candidates |
+
+Cell delivery uses bracketed paste followed by a separate Enter. A `submitted`
+receipt confirms transport to the target TUI, not acceptance or completion by
+its model. There is no silent offline queue.
+
+### Notification language
+
+`nc_notify` accepts `title`, optional `body`, optional `urgency`, and optional
+`lang`. Use `lang` whenever the text language is known so an opted-in,
+visible/focused PWA can select the correct on-device speech voice:
+
+```json
+{
+  "title": "Release completata",
+  "body": "Correzione verificata e pubblicata con tutti i test verdi.",
+  "lang": "it"
+}
+```
+
+Accepted base languages are `it`, `en` and `es`; equivalent BCP-47 forms such
+as `it-IT` are normalized. Omitting `lang` remains backward compatible.
+
+## Claude Code
+
+```json
+{
+  "mcpServers": {
+    "nexuscrew": {
+      "command": "nexuscrew",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## Codex and Codex-VL
+
+These clients launch MCP stdio processes with a cleared environment. Allowlist
+the identity variable names; do not copy values into the config:
+
+```toml
+[mcp_servers.nexuscrew]
+command = "nexuscrew"
+args = ["mcp"]
+env_vars = ["NEXUSCREW_MCP_SESSION", "TMUX", "TMUX_PANE"]
+```
+
+Equivalent Codex-VL CLI form:
+
+```text
+codex-vl mcp add nexuscrew \
+  --env-var NEXUSCREW_MCP_SESSION \
+  --env-var TMUX \
+  --env-var TMUX_PANE \
+  -- nexuscrew mcp
+```
+
+## Caller identity
+
+The caller is resolved in this order:
+
+1. Current tmux session.
+2. `NEXUSCREW_MCP_SESSION`.
+3. Missing identity.
+
+Without identity, gated tools fail closed with a stable
+`NEXUSCREW_MCP_IDENTITY_*` code. `nc_notify` degrades to an unknown sender.
+
+`nc_identity` returns only:
+
+- resolution source (`tmux`, environment fallback or missing)
+- boolean presence of identity variables
+- stable status code
+- remediation hint
+
+It never calls the HTTP API or reads the bearer token.
+
+`nc_cell_diagnostics` accepts an exact owner-qualified ID returned by
+`nc_cells`, only when the target belongs to the local node and the caller is an
+active local Fleet cell. Its command and failure information are bounded and
+credential-redacted.
+
+VL mutation tools likewise require an active local Fleet caller. Use
+`nc_vl_nodes` immediately before mutation and the full owner-qualified target.
+`nc_vl_command` receipts are transport-only until `lastAck` carries the same
+ID. See [VL micro-device nodes](VL_MICRO_NODES.md).
+
+### Audio Share
+
+Audio tools require an active local Fleet cell and an HMAC-signed bridge
+request. The target node independently enforces its own audio consent, ACL,
+`READONLY`, rate limit, and native capability. A successful adapter start is
+reported as `spoken`; it is not proof of physical audibility. See
+[Audio Share and native TTS](AUDIO_SHARE.md) for exact-target and group
+semantics.
+
+## Optional companions
+
+NexusCrew can work alongside separate local-first MCP servers for:
+
+- durable structured memory
+- searchable document memory
+- bounded worker delegation
+- mail access
+
+They are optional projects, not hidden NexusCrew dependencies. Discover
+existing tools first and ask before installing software, changing MCP
+configuration or requesting credentials.
+
+See [MCP_COMPANIONS.md](../MCP_COMPANIONS.md) and
+[`mcp-companions.json`](../mcp-companions.json).
+
+## Related guides
+
+- [Fleet and terminals](FLEET.md)
+- [Connect nodes](NODES.md)
+- [Audio Share and native TTS](AUDIO_SHARE.md)
+- [VL micro-device nodes](VL_MICRO_NODES.md)
+- [Security](SECURITY.md)