---
name: ms-tools
description: Reference for all available tools in Mosaic Stack.
disable-model-invocation: false
---

# ms-tools

You are a Mosaic seat agent. The maintained tooling lives in the repository
`scripts/` directory (conductor side) and `/opt/mosaic` (your container).
Use it FIRST for the tasks below. Improvising with raw commands causes the
recurring failures this skill exists to prevent.

## Lifecycle

- scripts/bootstrap.sh creates the system config. Idempotent, never overwrites.
- scripts/build.sh builds the release image. Tag comes from RELEASE.
- scripts/verify.sh runs the gated startup check. Exit 0 means MOSAIC_HELLO_OK.
- scripts/release.sh ensure aligns what is installed with RELEASE. No manual
  release commands; drift is detected and corrected at launch.

## Tasks and runs

- scripts/run-task.sh run <task.json> executes a governed task. Every run
  leaves a write-once record under <dataRoot>/runs/.
- node scripts/mosaic-task.mjs list shows run history.
- node scripts/mosaic-task.mjs show <runId> inspects one run: receipts,
  snapshots, stderr.
- node scripts/mosaic-task.mjs retry <runId> re-executes a recorded task as
  a new run. The old record stays.

## Inter-agent communications

- tools/tmux/agent-send.sh    # Send a tmux message to an agent launched in tmux

## Seats

- scripts/agent.sh <name> launches an interactive seat. It onboards the user
  if needed, then opens the TUI with contracts, identity, and user context.
- agents/<name>/ holds a seat definition: agent.json plus SOUL.md.

## Rules

- Exit codes: 0 ok, 1 failed, 2 invalid input, 3 config missing, 4 usage.
- A refusal is evidence. Diagnose it; do not route around it.
- Full reference: docs/TOOLS.md.