---
name: mosaic-tools
description: Fast path to the Mosaic fleet toolkit at ~/.config/mosaic/tools/. Use FIRST when you need to message another agent's tmux session, open/merge a Gitea/GitHub PR or issue, run a CI queue wait, or operate Portainer/Woodpecker/Authentik/Cloudflare. Reach for these wrappers before hand-rolling raw tmux send-keys, raw tea/gh/glab, or curl.
---

# mosaic-tools

You are a Mosaic fleet agent on web1. A maintained toolkit lives at `~/.config/mosaic/tools/`.
Use it FIRST for the tasks below — improvising with raw CLIs causes the recurring failures this
skill exists to prevent. This is the high-frequency fast path; the full reference is the
`# Machine Tools` section already in your system prompt.

## 1. Message another agent (highest priority)

To send a message or briefing to another agent's tmux session, use the wrapper — **never** raw
`tmux send-keys` / `paste-buffer` (interactive REPLs swallow a trailing Enter or leave the text as
an unsubmitted draft; the wrapper handles bracketed paste, Enter flushing, and the `[src -> dst]`
preamble):

```bash
~/.config/mosaic/tools/tmux/agent-send.sh -s <target-session> -m "your message"
~/.config/mosaic/tools/tmux/agent-send.sh -s mos-claude -f path/to/brief.md   # send a file's contents
```

The coordinator session is `mos-claude`. Status reports, findings, and questions go there.

## 2. Git provider operations (issues / PRs / milestones)

Use the wrappers — they auto-detect the platform (Gitea or GitHub) and handle auth. Prefer them
over raw `tea` / `gh` / `glab`:

```bash
~/.config/mosaic/tools/git/issue-create.sh ...
~/.config/mosaic/tools/git/issue-close.sh ...
~/.config/mosaic/tools/git/pr-create.sh ...
~/.config/mosaic/tools/git/pr-merge.sh ...
~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge   # REQUIRED before any push or merge
```

### GITEA_LOGIN gotcha (do not skip)

The wrappers default to `--login ${GITEA_LOGIN:-mosaicstack}`. On **USC** repos hosted at
`git.uscllc.com`, that default fails with `gitea / Error: GetUserByName ... not found`. Pick the
login from the repo's `origin` host **before** running a wrapper:

```bash
git remote get-url origin   # inspect the host, then:
```

| origin host           | login                                        |
| --------------------- | -------------------------------------------- |
| `git.uscllc.com`      | `export GITEA_LOGIN=usc`                     |
| `git.mosaicstack.dev` | default `mosaicstack` (no export needed)     |

## 3. Other tool suites under `~/.config/mosaic/tools/`

- `woodpecker/` — CI pipeline status/trigger (`pipeline-status.sh`, `pipeline-list.sh`; `-a usc` for USC repos)
- `portainer/` — Docker Swarm stack status/redeploy
- `authentik/` — identity: users, groups, apps, flows
- `cloudflare/` — DNS records (`-a <instance>` for multi-account)
- `health/` — `stack-health.sh` service checks
- `openbrain/` — semantic agent memory (meta-observations only)

For the complete reference, consult the `# Machine Tools` section in your system prompt before
improvising. Related skills: `mosaic-gitea` (full git-wrapper flag reference),
`mosaic-tmux-comms` (inter-agent messaging detail).