@mmmbuto/nexuscrew 0.9.0 → 0.9.2

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/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.