# During session, you run:
ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && rm -rf .next && npm run build'

# Auto-update CLAUDE.md:
## Quick Commands > Frontend > Build
# Clear cache and rebuild
ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && rm -rf .next && npm run build'

# Discovered: NEXT_PUBLIC_NODE_ENV required for production
# Auto-update: CLAUDE.md > Environment Variables section

# Found: authStore initializes with mock user
# Auto-create: SECURITY_AUDIT_[DATE].md
# Auto-update: CLAUDE.md > Security > Known Issues

# Created: .claude/skills/pix-validation/SKILL.md
# Auto-update: CLAUDE.md > Available Skills section

# Old way: Manual file transfer
# New way: rsync with specific flags
# Auto-update: CLAUDE.md > Deployment section

interface UpdateTrigger {
  type: 'command' | 'config' | 'security' | 'skill' | 'workflow';
  source: string;              // Where was this discovered?
  content: string;             // What should be documented?
  priority: 'low' | 'medium' | 'high' | 'critical';
  relatedFiles: string[];      // Which files are affected?
}

Is it a quick command/reference?
  YES → Update CLAUDE.md > Quick Commands
  NO → Continue

Is it detailed technical knowledge?
  YES → Update or create SKILL.md
  NO → Continue

Is it a security issue?
  YES → Create SECURITY_AUDIT_[DATE].md + update CLAUDE.md
  NO → Continue

Is it project-specific documentation?
  YES → Update README.md or docs/
  NO → Log for future review

## Section Title

### Subsection (if needed)

**Description:** Brief explanation of what/why

**Command/Pattern:**
```bash
# Comment explaining what this does
command here

**SKILL.md Updates:**
```markdown
## Version History

- **1.1.0** (2025-10-16): [Description of update]
  - Added: Feature X
  - Fixed: Issue Y
  - Updated: Section Z

# Auto-commit documentation updates
git add CLAUDE.md .claude/skills/
git commit -m "docs: auto-update from session [SESSION_ID]

- Added: [brief description]
- Updated: [sections modified]
- Source: [what triggered update]

Co-Authored-By: Claude <noreply@anthropic.com>"

# CLAUDE.md

**Last Updated:** YYYY-MM-DD
**Location:** `/Users/lucascardoso/Desktop/MUTUA/`
**Auto-Update Enabled:** ✅

---

## 🎯 Project Overview
[Brief description, tech stack]

## 🚀 Quick Start Commands
[Most common commands for dev/deploy]

## 🏗️ Architecture
[High-level system design]

## 🔐 Security
[Critical security considerations]

## 📋 Available Skills
[List of SKILL.md files with descriptions]

## ⚙️ Configuration
[Environment variables, important settings]

## 🐛 Troubleshooting
[Common issues and solutions]

## 📚 Documentation References
[Links to detailed docs]

## 🔄 Version History
[Track major CLAUDE.md changes]

The MutuaPIX platform uses a comprehensive authentication system
that leverages Laravel Sanctum on the backend for secure token-based
authentication while the frontend utilizes Next.js with Zustand for
state management and localStorage for token persistence...

## Authentication

**Stack:** Laravel Sanctum (backend) + Zustand (frontend)
**Token Lifetime:** 24 hours
**Login Flow:** CSRF token → POST /api/v1/login → Store JWT

**Quick Test:**
```bash
curl https://api.mutuapix.com/api/v1/health

## Skills Discovery

When Claude needs to find a skill:

```bash
# List all available skills
ls -la .claude/skills/

# Search skills by keyword
grep -r "PIX validation" .claude/skills/*/SKILL.md

# Read specific skill
cat .claude/skills/pix-validation/SKILL.md

# During debugging, discovered NEXT_PUBLIC_NODE_ENV is required

## Environment Variables

### Frontend Production (.env.production on VPS)

```bash
NEXT_PUBLIC_NODE_ENV=production          # ⚠️ CRITICAL: Required for security
NEXT_PUBLIC_API_URL=https://api.mutuapix.com
NEXT_PUBLIC_USE_AUTH_MOCK=false

### Example 2: New Deployment Command

**Trigger:**
```bash
# Discovered that clearing .next cache is required for env var changes
ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && rm -rf .next && npm run build && pm2 restart mutuapix-frontend'

## Deployment

### Frontend Deployment (Environment Variable Changes)

**⚠️ IMPORTANT:** When updating `.env.production`, must clear cache before rebuild!

```bash
# 1. Update .env.production on VPS
ssh root@138.199.162.115 'echo "NEXT_PUBLIC_NODE_ENV=production" >> /var/www/mutuapix-frontend-production/.env.production'

# 2. Clear cache + rebuild + restart
ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && rm -rf .next && npm run build && pm2 restart mutuapix-frontend'

# 3. Verify
curl -I https://matrix.mutuapix.com/login

### Example 3: Security Issue Found

**Trigger:**
```typescript
// Discovered: authStore has default mock user
// File: frontend/src/stores/authStore.ts:91-96
user: devLocalUser,           // ❌ VULNERABILITY

## Security

### Known Issues

**🔴 CRITICAL: Default Mock User in authStore** (Found: 2025-10-16)

**Issue:** `authStore` initializes with authenticated mock admin user by default.

**Risk:** If localStorage is empty, user appears logged in without credentials.

**Fix:** See `AUTHENTICATION_AUDIT_REPORT.md` Section "Remediation Plan > Phase 1"

**Status:** 🟡 Pending fix

**Related Files:**
- `frontend/src/stores/authStore.ts:91-96`
- `.claude/skills/authentication-management/SKILL.md`

interface DocHealthMetrics {
  claudeMdSize: number;              // Bytes (target: <50KB)
  skillsCount: number;               // Number of SKILL.md files
  lastUpdated: Date;                 // Most recent update
  staleSections: string[];           // Sections >90 days old
  brokenLinks: string[];             // Dead file references
  todoItems: number;                 // Unresolved TODOs in docs
}