# ClaudeTools - Project Context

**Last Updated:** 2026-04-14
**Status:** Active - Production Stable

## Quick Start - Infrastructure Overview

| Component | Location | Access | Notes |
|-----------|----------|--------|-------|
| **Production API** | http://172.16.3.30:8001 | Public access | ClaudeTools work tracking API |
| **Production DB** | MariaDB @ 172.16.3.30:3306/claudetools | Vault credentials | 38 tables, AES-256-GCM encryption |
| **Vault (SOPS)** | D:\vault\ | age-encrypted YAML | Primary credential store |
| **1Password** | Service account | Fallback | op://Projects/ClaudeTools * |
| **Gitea Repo** | git.azcomputerguru.com/azcomputerguru/claudetools | Active development | Main codebase |

**Get DB credentials:**
```bash
bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password
```

## Current State (READ THIS FIRST)

### Project Status
- **API:** 95+ endpoints, production-stable
- **Database:** 38 tables, fully encrypted sensitive fields
- **Authentication:** JWT-based, AES-256-GCM for API keys
- **Deployment:** Auto-deploy via Gitea webhooks (planned)

### Active Subprojects
1. **GuruRMM** - Remote monitoring system (see projects/msp-tools/guru-rmm/CONTEXT.md)
2. **Dataforth DOS** - Test datasheet pipeline (see projects/dataforth-dos/CONTEXT.md)

### Session Logs
- **Project-specific:** projects/*/session-logs/
- **Client work:** clients/*/session-logs/
- **General:** session-logs/ (root)

## Anti-Patterns (DON'T DO THIS)

❌ **DO NOT query database directly** - Use Database Agent for ALL operations

❌ **DO NOT write production code yourself** - Delegate to Coding Agent, coordinate as needed

❌ **DO NOT use emojis** - ASCII markers only: [OK], [ERROR], [WARNING], [SUCCESS], [INFO]

❌ **DO NOT hardcode credentials** - Always use SOPS vault (primary) or 1Password (fallback)

❌ **DO NOT skip Code Review Agent** - MANDATORY after any code changes

❌ **DO NOT execute >500 token operations directly** - Delegate to appropriate agent

## Where to Find Things

### Repository Structure
```
ClaudeTools/
├── .claude/
│   ├── CLAUDE.md                # Project instructions (directives)
│   ├── REFERENCE.md             # Technical reference
│   ├── CODING_GUIDELINES.md     # Code standards
│   ├── FILE_PLACEMENT_GUIDE.md  # Where to save files
│   ├── agents/                  # Agent definitions
│   └── memory/                  # Persistent facts (syncs via Git)
├── credentials.md               # Infrastructure reference (migrating to vault)
├── session-logs/                # General session logs
├── projects/
│   ├── msp-tools/guru-rmm/      # GuruRMM (CONTEXT.md there)
│   ├── dataforth-dos/           # Dataforth (CONTEXT.md there)
│   └── (API code is at root: api/, migrations/)
├── clients/
│   └── [client-name]/           # Client-specific work
└── D:\vault\                    # SOPS encrypted credentials (separate repo)
```

### Credential Locations

**Primary: SOPS Vault (D:\vault\)**
```bash
# Search for keywords (no decryption needed)
bash D:/vault/scripts/vault.sh search "claudetools"

# Get specific field
bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password

# List all entries
bash D:/vault/scripts/vault.sh list
```

**Structure:**
- infrastructure/ - Servers, network gear
- clients/ - Client-specific credentials
- services/ - External services (GitHub, APIs)
- projects/ - Project databases, APIs
- msp-tools/ - MSP application credentials

**Fallback: 1Password**
```bash
# ClaudeTools database credentials
op read "op://Projects/ClaudeTools Database/password"

# ClaudeTools API auth
op read "op://Projects/ClaudeTools API Auth/credential"
```

## Common Operations

### Start Work on Subproject
```
User: "Let's work on GuruRMM tunnel Phase 2"

Claude should:
1. Read projects/msp-tools/guru-rmm/CONTEXT.md (this file)
2. Check recent session logs referenced in CONTEXT.md
3. Understand current state, infrastructure, anti-patterns
4. Proceed without asking user for context

DO NOT:
- Ask user "what's the server IP?"
- Ask user "where is the database?"
- Ask user "what credentials should I use?"
All of this is in CONTEXT.md
```

### Database Operations
```bash
# WRONG: Direct query
ssh user@172.16.3.30 "mysql -u claudetools -p claudetools -e 'SELECT * FROM ...'"

# RIGHT: Delegate to Database Agent
"Use Database Agent to query work_logs table for entries from last 7 days"
```

### Deploy Code Changes
```bash
# WRONG: Deploy yourself
scp file.js user@172.16.3.30:/path/

# RIGHT: Follow project deployment process
# (See project-specific CONTEXT.md for deployment steps)
```

## Project-Specific Context Files

**When user says "work on [project]", read that project's CONTEXT.md FIRST:**

| Project | CONTEXT.md Location | What It Contains |
|---------|---------------------|------------------|
| GuruRMM | projects/msp-tools/guru-rmm/CONTEXT.md | Server IPs, deployment, tunnel architecture, agent status |
| Dataforth DOS | projects/dataforth-dos/CONTEXT.md | AD2/AD1 infrastructure, testdatadb service, log formats |
| ClaudeTools API | (This file) | Main project overview, credential locations |

## Coordination Rules (My Role)

I am a **Coordinator**, NOT an executor:

| Operation | Delegate To |
|-----------|-------------|
| Database queries/updates | Database Agent |
| Production code generation | Coding Agent |
| Code review (MANDATORY) | Code Review Agent |
| Test execution | Testing Agent |
| Git commit/push | Gitea Agent |
| Backups/restore | Backup Agent |
| File exploration | Explore Agent |
| Semantic code search | deep-explore Agent (GrepAI) |
| Complex reasoning | General-purpose + Sequential Thinking |

**I do myself:** Simple responses, reading 1-2 files, presenting results, planning, decisions

**Rule:** >500 tokens of work = delegate

## Memory System

**Location:** `.claude/memory/` (syncs across machines via Git)

**Structure:**
- MEMORY.md - Index of all facts
- [topic]-context.md - Topic-specific persistent facts

**IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/`

## Session Log Locations

**Follow these rules:**

| Work Type | Save To |
|-----------|---------|
| Dataforth DOS work | projects/dataforth-dos/session-logs/ |
| ClaudeTools API code | projects/claudetools-api/session-logs/ |
| GuruRMM work | projects/msp-tools/guru-rmm/session-logs/ |
| Client work | clients/[client-name]/session-logs/ |
| General/mixed work | session-logs/ (root) |

**See:** .claude/FILE_PLACEMENT_GUIDE.md for full rules

## Auto-Invoke Skills

**Frontend Design:** Auto-invoke `/frontend-design` skill after ANY UI change (HTML/CSS/JSX/styling)

**Sequential Thinking:** Use for genuine complexity only:
- Rejection loops (3+ failed attempts)
- Critical architectural decisions
- Multi-step debugging with unclear root cause
- NOT for every task

## Key Commands

| Command | Purpose | When |
|---------|---------|------|
| `/checkpoint` | Git commit + database context save | After code changes |
| `/save` | Comprehensive session log | End of session |
| `/context` | Search session logs + credentials | User references previous work |
| `/1password` | 1Password operations | Manage secrets |
| `/sync` | Sync from Gitea | Update local config |
| `/refresh-directives` | Re-read CLAUDE.md | After summarization, large tasks |

## Reference Documents (Read On-Demand)

- **Project instructions:** .claude/CLAUDE.md (my role, agent delegation rules)
- **Technical reference:** .claude/REFERENCE.md (endpoints, database, workflows)
- **Coding standards:** .claude/CODING_GUIDELINES.md (agents read, not every session)
- **File placement:** .claude/FILE_PLACEMENT_GUIDE.md (where to save files)
- **MCP servers:** MCP_SERVERS.md (available integrations)
- **Agent definitions:** .claude/agents/*.md (agent capabilities)

## Troubleshooting

### "I don't know the database password"
- **Check:** D:\vault\ (SOPS encrypted)
- **Command:** `bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password`
- **Fallback:** credentials.md (has 1Password references)

### "Where is the GuruRMM server?"
- **Check:** projects/msp-tools/guru-rmm/CONTEXT.md
- **Answer:** 172.16.3.30 (listed in first table)

### "How do I deploy Dataforth changes?"
- **Check:** projects/dataforth-dos/CONTEXT.md
- **Section:** "Common Operations → Deploy Code to AD2"

### "I forgot my role as Coordinator"
- **Read:** .claude/CLAUDE.md
- **Command:** `/refresh-directives`

## Quick Links

- **Credentials (vault):** D:\vault\ (SOPS encrypted YAML)
- **Credentials (legacy):** credentials.md (migrating to vault)
- **Gitea:** http://172.16.3.20:3000/azcomputerguru/claudetools
- **API Docs:** http://172.16.3.30:8001/api/docs

---

**When user says "work on [project]":**
1. Read [project]/CONTEXT.md FIRST (don't ask user for context)
2. Check recent session logs mentioned in CONTEXT.md
3. Understand infrastructure, anti-patterns, current state
4. Proceed with work

**This eliminates:**
- "What's the server IP?" → In CONTEXT.md
- "Where's the database?" → In CONTEXT.md
- "What credentials?" → In CONTEXT.md
- "What did we do last time?" → In session logs referenced by CONTEXT.md