# TOOLS.md — Builder's Toolkit

## Development Environment
- **VPS:** DigitalOcean syd1, 2 vCPU, 8GB RAM, IP 134.199.153.159
- **Node:** v22.x
- **Package Manager:** npm
- **App Port:** 3000 via systemd `rateright-app` service
- **Builder Gateway:** port 18790 via systemd `clawdbot-builder` service

## Build & Deploy

```bash
# Build (mandatory before every commit)
npm run build

# Dev server
npm run dev

# Deploy to production
npm run build && sudo systemctl restart rateright-app

# Check app status
sudo systemctl status rateright-app

# App logs
sudo journalctl -u rateright-app -f

# Builder gateway logs
sudo journalctl -u clawdbot-builder -f --no-pager -n 50
```

## Git

```bash
# Status check
git status

# Conventional commits
git add -A && git commit -m "feat: description"
git add -A && git commit -m "fix: description"
git add -A && git commit -m "refactor: description"
git add -A && git commit -m "chore: description"

# Push to main (no PRs required)
git push origin main
```

## Database (Supabase)

- **Project:** eciepjpcyfurbkfzekok
- **URL:** https://eciepjpcyfurbkfzekok.supabase.co
- **Schema:** profiles, companies, worker_profiles, jobs, matches, ratings, payments, notifications, conversations, conversation_participants, messages
- **RLS:** Enabled on all tables — never bypass in client code

### SQL via Management API
```bash
curl -s -X POST "https://eciepjpcyfurbkfzekok.supabase.co/rest/v1/rpc/<function>" \
  -H "apikey: $SUPABASE_ANON_KEY" \
  -H "Authorization: Bearer $SUPABASE_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json"
```

## Stripe
- **Product:** $50 AUD hire fee, `prod_TwC6PLLwYHVTt3`
- **Price:** `price_1SyJinRQ4311dYYb9NmbyYgO`
- **Keys:** In `.env.local` — `sk_live` and `pk_live`
- **Never read .env in session** — use external scripts

## Fleet Communication

### Inbox (JSONL System)
```bash
# Read my inbox
node /home/ccuser/shared/scripts/inbox.js read --agent builder --unread

# Acknowledge a message
node /home/ccuser/shared/scripts/inbox.js ack --agent builder --id <msg-id>

# Send to another agent
node /home/ccuser/shared/scripts/inbox.js send --from builder --to <agent> --subject "Subject" --body "Details"
```

### Fleet Status
```bash
# Quick fleet overview
node /home/ccuser/shared/scripts/fleet-cli.js status

# My briefing
node /home/ccuser/shared/scripts/fleet-cli.js briefing builder --brief

# Update my status
node /home/ccuser/shared/scripts/fleet-update.js builder --status active --task "description"
```

### Agent Bridge (HTTP)
```bash
# Wake an agent
node /home/ccuser/the-50-dollar-app/scripts/agent-bridge.js <agent> wake "<message>"

# Agent status
node /home/ccuser/the-50-dollar-app/scripts/agent-bridge.js <agent> status
```

### Shared Files
```
/home/ccuser/shared/fleet-state.json       # Fleet-wide state (read often, Rivet curates)
/home/ccuser/the-50-dollar-app/status.json # My status (I write, others read)
/home/ccuser/the-50-dollar-app/queue.json  # My task queue (Rivet writes, I execute)
```

### Inbox Files (Markdown — Primary Channel)
```
/home/ccuser/rateright-growth/rivet/BUILDER-INBOX.md  # Rivet → me (I read only)
/home/ccuser/the-50-dollar-app/RIVET-INBOX.md         # Me → Rivet (I write only)
```

## External Services
- **Resend:** Email sending, API key in .env.local
- **OpenAI:** AI features (voice, matching), API key in .env.local
- **Domain:** rivet.rateright.com.au with SSL

## Tech Stack
- **Framework:** Next.js 14 App Router
- **Language:** TypeScript (strict)
- **Styling:** Tailwind CSS 4 + shadcn/ui
- **Auth:** Supabase Auth
- **Database:** Supabase (PostgreSQL)
- **Payments:** Stripe
- **Voice:** Whisper transcription, GPT-4o-mini processing
- **Deployment:** systemd on VPS

## Workspace Layout
```
/home/ccuser/the-50-dollar-app/
├── SOUL.md              # Who I am
├── IDENTITY.md          # Quick reference card
├── AGENTS.md            # Fleet operations
├── TOOLS.md             # This file
├── OPS.md               # Autonomous operations playbook
├── MEMORY.md            # Long-term technical knowledge
├── USER.md              # About Michael
├── HEARTBEAT.md         # Heartbeat protocol
├── RIVET-INBOX.md       # My messages to Rivet
├── status.json          # My current state
├── queue.json           # Task queue from fleet
├── scripts/             # Utility scripts (agent bridge, etc.)
├── src/                 # App source code
├── app/                 # Next.js app directory
├── components/          # React components
├── lib/                 # Shared utilities
├── public/              # Static assets
└── memory/              # Daily logs and notes
```

---

*These are my tools. Mastered and ready. 🔨*