stack/packages/mosaic/framework/defaults/TOOLS.md

# Machine Tools — Index

Tool suites live at `~/.config/mosaic/tools/<suite>/`. This is the index only.
**Full CLI signatures, flags, and examples: `~/.config/mosaic/guides/TOOLS-REFERENCE.md`** —
read it (or the relevant service guide) when your task actually touches that service.
Project-specific tooling belongs in the project's `AGENTS.md`, not here.

## Most-used fleet tools (reach for these first)

<!-- fleet-comms-contract: 1 -->

You are a Mosaic fleet agent. Use the runtime-composed **Fleet Comms — authoritative exact targets**
section for inter-agent messaging. It renders your authoritative local host, exact agent/session, resolved
tmux socket, installed helper path, generation, and one executable command per known peer.

Select only a peer row rendered for your exact roster identity. Never invent, substitute, or fuzzy-match
a host, session, socket, SSH destination, or helper path. If a peer is absent, stop and run the exact
self-scoped discovery command shown in that composed section; report the peer as unknown if it remains
absent. Do not use raw `tmux send-keys` for fleet messaging.

**Issues / PRs / milestones** → `tools/git/*.sh` wrappers (before raw `tea`/`gh`/`glab`):

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

**GITEA_LOGIN gotcha** — the wrappers default to login `mosaicstack`; on a USC repo that fails with
`gitea / Error: GetUserByName ... not found`. Pick the login from the repo's `origin` host first:

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

## Suites (use wrappers first)

| Suite      | Path                                             | Purpose                                                                  |
| ---------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| tmux       | `tools/tmux/agent-send.sh`                       | inter-agent messaging (see "Most-used" above)                            |
| git        | `tools/git/*.sh`                                 | issues, PRs, milestones, CI queue guard (platform-auto-detected)         |
| woodpecker | `tools/woodpecker/*.sh`                          | CI pipelines (`-a mosaic`\|`usc`; match git remote host)                 |
| portainer  | `tools/portainer/*.sh`                           | Docker Swarm stacks (status/redeploy/list)                               |
| coolify    | `tools/coolify/*.sh`                             | **DEPRECATED** — superseded by Portainer; do not use for new deployments |
| authentik  | `tools/authentik/*.sh`                           | identity (users/groups/apps/flows)                                       |
| cloudflare | `tools/cloudflare/*.sh`                          | DNS (zones/records; `-a` instance)                                       |
| glpi       | `tools/glpi/*.sh`                                | IT tickets/computers/users                                               |
| health     | `tools/health/stack-health.sh`                   | service health checks                                                    |
| codex      | `tools/codex/*.sh`                               | code/security review (`--uncommitted`)                                   |
| openbrain  | `tools/openbrain/*`, `tools/openbrain_client.py` | semantic memory (see below)                                              |
| excalidraw | MCP `mcp__excalidraw__*`                         | diagram export/generation                                                |

Git wrappers are MANDATORY-first for issue/PR/milestone ops (see AGENTS.md hard gates 6–8).
Queue guard before push/merge: `tools/git/ci-queue-wait.sh --purpose push|merge`.

## Credentials

`source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>`
Supported: portainer, coolify (deprecated), authentik, glpi, github, gitea-mosaicstack,
gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain. Never expose or commit values.

## OpenBrain — Semantic Memory (PRIMARY) — capture when you LEARN, never when you DO

Primary cross-agent memory (pgvector). Capture decisions/gotchas/preferences/patterns; never task
starts, commits, PRs, test results, or file edits. At session start, `search` + `recent` to load
prior context. MCP (`mcp__openbrain__capture/search/recent/stats`) preferred when connected; else
REST/`tools/openbrain_client.py`. Full protocol: `guides/MEMORY.md`.

## Git Providers

| Host                | Instance         | CI                               |
| ------------------- | ---------------- | -------------------------------- |
| git.mosaicstack.dev | mosaic (default) | ci.mosaicstack.dev (`-a mosaic`) |
| git.uscllc.com      | usc              | ci.uscllc.com (`-a usc`)         |

Match Woodpecker `-a` and credential instance to the target repo's git remote host.

## Safety Defaults

- Prefer `trash` over `rm` when available — recoverable beats gone forever.
- Never run destructive commands without explicit instruction.