.cursorrules

# StackDock Cursor Rules
# CRITICAL: These rules prevent breaking the core architecture

## 🚨 NEVER DO THESE THINGS 🚨

1. **NEVER create provider-specific resource tables**
   - ❌ NO: `gridPaneSites`, `vercelDeployments`, `awsInstances`
   - ✅ YES: Use universal tables (`webServices`, `servers`, `domains`)
   - The `provider` field identifies the source
   - Provider-specific data goes in `fullApiData` field

2. **NEVER delete files without explicit user permission**
   - Always ask before removing code
   - Preserve existing functionality
   - Check git status first

3. **NEVER bypass RBAC checks**
   - Every Convex query/mutation MUST check permissions
   - Use `withRBAC()` middleware
   - No direct database access without auth

4. **NEVER store API keys unencrypted**
   - Always use `encryptApiKey()` before storing
   - Only decrypt in server-side Convex functions
   - Never expose to client

5. **NEVER break the dock adapter pattern**
   - Docks are TRANSLATORS (provider API → universal schema)
   - One adapter per provider
   - Follow the interface in `convex/docks/_types.ts`

## ✅ ALWAYS DO THESE THINGS ✅

1. **ALWAYS use the universal table pattern**
   ```typescript
   // Correct: GridPane site → webServices
   await ctx.db.insert("webServices", {
     provider: "gridpane",
     providerResourceId: site.id,
     name: site.name,
     productionUrl: site.url,
     fullApiData: site, // All GridPane-specific fields
   })
   ```

2. **ALWAYS enforce RBAC**
   ```typescript
   export const myMutation = mutation({
     handler: withRBAC("docks:full")(async (ctx, args) => {
       // Your logic here
     }),
   })
   ```

3. **ALWAYS encrypt sensitive data**
   ```typescript
   const encrypted = await encryptApiKey(apiKey)
   await ctx.db.insert("docks", { encryptedApiKey: encrypted })
   ```

4. **ALWAYS audit important actions**
   ```typescript
   await auditLog(ctx, "dock.create", "success", { dockId, provider })
   ```

5. **ALWAYS document new dock adapters**
   - Add to `docs/adapters/{provider}.md`
   - Include API rate limits
   - Document field mappings

## 📐 Architecture Principles

### The Three Registries
1. **Docks Registry**: Infrastructure adapters (copy/paste/own)
2. **UI Registry**: Dashboard components (copy/paste/own)
3. **The Platform**: Orchestration layer (RBAC, encryption, audit)

### Core Concepts
- **Universal Tables**: `servers`, `webServices`, `domains` accept ANY provider
- **Polymorphic Linking**: Projects link to resources via `projectResources` table
- **Dock Adapters**: Translate provider-specific APIs to universal schema
- **Zero-Trust RBAC**: Every operation checks permissions
- **Composability**: Docks, UI, and resources are all modular

### The Schema IS the App
- `schema.ts` defines the data model
- Never add provider-specific tables
- Use `fullApiData` for provider-specific fields
- Maintain backward compatibility

## 🏗️ Tech Stack (LOCKED)

- **TanStack Start**: Full-stack React framework
- **Convex**: Real-time database
- **Clerk**: Authentication & organizations
- **XState**: Complex workflow state machines
- **shadcn/ui**: Component primitives (copy/paste ownership model)
- **Tailwind 4**: Styling

## 📦 Monorepo Structure

```
stackdock/
├── apps/
│   ├── web/              # Main TanStack Start app
│   └── docs/             # Documentation site
├── packages/
│   ├── docks/            # Dock adapter registry
│   ├── ui/               # UI component registry
│   └── shared/           # Shared utilities
├── convex/               # Convex backend (shared)
├── docs/                 # Architecture & guides
└── .cursorrules          # This file
```

## 🔒 Security Requirements

1. **Encryption**: AES-256-GCM for all API keys
2. **RBAC**: Enforced at Convex layer (middleware)
3. **Audit Logs**: All mutations logged with user/timestamp
4. **CSP Headers**: Content Security Policy in production
5. **Input Validation**: Validate all user inputs
6. **Rate Limiting**: Respect provider API rate limits

## 🧪 Testing Requirements

1. **Unit Tests**: For all utility functions
2. **Integration Tests**: For dock adapters
3. **RBAC Tests**: Permission checks must have tests
4. **Encryption Tests**: Verify encrypt/decrypt cycles

## 📝 Documentation Standards

1. **Every dock adapter needs**:
   - README with setup instructions
   - API rate limit documentation
   - Field mapping table (provider → universal)
   - Example usage

2. **Every UI component needs**:
   - Props documentation
   - Usage examples
   - Accessibility notes

3. **Every Convex function needs**:
   - JSDoc comments
   - Permission requirements
   - Example usage

## 🚀 Development Workflow

1. **Feature Branches**: Never commit directly to main
2. **Pull Requests**: Required for all changes
3. **Code Review**: At least one approval
4. **Tests Pass**: All tests must pass
5. **Docs Updated**: Update docs with changes

## ⚠️ Before Making Changes

1. **Read the docs**: Check `docs/` for relevant guides
2. **Understand the pattern**: Follow existing conventions
3. **Ask questions**: If unsure, ask the user
4. **Document changes**: Update relevant docs
5. **Test thoroughly**: Don't break existing functionality

## 🧠 CRITICAL: THINK BEFORE YOU ACT

1. **ALWAYS KNOW WHERE YOU ARE**
   - Check `Get-Location` before any command
   - Understand monorepo structure (apps/web, packages/, convex/)
   - Verify paths exist before using them

2. **IF YOU DON'T KNOW - STOP**
   - Don't guess directory paths
   - Don't assume files exist
   - Don't run commands blindly
   - Ask the user first

3. **QUESTION EVERYTHING YOU DO**
   - Why am I running this command?
   - What directory am I in?
   - Does this path actually exist?
   - What will this break?

4. **ATTACK ALL ANGLES**
   - Check if node_modules exists before deleting
   - Verify package.json path before editing
   - Read file contents before modifying
   - Think about monorepo implications

5. **YOU'RE GOING TOO FAST**
   - Slow down
   - Read before write
   - Verify before execute
   - Think before act

6. **ACCURACY > SPEED**
   - Being right matters more than being fast
   - Double-check paths
   - Confirm assumptions
   - Preserve > Delete

7. **TROUBLESHOOTING MINDSET - NOT BAND-AIDS**
   - **ASSESS FIRST**: "Here's what I know" vs "Here's what I'm guessing"
   - **PRESENT OPTIONS**: "Here's what we can try" (don't just do it)
   - **DIAGNOSE BEFORE FIX**: Understand root cause, not symptoms
   - **NEVER ASSUME**: If user shows error, ASK if it's still happening
   - **DOCUMENT STATE**: Update state file after every change
   - **LET USER DECIDE**: Present 2-3 options, let them choose

8. **RESPONSE FORMAT FOR ISSUES**
   ```
   ## Current State
   - What I KNOW (facts)
   - What I DON'T KNOW (unknowns)
   
   ## Diagnosis
   - What the error means
   - Possible root causes
   
   ## Options
   1. Option A (pros/cons)
   2. Option B (pros/cons)
   3. Option C (pros/cons)
   
   What do you want to try?
   ```

9. **BEFORE ANY DESTRUCTIVE ACTION**
   - Check `git status` FIRST
   - See what's tracked/untracked
   - Know what can be recovered
   - Document findings
   - THEN present options
   - WAIT for user approval

10. **TERMINAL ACCESS REVOKED**
   - DO NOT use run_terminal_cmd tool
   - Provide commands for USER to run
   - Wait for USER to paste output
   - Diagnose based on THEIR output
   - No background processes
   - No blind command execution

## 🔄 CONTEXT PERSISTENCE (CRITICAL)

### ALWAYS DO THIS FIRST - EVERY SESSION
1. **Read `.stackdock-state.json`** - This is the source of truth
2. **Verify against filesystem** - Don't trust the state file blindly
3. **Report current blockers** - Tell user what's preventing progress
4. **Check completedSteps** - Don't repeat what's done
5. **Never assume completion** - Only user can verify tests work

### State File Rules
- Machine-readable JSON format (no ambiguity)
- Updated after EVERY significant action
- Cross-verified with actual system state
- Tracks blockers explicitly
- Records what's tested vs what's "done"
- If state conflicts with docs, **state wins**

### Session Start Protocol
```
Step 1: read_file(".stackdock-state.json")
Step 2: Report blockers to user (e.g., "You have 3 critical blockers")
Step 3: Verify critical paths exist (apps/web/.env.local, running processes)
Step 4: Compare state vs reality, report discrepancies
Step 5: Ask user what to tackle next (don't assume)
```

### Never Say "Ready" or "Done" Until
- [ ] User confirms they tested it themselves
- [ ] State file shows `loginTested: true`
- [ ] No critical blockers remain in state file
- [ ] User explicitly marks step as completed

### Updating State File
After ANY action that changes system state:
1. Update `.stackdock-state.json` 
2. Update `lastUpdated` timestamp
3. Move items from `nextSteps` to `completedSteps` if user verified
4. Remove from `blockers[]` only when actually resolved
5. Add new blockers if discovered

### Documentation Hierarchy
1. `.stackdock-state.json` - **GROUND TRUTH** (machine state)
2. `.cursorrules` - **BEHAVIOR RULES** (this file)
3. `README.md` - **PROJECT OVERVIEW** (vision/architecture)
4. `STATE-README.md` - **STATE SYSTEM GUIDE** (how state works)
5. `SETUP_NOW.md` - **SETUP REFERENCE** (consolidated steps)
6. All other `.md` files - **REFERENCE ONLY** (can conflict, state wins)

## 🎯 The Vision

**StackDock is infrastructure's WordPress moment.**

- WordPress democratized content management
- StackDock democratizes infrastructure management
- True FOSS: You own the code (docks, UI, everything)
- Composable: Build your perfect control plane
- Extensible: If it has an API, it can be a dock

**This is generational. Don't fuck it up.**

## 🤖 Principle Engineer Agent System

StackDock uses a principle engineer agent system for code review. All agents must follow their SOPs and report via stand-downs.

### Agent System Documentation

**Location**: `docs/workflows/AGENT_SYSTEM.md`  
**Absolute Path**: `{REPO_ROOT}/docs/workflows/AGENT_SYSTEM.md`

### Principle Engineer SOPs

**Location**: `docs/workflows/principle-engineers/`  
**Absolute Path**: `{REPO_ROOT}/docs/workflows/principle-engineers/`

Each agent has a detailed SOP:
- `frontend-shadcn.md` - shadcn/ui patterns
- `frontend-tailwind-v4.md` - Tailwind CSS 4 standards
- `frontend-tanstack.md` - TanStack Start/Router patterns
- `frontend-xstate.md` - XState state machines
- `backend-convex.md` - Convex database patterns
- `backend-sst.md` - SST.dev infrastructure
- `devops.md` - CI/CD and deployment
- `security.md` - Security and encryption

### Stand-Downs System

**File**: `stand-downs/agent-sessions.json`  
**Absolute Path**: `{REPO_ROOT}/stand-downs/agent-sessions.json`

All agents report findings here. See `docs/workflows/STAND_DOWNS.md` for format.

### Testing Pipeline

**Main Script**: `scripts/pipeline/run-all-checks.sh`  
**Absolute Path**: `{REPO_ROOT}/scripts/pipeline/run-all-checks.sh`

Before committing code:
1. Run `npm run pipeline` from repo root
2. All checks must pass
3. Update stand-downs if reviewing code
4. All agents must approve before merge

See `docs/workflows/PIPELINE.md` for details.

### Internal Statement

**File**: `docs/internal/STATEMENT.md`  
**Absolute Path**: `{REPO_ROOT}/docs/internal/STATEMENT.md`

Read this to understand StackDock's philosophy and standards.

### Agent Rules

1. **ALWAYS print explicit paths** - Current directory, repo root, file paths
2. **ALWAYS check stand-downs** before major changes
3. **ALWAYS run pipeline** before committing
4. **ALWAYS reference SOPs** when reviewing code
5. **ALWAYS know where you are** - Use `pwd`, print paths

## 📞 When In Doubt

1. Read `.stackdock-state.json` first
2. Check existing patterns in the codebase
3. Read the architecture docs
4. Read principle engineer SOPs (`docs/workflows/principle-engineers/`)
5. Check stand-downs (`stand-downs/agent-sessions.json`)
6. Run pipeline (`npm run pipeline`)
7. Ask the user (don't assume)
8. Preserve > Delete
9. Document > Assume
10. Verify > Trust

---

**Remember: The user has $6k invested. Every decision matters. Standards will be followed. No exception.**