test-repo/TOOLS.md

# TOOLS.md - Local Notes

Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.

## What Goes Here

Things like:

- Camera names and locations
- SSH hosts and aliases
- Preferred voices for TTS
- Speaker/room names
- Device nicknames
- Anything environment-specific

## Examples

```markdown
### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice: "Nova" (warm, slightly British)
- Default speaker: Kitchen HomePod
```

## Why Separate?

Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.

---
## Gitea (Git Server - DO NOT INSTALL LOCALLY)

**⚠️ CRITICAL:** Gitea runs on a SEPARATE MACHINE (192.168.1.128). Do NOT install it on Matt's Mac.

**Server Location:** http://192.168.1.128:3000 (NOT localhost:3000)
- **Login:** ai-agent / !7883Gitea
- **Organization:** TopDogLabs
- **All repos go under:** http://192.168.1.128:3000/TopDogLabs/

### Backup Rule - MANDATORY

**ALWAYS push to Gitea after significant changes:**
```bash
cd /Users/mattbruce/.openclaw/workspace
git add -A
git commit -m "Description of changes"
git push origin master
```

**Push after:**
- New skills or agent profiles created
- TOOLS.md, SOUL.md, AGENTS.md updates
- New cron jobs or automation
- Significant memory/documentation changes
- New project scaffolding

**Why:** Ensures continuity if local workspace is lost/corrupted.

### Using Gitea

**Clone existing repo:**
```bash
git clone http://192.168.1.128:3000/TopDogLabs/repo-name.git
```

**Push to Gitea:**
```bash
git push origin main
# Enter username: ai-agent
# Enter password: !7883Gitea
```

**Create new repo via web:**
1. Go to http://192.168.1.128:3000
2. Login as ai-agent
3. Click + → New Repository
4. Owner: TopDogLabs
5. Name: [project-name]

**NEVER do this:**
- ❌ `brew install gitea` on Matt's Mac
- ❌ Run `gitea web` locally
- ❌ Use port 3000 for anything (it's for Next.js dev)

## Folders for All Content/Projects
- **Location:** /Users/mattbruce/Documents/Projects/OpenClaw
- **Documents:** /Users/mattbruce/Documents/Projects/OpenClaw/Documents
- **iOS:** /Users/mattbruce/Documents/Projects/OpenClaw/iOS
- **Web:** /Users/mattbruce/Documents/Projects/OpenClaw/Web

## Blog Backup
- **Location:** /Users/mattbruce/Documents/Projects/OpenClaw/Web/blog-backup
- **Live URL:** https://blog-backup-two.vercel.app
- **Local Dev:** http://localhost:3002
- **Stack:** Next.js + Supabase + Vercel
- **Deploy:** `npm run build && vercel --prod` (no GitHub, CLI only)
- **Features:** Daily digest blog with tag filtering, search, responsive design

## Mission Control
- **Location:** /Users/mattbruce/Documents/Projects/OpenClaw/Web/mission-control
- **Live URL:** https://mission-control-rho-pink.vercel.app/
- **Local Dev:** http://localhost:3001
- **Stack:** Next.js + Vercel
- **Deploy:** `npm run build && vercel --prod` (no GitHub, CLI only)

## Heartbeat Monitor
- **Location:** /Users/mattbruce/Documents/Projects/OpenClaw/Web/heartbeat-monitor
- **Local Dev:** http://localhost:3005
- **Stack:** Next.js + Vercel

## Gantt Board
- **Location:** /Users/mattbruce/Documents/Projects/OpenClaw/Web/gantt-board
- **Live URL:** https://gantt-board.vercel.app
- **Login:** mbruce+max@topdoglabs.com / !7883Gantt
- **Local Dev:** http://localhost:3000
- **Stack:** Next.js + Supabase + Vercel
- **Deploy:** `npm run build && vercel --prod` (no GitHub, CLI only)

### CLI Access (Create Tasks Directly)

**Location:** `/Users/mattbruce/Documents/Projects/OpenClaw/Web/gantt-board/scripts/gantt-task-crud.sh`

**Create Task:**
```bash
cd /Users/mattbruce/Documents/Projects/OpenClaw/Web/gantt-board
./scripts/gantt-task-crud.sh create "Task Title" todo high a1b2c3d4-0001-0000-0000-000000000001 9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa task
```

**Parameters:**
1. `title` - Task title (required)
2. `status` - open, todo, in-progress, review, validate, done
3. `priority` - low, medium, high, urgent
4. `project_id` - Default: a1b2c3d4-0001-0000-0000-000000000001
5. `assignee_id` - Default: 9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa (Max)
6. `type` - task, idea, bug, research, plan

**Other Commands:**
```bash
./scripts/gantt-task-crud.sh list                    # List all tasks
./scripts/gantt-task-crud.sh list todo               # List todo tasks
./scripts/gantt-task-crud.sh get <task-id>           # Get specific task
./scripts/gantt-task-crud.sh update <id> status done # Update task status
./scripts/gantt-task-crud.sh delete <task-id>        # Delete task
```

**Note:** The CLI uses Supabase service role key for direct DB access. Description, tags, and sprint assignment must be added via the web UI after creation.

## Supabase for Gantt Board

- **URL:** https://qnatchrjlpehiijwtreh.supabase.co
- **Project ID:** qnatchrjlpehiijwtreh

## User IDs for Gantt Board

- **Matt:** 0a3e400c-3932-48ae-9b65-f3f9c6f26fe9
- **Max:** 9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa

---

## 🔄 Automated Task Worker (24/7)

**CRITICAL:** This is the PRIMARY workflow for all task work. Read this every session.

### Cron Job
- **Job ID:** `b9f3bbe6-bcb5-4483-8816-d044fd91c58a`
- **Schedule:** Every hour (24/7)
- **Scope:** Current sprint ONLY (ignores backlog/future sprints)
- **Statuses:** `open`, `todo`, `in-progress`
- **Assignee:** Max (9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa)

### When User Says "Create a Task"
1. Immediately add to Gantt Board via CLI: `./scripts/gantt-task-crud.sh create "Title" todo high ...`
2. Assign to current sprint
3. Do NOT create separate files (unless specifically asked)

### Reading Full Task Details (REQUIRED)
**ALWAYS query Supabase for complete task before working:**
```bash
curl -s "https://qnatchrjlpehiijwtreh.supabase.co/rest/v1/tasks?id=eq.{task_id}&select=*" \
  -H "apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InFuYXRjaHJqbHBlaGlpand0cmVoIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc3MTY0MDQzNiwiZXhwIjoyMDg3MjE2NDM2fQ.rHoc3NfL59S4lejU4-ArSzox1krQkQG-TnfXb6sslm0" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InFuYXRjaHJqbHBlaGlpand0cmVoIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImlhdCI6MTc3MTY0MDQzNiwiZXhwIjoyMDg3MjE2NDM2fQ.rHoc3NfL59S4lejU4-ArSzox1krQkQG-TnfXb6sslm0"
```

**READ in this order:**
1. **Title** - High-level goal
2. **Description** - Implementation details, steps
3. **Comments** (ALL of them) - What's done? What's next? What's left?

### Task Comment Format (APPEND to existing)
```json
{
  "id": "{timestamp}-{random}",
  "text": "[YYYY-MM-DD HH:MM] 🔄 In Progress\n\n**What was just done:**\n- Step completed\n\n**What is next:**\n- Next action\n\n**What is left to do:**\n- Remaining work",
  "replies": [],
  "createdAt": "YYYY-MM-DDTHH:MM:SSZ",
  "commentAuthorId": "9c29cc99-81a1-4e75-8dff-cd7cc5ceb5aa"
}
```

### Status Flow
```
open/todo → in-progress → review → (user validates) → done
    ↑
Add progress comment at EACH step
```

### Updating Tasks
```bash
curl -s -X PATCH "https://qnatchrjlpehiijwtreh.supabase.co/rest/v1/tasks?id=eq.{task_id}" \
  -H "apikey: {service_key}" \
  -H "Authorization: Bearer {service_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in-progress",
    "comments": [EXISTING_COMMENTS_PLUS_NEW_ONE]
  }'
```

### Subagent Coordination
- Spawn subagents for parallel work
- Subagents READ same full task details
- Subagents REPORT back with progress
- YOU update task comments with their work

### User Workflow
- User creates task in Gantt Board
- Cron/auto picks it up hourly
- I work on it, log everything in comments
- Move to `review` when complete
- User validates, moves to `done`

## 👥 Subagent Team (Alice, Bob, Charlie)

**Location:** `/Users/mattbruce/.openclaw/workspace/agents/`

**Full Registry:** `agents/TEAM-REGISTRY.md`

### Team Members

| Name | Role | When to Spawn |
|------|------|---------------|
| **Alice-Researcher** | Research & tech evaluation | Need to choose technology, compare options, assess risks |
| **Bob-Implementer** | Code implementation | Requirements clear, ready to build |
| **Charlie-Tester** | Testing & code review | Implementation done, need quality gate |

### Standard Workflow

```
Complex Task:  Alice → Bob → Charlie → Done
               15m    30m     10m

Simple Task:   Bob → Charlie → Done
               20m    10m

Research Only: Alice → Report
               15m
```

### How to Spawn

**Alice (Research):**
```javascript
sessions_spawn({
  task: `Research: [question]\n\nContext: [background]\n\nRead your SOUL.md at: /Users/mattbruce/.openclaw/workspace/agents/alice-researcher/SOUL.md`,
  label: "Alice-Researcher",
  agentId: "main"
})
```

**Bob (Implement):**
```javascript
sessions_spawn({
  task: `Implement: [feature]\n\nBased on: [research/spec]\n\nRead your SOUL.md at: /Users/mattbruce/.openclaw/workspace/agents/bob-implementer/SOUL.md`,
  label: "Bob-Implementer",
  agentId: "main"
})
```

**Charlie (Test):**
```javascript
sessions_spawn({
  task: `Test: [feature]\n\nCode: [files]\n\nRead your SOUL.md at: /Users/mattbruce/.openclaw/workspace/agents/charlie-tester/SOUL.md`,
  label: "Charlie-Tester",
  agentId: "main"
})
```

### Each Agent Has
- **SOUL.md** - Personality, rules, boundaries
- **AGENTS.md** - Role definition, skills, typical tasks

### Announcement Format
- **Alice:** "Alice-Researcher ✅ 5 options evaluated – Recommended: X – Ready for Bob"
- **Bob:** "Bob-Implementer ✅ [feature] implemented – Ready for Charlie"
- **Charlie:** "Charlie-Tester ✅ 12 tests passed – 2 bugs found – Recommendation"

---

## Tavily AI Search (Configured)

**API Key:** Stored in `.env.tavily` (auto-loaded)

**Quick Commands:**
```bash
# Search
cd ~/.openclaw/workspace && ./tavily-search.sh "query" -n 5

# Extract URL content
cd ~/.openclaw/workspace && ./tavily-extract.sh "https://example.com"

# Deep research
cd ~/.openclaw/workspace && ./tavily-search.sh "query" --deep
```

**Note:** API key is automatically loaded from `.env.tavily`. No need to export manually.

---

## Daily Digest Failsafe System

**Cron Job:** Daily Digest - 7am CST (America/Chicago)  
**Status:** ✅ Fixed and monitored  
**Last Posted:** 2026-02-23

**What I Fixed:**
- ✅ Wrong API key in cron job (was `cron_daily_digest_2025`, now `daily-digest-2026-secure-key`)
- ✅ Added retry logic (3 attempts with 30s delay)
- ✅ Enabled notifications on failure
- ✅ Added backup file creation on failure (`memory/YYYY-MM-DD-digest-failed.md`)

**If It Fails:**
1. You will get notified immediately
2. Digest content saved to `memory/` folder
3. Can be manually posted or I can fix it

**Manual Posting (Emergency):**
```bash
curl -X POST "https://blog-backup-two.vercel.app/api/digest" \
  -H "Content-Type: application/json" \
  -H "x-api-key: daily-digest-2026-secure-key" \
  -d '{"date": "2026-02-23", "content": "...", "tags": [...]}'
```

---

Add whatever helps you do your job. This is your cheat sheet.