bootstrap/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, project state, and observations via semantic search.

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

# --- Read ---
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/recent?limit=5"
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/{id}"
curl -s -H "Authorization: Bearer $OPENBRAIN_TOKEN" \
  "$OPENBRAIN_URL/v1/thoughts?source=agent-name&metadata_id=my-entity&limit=10"

# --- Search ---
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 ---
curl -s -X POST -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"content": "...", "source": "agent-name", "metadata": {}}' "$OPENBRAIN_URL/v1/thoughts"

# --- Update (re-embeds if content changes) ---
curl -s -X PATCH -H "Authorization: Bearer $OPENBRAIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"content": "updated text", "metadata": {"key": "val"}}' "$OPENBRAIN_URL/v1/thoughts/{id}"

# --- Delete single ---
curl -s -X DELETE -H "Authorization: Bearer $OPENBRAIN_TOKEN" "$OPENBRAIN_URL/v1/thoughts/{id}"

# --- Bulk delete by filter (source and/or metadata_id required) ---
curl -s -X DELETE -H "Authorization: Bearer $OPENBRAIN_TOKEN" \
  "$OPENBRAIN_URL/v1/thoughts?source=agent-name&metadata_id=my-entity"

# --- 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, all CRUD tools are available natively: capture, search, recent, stats, get, update, delete, delete_where, list_thoughts

When to use openbrain (required for all agents):

Trigger	Action
Session start	Search/recent to load prior context
Significant decision made	Capture with rationale
Blocker or gotcha discovered	Capture immediately
Task or milestone completed	Capture summary
Cross-agent handoff	Capture current state

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