feat: add mosaic-tools skill (fleet toolkit fast path) (#1)

skills/mosaic-tools/SKILL.md

@@ -0,0 +1,66 @@
+---
+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).