# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working in any project under the claude-projects directory.

## AUTO-SAVE CREDENTIALS RULE

**CRITICAL: IMMEDIATELY save to `shared-data/credentials.md` whenever:**

1. **User provides** any credential (password, API key, token, etc.)
2. **Claude generates** any credential (SSH keys, tokens, secrets, passwords, etc.)
3. **Claude discovers** credentials during work (from config files, command output, etc.)

**Types of credentials to save:**
- Passwords
- API keys/tokens
- SSH keys or passphrases
- Database credentials
- Service account credentials
- OAuth tokens
- JWT secrets
- Generated secrets (random strings, hashes)
- Any authentication information

**How to save:**
1. Identify the service/system the credential belongs to
2. Append to the appropriate section in `shared-data/credentials.md`
3. Include: service name, username (if applicable), the credential, and any relevant URLs/hosts
4. Confirm to the user that the credential was saved

**Format example:**
```markdown
### Service Name
- **Host:** hostname or URL
- **Username:** user
- **Password/Token:** the_credential
- **Notes:** any context (e.g., "generated 2025-12-16")
```

**Do this IMMEDIATELY - do not wait until end of session. No credential should ever be lost.**

---

## Credentials & Auth Reference

**PRIMARY SOURCE:** `shared-data/credentials.md` - Consolidated credentials file for all services
- SSH passwords for Jupiter, Saturn, pfSense
- API tokens (Gitea, Cloudflare, NPM)
- Database credentials (GuruRMM, client sites)
- Service URLs and ports

**ALWAYS check this file first** when needing authentication info.

## Context Recovery

**When the user references previous work, conversations, or context, check these sources:**

1. **Credentials:** `shared-data/credentials.md` - All auth info consolidated here
2. **Session logs:** `session-logs/` directory - Detailed work history
3. **Search for context:** Use grep/search to find relevant keywords

**Information stored includes:**
- Credentials and API keys (UNREDACTED for internal use)
- Server/host information (IPs, ports, hostnames)
- Configuration changes made
- Important commands and their results
- Decisions made in previous sessions
- Unfinished/pending tasks

**Example usage:**
- User says "use the cloudflare key from before" → Check `shared-data/credentials.md`
- User says "connect to the server we set up" → Check credentials.md for SSH info
- User says "continue where we left off" → Read most recent session log

## Infrastructure Reference

### SSH Hosts (from ~/.ssh/config)
| Alias | Host | User | Port |
|---|---|---|---|
| pfsense | 172.16.0.1 | admin | 2248 |
| jupiter | 172.16.3.20 | root | 22 |
| saturn | 172.16.3.21 | root | 22 |

### Key Servers
- **Jupiter** (172.16.3.20) - Unraid, primary container host (Gitea, NPM, GuruRMM)
- **Saturn** (172.16.3.21) - Unraid, secondary/migration source
- **pfSense** (172.16.0.1) - Firewall, Tailscale gateway

### Common Services
- **Gitea:** https://git.azcomputerguru.com/ (internal: 172.16.3.20:3000)
- **NPM:** Admin at 172.16.3.20:7818, HTTP/HTTPS on 1880/18443
- **GuruRMM API:** https://rmm-api.azcomputerguru.com (172.16.3.20:3001)

## Slash Commands

### /save or /s
Saves complete session context to `session-logs/YYYY-MM-DD-session.md`. Includes:
- Complete summary of work done
- ALL credentials, API keys, tokens (unredacted)
- All server/host information
- All commands run and their outputs
- Decisions made and rationale
- Errors encountered and resolutions
- Pending/incomplete tasks

### /context
Searches session logs for relevant context when user references previous work.

### /sync
Commits and pushes changes to Gitea remote.

---

## Per-Project Planning

### Workflow
1. **Active planning** uses `.claude/plans/` (system default)
2. **On completion**, archive the plan to the project directory as `PLAN.md`
3. **Future sessions** reference archived plans for context

### Archive Locations
```
/home/guru/claude-projects/gururmm/PLAN.md
/home/guru/claude-projects/mailprotector-config/PLAN.md
/home/guru/claude-projects/dataforth/PLAN.md
/home/guru/claude-projects/[project]/PLAN.md
```

### When to Archive
Archive the active plan when:
- Implementation is complete
- Switching to a different project
- Plan is approved but work will continue later
- Session is ending with incomplete work

### Archive Command
After exiting plan mode, run:
```bash
cp /home/guru/.claude/plans/*.md /home/guru/claude-projects/[project]/PLAN.md
```

Or Claude will do this automatically when:
- User says "archive the plan" or "save the plan"
- A project switch is detected
- Session save (/save) is triggered

### Plan File Contents
Archived plans should include:
- Overview and goals
- Implementation steps (completed and pending)
- Key decisions made
- Files modified
- Testing notes
- Next steps (if incomplete)

### Recovering Context
When resuming a project:
1. Check for `PLAN.md` in the project directory
2. Read to understand previous work and pending tasks
3. Continue from where left off or start new plan if needed

---

## Best Practices

1. **Always save context frequently** - Use /save before long operations or context limits
2. **Check existing context first** - Before asking user for info, check session logs
3. **Store ALL credentials** - Session logs are the source of truth for credentials
4. **Track infrastructure changes** - Document any server/config changes
5. **Note pending tasks** - Future sessions should know what's incomplete

## Projects

This repository contains session logs and shared configuration for multiple projects including:
- GuruRMM (custom RMM system)
- MSP Toolkit (integrated CLI for MSP operations)
- Website2025 (web development projects)
- Various infrastructure automation

Each project may have its own CLAUDE.md with project-specific guidance.

---

## OPTIMIZATION PASS REQUIRED

**Status:** Pending
**Priority:** High
**Requested:** 2025-12-16

### Tasks for All Machines

When starting a session, perform these optimization tasks:

#### 1. Repository Cleanup
- [ ] Ensure all git remotes point to Gitea (`git.azcomputerguru.com`), not GitHub
- [ ] Remove any stale GitHub references
- [ ] Verify repos are properly synced with Gitea

#### 2. Credential Consolidation
- [ ] All credentials should be in `shared-data/credentials.md`
- [ ] Git credentials accessible via API token (see credentials.md)
- [ ] SSH keys consistent across machines

#### 3. Project Organization
- [ ] Each project has proper CLAUDE.md
- [ ] Session logs are up to date
- [ ] No orphaned files or configurations

#### 4. Machine-Specific Verification
| Machine | Tasks |
|---------|-------|
| Mac (ACG-M-L5090) | Verify osxkeychain has Gitea creds, SSH keys working |
| Windows/WSL | Verify git-credential-store, SSH keys in ~/.ssh |
| Ubuntu Server (172.16.3.30) | Verify Gitea clone access, build tools working |

### Current Gitea Repositories
- `azcomputerguru/gururmm` - RMM system (Rust server, React dashboard, Rust agent)
- `azcomputerguru/claude-projects` - Claude Code workspace, session logs, shared data

### Pending Work (from gururmm)
- Build and deploy updated agent with extended metrics (uptime, public IP, idle time)
- Agent source is updated but needs to be built on Ubuntu server (172.16.3.30)
- Server and dashboard already deployed with extended metrics support