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

Machine-Level Tool Reference

Centralized reference for tools, credentials, and CLI patterns available across all projects. Project-specific tooling belongs in the project's AGENTS.md, not here.

All tool suites are located at ~/.config/mosaic/tools/.

Tool Suites

Git Wrappers (Use First)

Mosaic wrappers at ~/.config/mosaic/tools/git/*.sh handle platform detection and edge cases. Always use these before raw CLI commands.

# Issues
~/.config/mosaic/tools/git/issue-create.sh
~/.config/mosaic/tools/git/issue-close.sh

# PRs
~/.config/mosaic/tools/git/pr-create.sh
~/.config/mosaic/tools/git/pr-merge.sh

# Milestones
~/.config/mosaic/tools/git/milestone-create.sh

# CI queue guard (required before push/merge)
~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge

Code Review (Codex)

~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted

Infrastructure — Portainer

~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name>
~/.config/mosaic/tools/portainer/stack-list.sh
~/.config/mosaic/tools/portainer/endpoint-list.sh

Infrastructure — Coolify (DEPRECATED)

Coolify has been superseded by Portainer Docker Swarm in this stack. Tools remain for reference but should not be used for new deployments.

# DEPRECATED — do not use for new deployments
~/.config/mosaic/tools/coolify/project-list.sh
~/.config/mosaic/tools/coolify/service-list.sh
~/.config/mosaic/tools/coolify/service-status.sh -u <uuid>
~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>
~/.config/mosaic/tools/coolify/env-set.sh -u <uuid> -k KEY -v VALUE

Identity — Authentik

~/.config/mosaic/tools/authentik/user-list.sh
~/.config/mosaic/tools/authentik/user-create.sh -u <username> -n <name> -e <email>
~/.config/mosaic/tools/authentik/group-list.sh
~/.config/mosaic/tools/authentik/app-list.sh
~/.config/mosaic/tools/authentik/flow-list.sh
~/.config/mosaic/tools/authentik/admin-status.sh

CI/CD — Woodpecker

Multi-instance support: -a <instance> selects a named instance. Omit -a to use the default from woodpecker.default in credentials.json.

Instance	URL	Serves
mosaic (default)	ci.mosaicstack.dev	Mosaic repos (git.mosaicstack.dev)
usc	ci.uscllc.com	USC repos (git.uscllc.com)

# List recent pipelines
~/.config/mosaic/tools/woodpecker/pipeline-list.sh [-r owner/repo] [-a instance]

# Check latest or specific pipeline status
~/.config/mosaic/tools/woodpecker/pipeline-status.sh [-r owner/repo] [-n number] [-a instance]

# Trigger a build
~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh [-r owner/repo] [-b branch] [-a instance]

Instance selection rule: match -a to the git remote host of the target repo. If the repo is on git.uscllc.com, use -a usc. If on git.mosaicstack.dev, use -a mosaic (or omit, since it's the default).

DNS — Cloudflare

Multi-instance support: -a <instance> selects a named instance (e.g. personal, work). Omit -a to use the default from cloudflare.default in credentials.json.

# List zones (domains)
~/.config/mosaic/tools/cloudflare/zone-list.sh [-a instance]

# List DNS records (zone by name or ID)
~/.config/mosaic/tools/cloudflare/record-list.sh -z <zone> [-a instance] [-t type] [-n name]

# Create DNS record
~/.config/mosaic/tools/cloudflare/record-create.sh -z <zone> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl] [-P priority]

# Update DNS record
~/.config/mosaic/tools/cloudflare/record-update.sh -z <zone> -r <record-id> -t <type> -n <name> -c <content> [-a instance] [-p] [-l ttl]

# Delete DNS record
~/.config/mosaic/tools/cloudflare/record-delete.sh -z <zone> -r <record-id> [-a instance]

IT Service — GLPI

~/.config/mosaic/tools/glpi/ticket-list.sh
~/.config/mosaic/tools/glpi/ticket-create.sh -t <title> -c <content>
~/.config/mosaic/tools/glpi/computer-list.sh
~/.config/mosaic/tools/glpi/user-list.sh

Health Check

# Check all configured services
~/.config/mosaic/tools/health/stack-health.sh

# Check a specific service
~/.config/mosaic/tools/health/stack-health.sh -s portainer

# JSON output for automation
~/.config/mosaic/tools/health/stack-health.sh -f json

Shared Credential Loader

# Source in any script to load service credentials
source ~/.config/mosaic/tools/_lib/credentials.sh
load_credentials <service-name>
# Supported: portainer, coolify, authentik, glpi, github, gitea-mosaicstack, gitea-usc, woodpecker, cloudflare, turbo-cache, openbrain

OpenBrain — Semantic Memory (PRIMARY)

Self-hosted semantic brain backed by pgvector. Primary shared memory layer for all agents across all sessions and harnesses. Stores and retrieves decisions, context, and observations via semantic search.

MANDATORY jarvis-brain rule: When working in ~/src/jarvis-brain, NEVER capture project data, meeting notes, status updates, timeline decisions, or task completions to OpenBrain. The flat files (data/projects/*.json, data/tasks/*.json) are the SSOT — use tools/brain.py and direct JSON edits. OpenBrain is for agent meta-observations ONLY (tooling gotchas, framework learnings, cross-project patterns). Violating this creates duplicate, divergent data.

Credentials: load_credentials openbrain → exports OPENBRAIN_URL, OPENBRAIN_TOKEN

Configure in your credentials.json:

"openbrain": {
  "url": "https://<your-openbrain-host>",
  "api_key": "<your-api-key>"
}

REST API (any language, any harness):

source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials openbrain

# Search by meaning
curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}' "$OPENBRAIN_URL/v1/search"

# Capture a thought
curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"content": "...", "source": "agent-name", "metadata": {}}' "$OPENBRAIN_URL/v1/thoughts"

# Recent activity
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"

# Stats
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/stats"

Python client (if jarvis-brain is available on PYTHONPATH):

python tools/openbrain_client.py search "topic"
python tools/openbrain_client.py capture "decision or observation" --source agent-name
python tools/openbrain_client.py recent --limit 5
python tools/openbrain_client.py stats

MCP (Claude Code sessions): When connected, mcp__openbrain__capture/search/recent/stats tools are available natively — prefer those over CLI when in a Claude session.

Rule: capture when you LEARN something. Never when you DO something.

Trigger	Action	Retention
Session start	search + recent to load prior context	—
Architectural or tooling decision made	Capture with rationale	long or permanent
Gotcha or non-obvious behavior discovered	Capture immediately	medium
User preference stated or confirmed	Capture	permanent
Cross-project pattern identified	Capture	permanent
Prior decision superseded	UPDATE existing thought	(keep tier)

Never capture: task started, commit pushed, PR opened, test results, file edits, CI status.

Full protocol and cleanup tools: ~/.config/mosaic/guides/MEMORY.md Smart capture wrapper (enforces schema + dedup): ~/.config/mosaic/tools/openbrain/capture.sh

Excalidraw — Diagram Export (MCP)

Headless .excalidraw → SVG export via @excalidraw/excalidraw. Available as MCP tools in Claude Code sessions.

MCP tools (when connected):

Tool	Input	Output
mcp__excalidraw__excalidraw_to_svg	elements JSON string + optional app_state	SVG string
mcp__excalidraw__excalidraw_file_to_svg	file_path to .excalidraw	SVG string + writes .svg alongside
mcp__excalidraw__list_diagrams	(none)	Available templates (requires EXCALIDRAW_GEN_PATH)
mcp__excalidraw__generate_diagram	name, optional output_path	Path to generated .excalidraw
mcp__excalidraw__generate_and_export	name, optional output_path	Paths to .excalidraw and .svg

Diagram generation (list_diagrams, generate_diagram, generate_and_export) requires EXCALIDRAW_GEN_PATH env var pointing to excalidraw_gen.py. Set in environment or shell profile:

export EXCALIDRAW_GEN_PATH="$HOME/src/jarvis-brain/tools/excalidraw_export/excalidraw_gen.py"

Manual registration:

mosaic-ensure-excalidraw           # install deps + register with Claude
mosaic-ensure-excalidraw --check   # verify registration

Git Providers

Instance	URL	CLI	Purpose
(add your git providers here)

Credentials

Location: (configure your credential file path) Loader: source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials <service>

Never expose actual values. Never commit credential files.

CLI Gotchas

(Add platform-specific CLI gotchas as you discover them.)

Safety Defaults

• Prefer trash over rm when available — recoverable beats gone forever
• Never run destructive commands without explicit instruction
• Write it down — "mental notes" don't survive session restarts; files do