@mmmbuto/nexuscrew 0.8.58 → 0.9.1

package/skills/aidesktop/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: aidesktop
+description: Use when a user wants to give a cell a web panel via panelUrl, asks why a panel URL or panel request was rejected, wants to build the AI Desktop container recipe for an isolated browser and desktop, or needs to connect a Playwright MCP client to that desktop's Chromium through its CDP relay.
+---
+
+# AI Desktop
+
+A desktop you can watch and a browser you can drive are two faces of the same
+container: watching it is the **panel**, driving it is the **CDP relay** a
+Playwright MCP client attaches to. This skill covers both together, plus the
+recipe that builds the container itself.
+
+## The panel
+
+`panelUrl` is a **property of the cell** (or its engine, as a default for
+every cell using it) — a sibling of `engine` and `cwd`, not a command and not
+something the cell runs. The app's cell/engine editor has a `panelUrl` field
+for this; do not write the URL into the command field, which makes the cell
+try to execute it as a program and fails to start, while no panel button
+appears either, since `panelUrl` was never actually set.
+
+The value must be an `http:`/`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, just without a panel button.
+**A container's own address is not loopback** — publish its port to
+`127.0.0.1` on the host that runs the node, and point `panelUrl` there. This
+is not a nitpick: the forwarder resolves *which cell*, never *where to
+connect*, so allowing a non-loopback destination would turn it into a way to
+reach any address the node can reach. See
+[The cell panel](../../docs/CELL_PANEL.md) for the full explanation and the
+worked example.
+
+### Origin separation (0.9.1)
+
+The panel used to be served from the same origin as the control plane, which
+meant a compromised or hostile page mounted in the panel iframe could, in
+principle, read the operator's token straight out of the app's own
+`localStorage`. As of 0.9.1, the panel is served from a **second loopback
+port** — the browser's Same-Origin Policy treats a different port as a
+different origin, so a document in that frame has nothing of the control
+plane's to read or write. The app also sends
+`Content-Security-Policy: frame-ancestors` on its own page, which is a
+separate, orthogonal protection: it stops the app itself from being embedded
+as someone else's iframe.
+
+This covers **remote** cells too, not just local ones. Two paired nodes
+negotiate a second port pair the same way they already negotiate the control
+plane's own tunnel: when the hub side has a panel server running, it
+announces its panel port at join time, the joining side reserves a local port
+for it, and the supervisor forwards both destinations over the same SSH
+connection — one `-L` for control, one for the panel, never sharing a port.
+`GET /api/config` exposes the result as `nodePanelPorts` (node name → the
+locally forwarded port), and the app resolves the right one per cell from its
+route before ever opening the frame.
+
+A node with no port pair on record — paired **before** this existed, or
+paired since but with the local port reservation having failed at the time
+(pairing still succeeds; the port pair is treated as an extension, never a
+reason to fail the bond) — is not treated as an error either way: its cells
+fall back to the old federated path (same origin as the control plane)
+exactly as before, and a cell never borrows another node's port to paper over
+the gap — the absence stays visible as the old behavior, not a silent, wrong
+origin. The pair is only established at pairing time, not by reconnecting an
+existing tunnel; re-pair the node to pick one up.
+
+None of this changes how a request actually gets into the frame: an
+authenticated call asks for a one-use ticket bound to one cell, the frame's
+first request spends it and receives a viewing cookie scoped to that cell's
+panel path, and the app's own token never reaches the frame. See
+[How the browser gets in](../../docs/CELL_PANEL.md#how-the-browser-gets-in)
+for the full mechanism — it is unchanged by the port move, only relocated.
+
+### Panels on another node
+
+Opening a panel that lives on a paired node needs that node's permission,
+**granted there, never by the requester**:
+
+```bash
+nexuscrew nodes panel <node> on
+```
+
+Denied by default. Without it, the rejection names itself —
+`panel-not-granted` — instead of leaving a blank rectangle to debug.
+
+## The Docker recipe
+
+**This repository ships the recipe, not an image.** The base,
+`lscr.io/linuxserver/webtop`, is GPL-3.0; a `FROM` line pointing at its public
+source is a recipe, not a distributed derivative, and the only thing this
+project actually owns is the two added lines below and their reasons. It also
+means no registry to host, nothing to keep patched on your behalf, and a
+recipe you can read before you run it.
+
+Build it yourself from [`docker/`](docker/):
+
+```bash
+cd <skill-dir>/docker
+cp docker-compose.example.yml docker-compose.yml
+# create ./.gui_password yourself — see the comments in the compose file
+docker compose up -d --build
+```
+
+First start creates an **empty** browser profile: no logins, no history,
+nothing carried over. The example compose ships no branding and no
+pre-populated `/config` — you get a bare webtop desktop plus the two
+additions below.
+
+### The two additions, and why each exists
+
+- **`socat`** — modern Chrome ignores `--remote-debugging-address` and binds
+  its DevTools/CDP port to `127.0.0.1` *inside* the container, so a Docker
+  port mapping alone never reaches it. `socat` relays
+  `0.0.0.0:9223 -> 127.0.0.1:9222` inside the container's own network
+  namespace; the published host port still only opens on `127.0.0.1`, so the
+  loopback-only rule is unchanged — nothing new is exposed, only bridged.
+- **the init script** also clears `Singleton{Lock,Cookie,Socket}` files an
+  unclean shutdown leaves behind, which otherwise stop Chromium from starting
+  again with no visible error.
+
+Notably absent: anything that tries to sandbox the browser. That is the next
+section, and it is the part worth reading before you adapt this recipe.
+
+### Where the boundary is
+
+**The browser in this container runs with `--no-sandbox`, and this recipe
+keeps it that way.** That is a trade, made deliberately, and you should
+understand it before deciding whether it fits your situation.
+
+The base image launches Chromium through `/usr/local/bin/wrapped-chromium`,
+which hardcodes the flag:
+
+```
+${BIN} --password-store=basic --no-sandbox --test-type "$@"
+```
+
+Installing Chromium's setuid helper does not change this, and overriding the
+wrapper to drop the flag does not produce a sandbox either. Measured inside a
+running container, launching the browser without it aborts:
+
+```
+The setuid sandbox is not running as root. Common causes:
+  * A parent process set prctl(PR_SET_NO_NEW_PRIVS, ...)
+Failed to move to new namespace: PID namespaces supported,
+Network namespace supported, but failed: errno = Operation not permitted
+```
+
+Both routes are closed, and for opposite reasons. The **setuid** sandbox needs
+its helper to elevate, which `no-new-privileges` exists to prevent. The
+**namespace** sandbox needs unprivileged user namespaces, which the container
+denies. Opening either one means handing the container `CAP_SYS_ADMIN` or
+`seccomp=unconfined`.
+
+That is the trade: **you would weaken the boundary that is actually holding in
+order to build one inside it.** For a desktop reachable only over loopback,
+the container is the stronger of the two — so the recipe keeps the container
+hard and accepts the browser soft. `no-new-privileges` stays on.
+
+**What this costs you, stated plainly:** a renderer exploit lands in the
+container. Everything the browser can reach is in the blast radius — its
+profile, its logged-in sessions, and anything you mount. Mount as little as
+possible, keep the published ports on loopback, and do not treat this desktop
+as isolation between *sites*: it is isolation between the desktop and the
+host.
+
+**If your situation differs** — an untrusted desktop, or a host where the
+container boundary matters less than the browser one — the inverse trade is
+legitimate: grant `seccomp=unconfined`, override the wrapper, and verify you
+actually got a sandbox rather than assuming it. Check the running process, not
+the launch log:
+
+- open `chrome://sandbox` inside the desktop and read what it reports, or
+- confirm the zygote no longer carries `--no-sandbox` (`ps -eo args | grep zygote`).
+
+Until one of those confirms it, assume the browser is unsandboxed — which,
+with this recipe as shipped, it is.
+### Commanding the browser
+
+The relay's published port, `127.0.0.1:9222` on the host, is the CDP
+endpoint a Playwright MCP client attaches to — for example:
+
+```bash
+playwright-mcp --cdp-endpoint http://127.0.0.1:9222
+```
+
+Register that command as its own MCP server in the AI client's configuration;
+NexusCrew does not bundle browser automation itself, it only gives the
+container a loopback CDP port to attach one to. It is the same Chromium the
+panel shows over the desktop, so it carries the same logins — treat driving
+it with the same care as watching it.
+
+## Dependencies
+
+**Bundled:** the `docker/` recipe (`Dockerfile`, `docker-compose.example.yml`,
+`custom-cont-init.d/10-cdp-relay.sh`) ships with this skill.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| Docker with Compose v2 | your platform's Docker install | `docker compose version` fails → nothing in `docker/` builds or runs |
+| A Playwright-capable MCP client, to drive the browser | install separately, point it at the CDP port | if no such client is registered, no `browser_*`-style tools exist in that session — the desktop and its panel still work without it |

package/skills/aidesktop/docker/Dockerfile

@@ -0,0 +1,21 @@
+# AI Desktop = a webtop base plus the one thing the base is missing: a way to
+# reach Chrome DevTools Protocol from outside the container.
+#
+# WHAT THIS IMAGE DELIBERATELY DOES NOT DO
+# It does not try to give the browser its own sandbox. That is a decision, not
+# an omission, and it was made after measuring — see ../SKILL.md, "Where the
+# boundary is". In short: inside this container the browser's own sandbox
+# cannot start (setuid helper blocked by no-new-privileges, unprivileged user
+# namespaces denied), and the changes that would let it start are exactly the
+# ones that weaken the container — the boundary that actually holds here.
+FROM lscr.io/linuxserver/webtop:debian-xfce
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends socat \
+ && rm -rf /var/lib/apt/lists/*
+
+# socat: modern Chrome IGNORES --remote-debugging-address and binds CDP to
+# 127.0.0.1 inside the container, so a Docker port mapping alone never
+# reaches it. The relay 0.0.0.0:9223 -> 127.0.0.1:9222 is the only bridge,
+# and it still only leaves the container through a port you publish to the
+# host's own loopback (see docker-compose.example.yml).

package/skills/aidesktop/docker/custom-cont-init.d/10-cdp-relay.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Runs at every container start, as root, BEFORE the desktop session starts.
+#
+# 1) Orphaned profile locks: if the container dies while Chromium is still
+#    running, Singleton{Lock,Cookie,Socket} files are left behind pointing at
+#    a dead pid, and Chromium then REFUSES to start on the next boot.
+#    Observed symptom: autostart present, zero processes, no visible error.
+#    It is safe to remove them here: the desktop session has not started yet,
+#    so no browser can possibly be alive.
+rm -f /config/browser-profile/Singleton* 2>/dev/null || true
+
+# 2) CDP relay: modern Chrome ignores --remote-debugging-address and binds
+#    DevTools to 127.0.0.1 inside the container, unreachable through a Docker
+#    port mapping. socat bridges it. What leaves the container through this
+#    port still only reaches the host's own loopback — see the port mapping
+#    in docker-compose.example.yml.
+pkill -f "TCP-LISTEN:9223" 2>/dev/null || true
+nohup socat TCP-LISTEN:9223,fork,reuseaddr TCP:127.0.0.1:9222 >/dev/null 2>&1 &
+
+echo "[cdp-relay] stale profile locks cleared; socat 9223 -> 9222 started"

package/skills/aidesktop/docker/docker-compose.example.yml

@@ -0,0 +1,75 @@
+# Example compose for the AI Desktop recipe. Copy this next to the Dockerfile
+# and custom-cont-init.d/, adjust the marked values, then:
+#
+#   docker compose up -d --build
+#
+# First start creates an EMPTY browser profile under ./config — no logins,
+# no history, nothing carried over from anywhere else. Expect a self-signed
+# certificate warning on the HTTPS port on first connect: normal for a
+# loopback-only service, and safe to trust locally.
+services:
+  ai-desktop:
+    build: .
+    image: ai-desktop:local
+    container_name: ai-desktop
+    restart: unless-stopped
+
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Etc/UTC                    # set your own timezone
+      - TITLE=AI Desktop
+      # GUI login: without a password, anyone who reaches the port gets a
+      # terminal with passwordless sudo INSIDE the container. Create your own
+      # ./.gui_password file (mode 600, one line, no trailing newline needed)
+      # before the first start — do not put the password in this file.
+      - CUSTOM_USER=admin              # set your own login name
+      - FILE__PASSWORD=/run/gui_password
+
+    volumes:
+      - ./config:/config
+      - ./.gui_password:/run/gui_password:ro
+      - ./custom-cont-init.d:/custom-cont-init.d:ro
+
+    # Loopback only, like everything else in NexusCrew: reach this from
+    # elsewhere through an SSH tunnel or VPN you control, never by publishing
+    # these ports beyond 127.0.0.1.
+    # 6900 = http, 6901 = https. The https port is the one worth using day to
+    # day — full desktop features (clipboard, audio/video codecs) need it.
+    ports:
+      - "127.0.0.1:6900:3000"
+      - "127.0.0.1:6901:3001"
+      # CDP of the Chromium running on the desktop: the channel a Playwright
+      # MCP client attaches to (see SKILL.md). Same browser you see and use
+      # over the desktop, so same logins.
+      - "127.0.0.1:9222:9223"
+
+    # Chromium crashes on tab open without adequate /dev/shm.
+    shm_size: "1gb"
+    mem_limit: 4g               # tune to your machine
+    mem_reservation: 1g
+    cpus: 2.0
+
+    # KEEP THIS. The container is the boundary that holds here, and this line
+    # is part of it. The browser inside runs with --no-sandbox — that is not
+    # an accident, it is the trade this image makes: giving Chromium its own
+    # sandbox would require handing the container CAP_SYS_ADMIN or
+    # seccomp=unconfined, weakening the one boundary that is actually doing
+    # the work in order to add one inside it.
+    #
+    # Measured, not assumed: with this line set, launching the browser without
+    # --no-sandbox aborts — the setuid helper cannot elevate (PR_SET_NO_NEW_PRIVS)
+    # and the namespace sandbox is denied ("failed to move to new namespace:
+    # Operation not permitted"). See ../SKILL.md, "Where the boundary is".
+    #
+    # The consequence is real and you should plan for it: a renderer exploit
+    # lands in this container. Treat what the browser can reach — its profile,
+    # its sessions, anything you mount — as being inside the blast radius.
+    security_opt:
+      - no-new-privileges:true
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"

package/skills/crew/SKILL.md

@@ -87,3 +87,18 @@ report.
 
 Transport receipts do not prove task acceptance or completion. Report only
 results that have been verified.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A Crew MCP fabric (companion) | optional companion `mcp-crewd-rs`: <https://github.com/DioNanos/mcp-crewd-rs> — the repository's Install section is authoritative and may change; this skill deliberately does not duplicate its commands (**not verified here**) | if the companion is not registered, the client exposes no `cell_*` tools; ask the client for its tool list |
+| Client MCP registration | register the companion's stdio command in the AI client's MCP config | same failure mode: absent tools, not a runtime error |
+| A `crew` token issued by the fabric | `crew token issue` on the host that runs the fabric (see the companion's docs) | spawns are rejected as unauthorized — the rejection names the missing authorization |
+
+Without the companion there is no worker delegation in that session: say so
+and suggest the companion once instead of emulating cells with raw tmux.

package/skills/live/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: live
+description: Use when a user wants to know or change which cell is the Live host on a node, asks why a Live host designation was rejected, or needs to grant or revoke another node's permission to designate a Live host cell on this one (liveHostAccess, via nexuscrew nodes live-host).
+---
+
+# Live host cell
+
+Live is the phone-facing quick-open flow: a single **host cell**, designated
+per node, is what a Live session lands on. See
+[Fleet and terminals](../../docs/FLEET.md) for what Live is; this skill covers
+designating it, clearing it, and permitting it across nodes.
+
+## One host cell per node, guarded by a revision
+
+Each node keeps exactly one `hostCell` (or none). Changing it is a
+compare-and-swap on a `revision` number, never an unconditional write:
+
+1. `GET .../live-host` returns `{ hostCell, revision, eligible, host: { lease } }`.
+2. `POST .../live-host/designate { cellId, expectedRevision }` — `expectedRevision`
+   must be the value just read. A stale revision (someone else changed the
+   designation meanwhile) is rejected with 409, not silently overwritten.
+3. `POST .../live-host/clear { expectedRevision }` — same rule, removes the
+   designation.
+
+Always re-read the revision immediately before writing; never reuse one from
+an earlier render. This is what keeps two people (or two tabs) racing to star
+a cell from leaving the store in a mixed state — one write wins, the other
+gets a 409 and re-reads.
+
+The designation survives the cell going inactive; it is never dropped just
+because tmux is not attached right now. `eligible` is computed fresh on every
+read from the roster and the designated cell's lease state
+(`live`/`grace`/`expired`/`none`/`unavailable`) — a designated-but-not-eligible
+host is a distinct, readable state, not an error to explain away.
+
+## Command the node that owns the cell, not the one serving the page
+
+This is the point of the feature: **the request must reach the node whose
+roster contains the cell**, not whichever node happens to be rendering the
+current page. Route it exactly like a federated deck — an empty route for a
+local cell, that node's route array for a remote one:
+
+```js
+getLiveHost(token, route)                                   // route: [] or [...hops]
+designateHostCell(token, cellId, expectedRevision, route)
+clearHostCell(token, expectedRevision, route)
+```
+
+Before 0.9.1 these calls took no `route`, so starring a cell shown from a
+remote node either did nothing or silently changed the wrong node's
+designation. That mismatch — not a missing capability — was the defect: a
+parameter nobody passed does not exist.
+
+## Federated permission: liveHostAccess
+
+A peer may designate or read another node's Live host only if that node has
+granted it. The permission is per peer, **denied by default**, and granted by
+the node that **owns** the cell — never by the one asking:
+
+```bash
+nexuscrew nodes live-host <node> on
+nexuscrew nodes live-host <node> off
+```
+
+Without it, the request gets a **named** rejection, not a timeout or a star
+that quietly does nothing: HTTP 403 with `reason: "live-host-not-granted"`.
+Surface this distinctly from a generic failure — the fix is a grant on the
+owning node, not a retry from the requester.
+
+## Common mistakes
+
+- **Reusing a stale `revision`.** `GET` immediately before every
+  `designate`/`clear`; a revision read earlier in the session is stale by
+  definition once anything else has changed the designation.
+- **Designating a cell that belongs to a different node than the route
+  targets.** The route selects which node's roster is searched; a `cellId`
+  absent from that node's local roster is rejected with 404, never forwarded
+  further to guess where it might live.
+- **Reading a `live-host-not-granted` rejection as a bug.** It means exactly
+  what it says: run `nexuscrew nodes live-host <node> on` on the node that
+  owns the cell, not on the node making the request.
+- **Assuming Live host state is global.** It is one value **per node**; a node
+  with nothing designated still answers `GET` with `hostCell: null` — a valid
+  state, distinct from "not permitted to ask".
+
+## Dependencies
+
+**Bundled:** this is a NexusCrew core feature. No external MCP companion or
+separate service is required — only a running NexusCrew node on each side of
+the designation.

package/skills/mail-assistant/SKILL.md

@@ -69,3 +69,18 @@ client-native scheduler or loop mechanism instead of manual polling, avoid
 duplicate jobs, respect quiet hours, and remain silent on unchanged ticks when
 the host workflow supports silent monitoring. A recurring authorization does
 not automatically authorize sending or permanent deletion.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A mail MCP connector already exposed by the current client (any Gmail/IMAP-capable MCP server; e.g. the optional companion `mcp-email-rs` <https://github.com/DioNanos/mcp-email-rs> — its Install section is authoritative, **not verified here**) | register the connector in the AI client's MCP config, following that connector's own instructions | if no mail tools are exposed, mailbox discovery returns nothing to call — ask the client for its tool list; do not assume provider folders or account layout |
+| Mailbox credentials | provided by the connector's own auth flow | auth failures surface from the connector, not from this skill |
+
+This skill never sends or deletes mail on its own initiative; a missing
+connector means the task cannot start, which must be reported, not worked
+around with direct IMAP scripting.

package/skills/memory/SKILL.md

@@ -79,3 +79,18 @@ document store, not in a bounded log.
 If no Memory MCP tool is available and this skill is packaged with NexusCrew,
 the optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
 missing capability and ask before installing or configuring anything.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A Memory MCP server (companion) | optional companion `mcp-memory-rs`: <https://github.com/DioNanos/mcp-memory-rs> — the repository's Install section is authoritative and may change; this skill deliberately does not duplicate its commands (**not verified here**) | if the companion is not registered, the client exposes no `memory_*` tools; ask the client for its tool list rather than guessing |
+| Client MCP registration | register the companion's stdio command in the AI client's MCP config | same failure mode as above: absent tools, not a runtime error |
+
+Without the companion this skill is not usable in that session: say so and
+suggest the companion once (see the packaged `mcp-companions.json` catalog)
+instead of approximating with file reads.

package/skills/nexuscrew/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: nexuscrew
+description: Read this first when working with NexusCrew for any reason — understanding what it is, what an AI agent can do through it, how cells, nodes, decks, engines, panels and Live fit together, which companion skills cover which capability, and where the trust boundaries are. This is the entry point: every other NexusCrew skill assumes what is written here.
+---
+
+# NexusCrew — what it is and what you can do through it
+
+Read this before the other NexusCrew skills. They describe individual
+capabilities; this one describes the machine they belong to, and the rules that
+hold across all of them.
+
+If the running build and this document disagree, **the build wins**. Check with
+`nexuscrew status`, `nexuscrew doctor`, and the MCP tool list actually exposed
+in your session.
+
+## The shape of the system
+
+NexusCrew turns live tmux sessions, AI CLI workers and connected machines into
+one local-first control plane, reachable from a browser.
+
+Five nouns carry almost everything:
+
+- **Node** — one installation on one machine. Its identity is an opaque
+  `instanceId`; the human-readable name is a **label**, and two nodes may
+  legitimately carry the same one. **Address things by id, never by name.**
+- **Cell** — one stable working identity (`Dev`, `Research`, …) bound to one
+  tmux session and one engine. A cell is not a process: it survives restarts of
+  the service, and stopping it does not end the work it was doing.
+- **Engine** — what a cell runs: an AI CLI, a plain shell, a command in a
+  container. Some are *managed* (the service knows how to describe and
+  configure them), some are not.
+- **Deck** — a relationship between cells that work together. Not a duplicate
+  cell, not a group chat: an arrangement.
+- **Panel** — an optional web interface a cell can carry, served next to its
+  terminal. A remote desktop, a notebook, a dashboard.
+
+Two machines that have paired are **peers**. Federation is the normal case, not
+the exception: assume the human is driving from one node toward another.
+
+## What an AI agent can actually do
+
+Through the MCP bridge, when the tools are exposed in your session:
+
+| You want to | Use | Covered by |
+|---|---|---|
+| tell the human something, or ask | `nc_notify`, `nc_ask` | `nexuscrew-agent` |
+| read runtime state, identity, decks | `nc_status`, `nc_identity`, `nc_deck` | `nexuscrew-agent` |
+| find and message another cell | `nc_cells` then `nc_send_cell` | `nexuscrew-agent` |
+| speak on a node or audio group | `nc_speak`, `nc_speak_group` | `nexuscrew-agent` |
+| hand a file to the human | `nc_send_file`, `nc_inbox` | `nexuscrew-agent` |
+| find out why a cell will not start | `nc_cell_diagnostics` | `nexuscrew-agent` |
+| keep state across sessions | Memory MCP | `memory` |
+| index and retrieve documents | MSA MCP | `vl-msa` |
+| delegate bounded work to workers | Crew MCP | `crew` |
+| read, search and triage mail | Mail MCP | `mail-assistant` |
+
+The last four are **optional companions**, listed in
+[`mcp-companions.json`](../../mcp-companions.json). They are separate servers:
+absent unless installed, and never installed silently.
+
+## Four rules that will save you a wasted hour
+
+**A receipt is not an outcome.** `submitted` from `nc_send_cell` means the text
+was pasted and Enter was pressed. It does not mean the message was understood,
+accepted, or acted on. If completion matters, ask for an explicit answer.
+
+**There is no offline queue.** A cell that is not active cannot receive. A
+`canReceive: false` peer is not "queued", it is unreachable.
+
+**Discovery is not authorization.** Seeing a cell or node in a listing does not
+mean you may act on it. Panels in particular are denied by default and granted
+per peer, by the node that owns the cell.
+
+**A cell that looks idle may not be.** A TUI queues incoming messages while it
+works, which is healthy. Do not conclude a cell is stuck from a quiet pane.
+
+## Trust boundaries
+
+- Everything binds to **loopback** by default. Reaching a node from elsewhere
+  means a tunnel or a pairing, deliberately.
+- A **panel** must point at loopback on the machine that runs the node. This is
+  not a port-forward: the caller picks *which cell*, never *where to connect*.
+  Without that rule, opening "a panel" would be a way to reach anything the
+  node can reach.
+- Never put tokens, keys, cookies or pairing material into MCP payloads,
+  messages to cells, or documents. Do not read credential files to work around
+  a missing tool.
+- Mutations are honoured or refused, never faked: `NEXUSCREW_READONLY=1` and
+  routed-peer inspect-only limits are real, and a refusal is information.
+
+## Where to look next
+
+| Topic | Document |
+|---|---|
+| Cells, engines, decks | [Fleet](../../docs/FLEET.md) |
+| Peers, pairing, visibility | [Nodes](../../docs/NODES.md) |
+| The MCP bridge and client setup | [MCP](../../docs/MCP.md) |
+| A cell's web panel | [Cell panel](../../docs/CELL_PANEL.md) |
+| Files, environment, settings | [Configuration](../../docs/CONFIGURATION.md) |
+| CLI, boot, backup, diagnostics | [Operations](../../docs/OPERATIONS.md) |
+| Trust boundaries in depth | [Security](../../docs/SECURITY.md) |
+
+## When something does not work
+
+In this order, because each step rules out the one before:
+
+1. `nexuscrew status` — is the service running, on which port, in which roles?
+2. `nexuscrew doctor` — local diagnostics.
+3. Is the tool you need **actually exposed** in this session? Do not emulate a
+   missing tool by reading state files; say it is missing and degrade openly.
+4. For a cell that will not start: `nc_cell_diagnostics` before anything else —
+   it returns the redacted command and the last startup failure.
+5. Only then look at files, and say that you are doing so and why.

package/skills/nexuscrew-agent/SKILL.md

@@ -169,3 +169,21 @@ work. The setting is also applied to windows created later in that session.
 - **Assuming a node listens on the port you know** → NexusCrew selects a free port per installation, and a peer's remote port is not the port that node listens on locally. Read it from `nexuscrew status` on that node; a health check aimed at the wrong port reports a dead service that is perfectly alive.
 - **Writing a reply into a local inbox directory** → the inbox is per-installation and is not synchronised between nodes. Answering a remote caller by dropping a file in your own inbox reaches nobody; reply through the tool that addressed you.
 - **Treating a dead scroll gesture as a web-terminal bug** → the pane is in the alternate buffer. Check whether it predates the NexusCrew setting or opted out with `alternateScreen:true`; never send raw page keys to a TUI to work around it.
+
+## Dependencies
+
+**Bundled (installed with the package):** the `nexuscrew` CLI, `lib/`, these
+skills, and the `bin/nc-send` / `bin/nc-deliver` helpers arrive with
+`npm install -g @mmmbuto/nexuscrew` (Node.js >= 18 required by `engines`).
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| Node.js >= 18 | Debian/Ubuntu `apt install nodejs` (nodesource for 18+), Fedora `dnf install nodejs`, macOS `brew install node`, Termux `pkg install nodejs-lts` | `node -v` prints >= 18; below that `npm install` refuses per `engines` |
+| tmux | Debian/Ubuntu `apt install tmux`, Fedora `dnf install tmux`, macOS `brew install tmux`, Termux `pkg install tmux` | `nexuscrew doctor` reports tmux missing by name; `nc-send` exits 127 with `nc-send: tmux not found on PATH (set TMUX_BIN)` — the failure names itself |
+| An AI client that can register the MCP server | register the stdio command `nexuscrew mcp` in the client's MCP config | if the `nc_*` tools are not exposed, no `nc_` tool exists in the session — see "MCP bridge" above |
+| A running NexusCrew service (for most tools) | `nexuscrew serve` (foreground) or your platform service manager | tools fail to reach the bridge; Termux has no systemd — run `nexuscrew serve` inside a tmux session or your own keep-alive |
+
+If tmux is missing, MCP inspection (`nc_status`, `nc_identity`) still works;
+anything that targets a session (including the `nc-send` fallback) does not.

package/skills/vl-msa/SKILL.md

@@ -66,3 +66,18 @@ round. Avoid a single unbounded search.
 If no VL-MSA tool is available and this skill is packaged with NexusCrew, the
 optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
 missing capability and ask before installing or configuring anything.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A VL-MSA MCP server (companion) | optional companion `mcp-vl-msa-rs`: <https://github.com/DioNanos/mcp-vl-msa-rs> — the repository's Install section is authoritative and may change; this skill deliberately does not duplicate its commands (**not verified here**) | if the companion is not registered, the client exposes no `msa_*` tools; ask the client for its tool list |
+| Client MCP registration | register the companion's stdio command in the AI client's MCP config | same failure mode: absent tools, not a runtime error |
+
+Without the companion, durable retrieval is simply unavailable in that
+session: say so and suggest the companion once instead of reading the
+server's on-disk collections directly (which this skill forbids).