vibecarbon 0.1.0

package/carbon/AGENTS.md

@@ -0,0 +1,422 @@
+# AGENTS.md
+
+Guidance for AI coding agents working on this codebase. The **Security Rules** section below is mandatory — violations introduce real vulnerabilities.
+
+## Tech Stack
+
+- **Frontend**: React 19, Vite, React Router, TanStack Query, Shadcn UI, Tailwind CSS v4, i18next
+- **Backend**: Hono (lightweight Node.js framework), Pino logger, Zod validation, nodemailer (SMTP email)
+- **Auth/Database**: Self-hosted Supabase (PostgreSQL, Auth, REST API, Realtime, Storage)
+- **Billing**: Stripe (subscriptions, checkout, webhooks, plan gating)
+- **Content**: MDX (blog, changelog, docs) with remark/rehype plugins
+- **Tooling**: Biome (lint/format), TypeScript, esbuild, Vitest
+
+## Commands
+
+```bash
+# Development
+pnpm dev:start          # Full cold start: Docker + migrations + dev servers
+pnpm dev                # Start API (port 3000) and Vite (port 5173)
+pnpm dev:reset          # Remove containers, volumes, and built images
+
+# Build & Test
+pnpm build              # Build client and server
+pnpm lint               # Biome linting
+pnpm typecheck          # TypeScript type checking
+pnpm test               # Run every tier (unit + component + integration)
+pnpm test:unit          # Pure functions, validators, shared lib
+pnpm test:component     # React components + hooks (RTL + jsdom)
+pnpm test:integration   # Hono routes with mocked Supabase/Stripe/SMTP
+pnpm test:watch         # Vitest watch mode
+pnpm test:coverage      # Generate coverage/ report (v8)
+pnpm test:prepush       # What the pre-push git hook runs
+
+# Docker
+pnpm docker:up          # Start Supabase services
+pnpm docker:down        # Stop services
+pnpm docker:reset       # Remove containers, volumes, and built images
+pnpm db:migrate         # Run SQL migrations
+```
+
+## Architecture
+
+### Directory Structure
+```
+src/
+├── client/                  # React SPA (Vite dev server on :5173)
+│   ├── components/
+│   │   ├── ui/              # 50+ Shadcn UI components
+│   │   └── auth/            # AuthProvider, ProtectedRoute
+│   ├── hooks/               # Custom React hooks
+│   ├── pages/               # Route pages (admin/, settings/, organizations/)
+│   ├── lib/                 # supabase.ts, i18n.ts, utils.ts, blog/changelog/docs loaders
+│   └── locales/             # i18n translation files
+├── server/                  # Hono API (Node.js on :3000)
+│   ├── index.ts             # App entry, middleware, route mounting
+│   ├── routes/              # health.ts, v1/, webhooks/, _internal/
+│   ├── emails/              # React Email templates
+│   └── lib/                 # supabase.ts, env.ts, email.ts, stripe.ts, logger.ts, rate-limiter.ts
+├── shared/                  # Shared TypeScript types (types.ts, pricing.ts)
+content/                     # MDX content (blog/, changelog/, docs/)
+supabase/migrations/         # SQL migrations (run with pnpm db:migrate)
+```
+
+### API Routes
+
+| Route | Description |
+|-------|-------------|
+| `GET /api/health` | Liveness probe (no DB check, public) |
+| `GET /api/health/ready` | Readiness probe (checks DB connectivity, public) |
+| `POST /api/v1/auth/login` | Email/password login with lockout protection |
+| `GET /api/v1/auth/settings` | Auth settings (enabled providers, MFA config) |
+| `GET /api/v1/me` | Current user info with memberships |
+| `GET/POST /api/v1/organizations` | List/create organizations |
+| `GET/POST /api/v1/organizations/:orgId/members` | Manage members |
+| `PATCH /api/v1/organizations/:orgId/members/:userId` | Update member role |
+| `GET /api/v1/notifications` | User's active notifications |
+| `POST /api/v1/notifications/:id/dismiss` | Dismiss notification |
+| `POST /api/v1/billing/checkout` | Create checkout session (Stripe/Paddle/Polar) |
+| `POST /api/v1/billing/portal` | Create customer portal session |
+| `POST /api/v1/contact/submit` | Submit contact form (public, rate-limited) |
+| `POST /api/v1/newsletter/subscribe` | Subscribe to newsletter (public, rate-limited) |
+| `GET /api/v1/newsletter/confirm` | Confirm newsletter subscription (via email token) |
+| `GET /api/v1/newsletter/unsubscribe` | Unsubscribe from newsletter |
+| `GET /api/v1/admin/users` | List all users (super admin) |
+| `GET /api/v1/admin/organizations` | List all organizations (super admin) |
+| `POST /api/v1/admin/impersonate/:userId` | Impersonate user (super admin) |
+| `GET/POST /api/v1/admin/notifications` | Manage notifications (super admin) |
+| `GET /api/v1/admin/stats` | Platform-wide stats (super admin) |
+| `GET /api/v1/admin/performance` | Service performance/health checks (super admin) |
+| `GET /api/v1/admin/jobs` | Background jobs and execution history (super admin) |
+| `POST /api/v1/admin/jobs/trigger` | Manually trigger a background job (super admin) |
+| `GET/PATCH/DELETE /api/v1/admin/contact` | Manage contact submissions (super admin) |
+| `GET /api/v1/admin/newsletter` | Manage newsletter subscribers (super admin) |
+| `POST /api/v1/admin/newsletter/send` | Send newsletter to active subscribers (super admin) |
+| `GET /api/v1/admin/newsletter/export` | Export subscribers as CSV (super admin) |
+| `GET /api/_internal/verify-role` | Traefik ForwardAuth |
+| `POST /api/webhooks/billing` | Billing webhook handler (Stripe/Paddle/Polar) |
+| `POST /api/webhooks/stripe` | Stripe webhook handler (backward compat) |
+| `GET /api/docs` | Scalar API reference (dev only) |
+
+### Authentication Flow
+
+1. **Client-side**: Supabase JS handles auth (email/password, OAuth, magic links, MFA)
+2. **API requests**: Client sends JWT in `Authorization: Bearer <token>` header
+3. **Server middleware**: Extracts token, calls `supabase.auth.getUser()`, sets `c.get('user')`
+4. **RLS**: Database queries respect row-level security based on authenticated user
+
+## Supabase Client Usage
+
+This is the #1 source of bugs. Three clients exist:
+
+**Client-side** (`src/client/lib/supabase.ts`) — uses anon key, RLS enforced:
+```typescript
+import { supabase } from '@/lib/supabase';
+const { data } = await supabase.from('organizations').select('*'); // RLS enforced
+```
+
+**Server-side** (`src/server/lib/supabase.ts`) — two options:
+```typescript
+// User-context queries (respects RLS) — use for most routes
+const supabase = c.get('supabase');
+
+// Admin operations (bypasses RLS) — use only when necessary
+import { supabaseAdmin } from '@/server/lib/supabase';
+
+// Auth operations — NEVER use supabaseAdmin for signInWithPassword
+// (stores session state on singleton, contaminates subsequent queries)
+import { createAuthClient } from '@/server/lib/supabase';
+const authClient = createAuthClient();
+```
+
+## Key Patterns
+
+### Adding an API Endpoint
+
+1. Create route in `src/server/routes/v1/` — follow existing routes for the `Variables` type, Zod validation, and auth check pattern
+2. Mount in `src/server/index.ts`: `app.route('/api/v1/items', myRoutes)`
+
+### Adding a Page
+
+1. Create component in `src/client/pages/` — use `SidebarProvider` + `AppSidebar` + `SidebarInset` layout (see existing pages)
+2. Add route in `src/client/App.tsx` wrapped in `<ProtectedRoute>`
+
+### Adding a Database Table
+
+1. Create migration in `supabase/migrations/` with:
+   - Table with `id UUID PRIMARY KEY DEFAULT gen_random_uuid()`, `created_at`, `updated_at`
+   - Index on foreign key columns
+   - `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`
+   - RLS policies using `auth.uid()` for user-scoped access (see `00001_init.sql` for patterns)
+   - `update_updated_at()` trigger
+2. Run `pnpm db:migrate` and add types to `src/shared/types.ts`
+
+### Data Fetching (TanStack Query)
+
+**NEVER use raw `fetch` in `useEffect`** — always use `useQuery` for reads and `useMutation` for writes. Raw fetch in useEffect bypasses TanStack Query's deduplication, caching, and retry logic, and React StrictMode will double-fire it in development.
+
+```typescript
+// CORRECT: useQuery with auth guard
+const { data, isLoading } = useQuery({
+  queryKey: ['items', orgId],
+  queryFn: async () => {
+    const headers = await getAuthHeaders();
+    const res = await fetch(`/api/v1/items?orgId=${orgId}`, { headers });
+    if (!res.ok) throw new Error('Failed to fetch items');
+    return res.json();
+  },
+  enabled: !!user && !!orgId, // Skip fetch when unauthenticated or missing params
+});
+
+// WRONG: raw fetch in useEffect
+useEffect(() => {
+  fetch('/api/v1/items').then(r => r.json()).then(setItems);
+}, []);
+```
+
+Rules:
+- **Gate authenticated queries** with `enabled: !!user` (or `!!session`) to prevent 401s for logged-out users
+- **Use `getAuthHeaders()`** from `@/lib/api.ts` for auth headers — never duplicate it locally, never send empty `Authorization` headers
+- **Place reusable hooks** in `src/client/hooks/api/` — page-specific queries can live in the page file
+- **Invalidate related queries** after mutations: `queryClient.invalidateQueries({ queryKey: ['items'] })`
+- **Set `staleTime`** to control cache freshness (default is 5min via QueryClient config)
+
+## Database Schema
+
+| Table | Purpose |
+|-------|---------|
+| `organizations` | Multi-tenant organizations (name, slug, plan) |
+| `memberships` | User-org relationships (role: OWNER, ADMIN, MEMBER) |
+| `customers` | Billing customer records (user or org, any provider) |
+| `subscriptions` | Billing subscription data |
+| `notifications` | System-wide or org-specific notifications |
+| `notification_dismissals` | Track dismissed notifications per user |
+| `failed_login_attempts` | Brute force protection |
+| `app_settings` | Global app configuration |
+| `cron_job_history` | Background job execution history (pg_cron) |
+| `contact_submissions` | Contact form submissions (name, email, subject, message, status) |
+| `newsletter_subscribers` | Newsletter subscribers (email, status: pending/active/unsubscribed) |
+
+RLS helper functions: `get_user_org_ids()`, `get_user_admin_org_ids()`, `is_super_admin()`
+
+## Path Aliases
+
+- `@/*` resolves to `./src/client/*`
+- `@shared/*` resolves to `./src/shared/*`
+- `@server/*` resolves to `./src/server/*` (test-only — server code uses relative imports)
+- **Never use `@/shared/*`** — it won't resolve
+
+## Testing
+
+Three tiers — pick the narrowest one that exercises the regression you're worried about.
+
+| Tier | Env | What it covers | Where it lives |
+|---|---|---|---|
+| `unit` | node | Pure functions, validators, pricing/format/business helpers, structural invariants (e.g. i18n parity) | `tests/unit/`, `tests/structural/` |
+| `component` | jsdom | React components + custom hooks via React Testing Library | `tests/component/` |
+| `integration` | node | Hono route handlers end-to-end via `app.request()`, with Supabase/Stripe/SMTP mocked at the module boundary | `tests/integration/` |
+
+Helpers live in `tests/_helpers/`:
+
+- `app.ts` — `mountRoute(prefix, routes)` to build a tiny Hono app for one route; `jsonPost(body)` for request boilerplate.
+- `factories.ts` — `makeUser`, `makeOrg`, `makeContactSubmission` for plausible domain fixtures.
+- `jwt.ts` — `mockJwt(payload)` for HS256-signed test tokens.
+- `env.ts` — `mockEnv({...})` returning a restore closure (no globals).
+- `setup-rtl.ts` — vitest setup for the component project (jest-dom matchers + RTL cleanup).
+- `setup-integration.ts` — seeds plausible Supabase env values so server modules load without zod-validation errors.
+
+**Mocking conventions:**
+- Supabase: `vi.mock('@server/lib/supabase', () => ({ supabaseAdmin: { from: () => ({ insert: vi.fn() }) } }))`.
+- Stripe: `vi.mock('@server/lib/stripe', () => ({ stripe: { ... } }))`.
+- fetch (client side): `vi.stubGlobal('fetch', vi.fn(...))` + `vi.unstubAllGlobals()` in afterEach.
+- TanStack Query: wrap with a fresh `QueryClient` per render (`retry: false`) — see `tests/component/use-auth-settings.test.tsx`.
+- Rate limiter: `vi.mock('@server/lib/rate-limiter', () => ({ createRateLimiter: () => async (_c, next) => { await next(); } }))` — the real module starts a 60s setInterval at module load.
+
+See `TESTING.md` for the full guide. The `test-maintainer` agent reads the tier directories to learn project conventions and will follow them automatically.
+
+## Agent Orchestration
+
+This project uses Claude Code's agent teams with a **lead-coordinator** that orchestrates 4 specialist teammates:
+
+| Agent | Role | Quality Gate |
+|-------|------|-------------|
+| `lead-coordinator` | Decomposes tasks, delegates, synthesizes results | — |
+| `backend-engineer` | Backend APIs, database, Docker/K8s, server logic | `pnpm lint` + `pnpm typecheck` on idle |
+| `frontend-engineer` | Frontend pages, components, layouts, styling | `pnpm lint` + `pnpm typecheck` on idle |
+| `security-reviewer` | Security audit after backend/infra changes | — |
+| `test-maintainer` | Test writing after any meaningful code change | `pnpm test:unit` on task complete |
+
+**Typical workflow**: Use the lead-coordinator for complex multi-step tasks. It decomposes the work, spawns specialists in dependency order (migrations -> API -> security review -> frontend -> tests), and synthesizes results. For simple single-domain tasks, invoke the specialist directly.
+
+**Quality gates** are enforced via hooks in `.claude/hooks/`:
+- `teammate-idle-gate.sh` — lint + typecheck before backend/frontend engineers go idle
+- `task-completed-gate.sh` — unit tests must pass before QA marks a task complete
+
+**Configuration**: `.claude/settings.json` registers the hooks and the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var required for agent teams.
+
+## Important Notes
+
+- **Prefer existing patterns** — follow the established code style in existing routes/components
+- **Auth is handled by Supabase** — don't implement custom auth, use `supabase.auth.*` methods
+- **Add Shadcn components** with `pnpm dlx shadcn@latest add [component-name]`
+
+---
+
+# Security Rules (Mandatory)
+
+The rules below are mandatory — violations introduce real vulnerabilities. The three most critical:
+
+1. **Always check auth** — every endpoint must verify `c.get('user')` and return 401 if null
+2. **Always validate input** — use Zod schemas for all API request bodies before processing
+3. **Use `c.get('supabase')` for user data** — never use `supabaseAdmin` for queries shown to end users; it bypasses RLS
+
+## Database Security (RLS)
+
+- **MUST** enable RLS on every new table: `ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;`
+- **MUST** use `(SELECT auth.uid())` in RLS policies, not bare `auth.uid()` — the subquery form prevents the query planner from re-evaluating per row
+- **MUST** use `SECURITY DEFINER` + `SET search_path = ''` on all helper functions used in RLS policies
+- **NEVER** disable RLS on existing tables
+- **NEVER** use `USING (true)` as a policy for user data — every table needs real ownership checks
+- **NEVER** grant direct table access to `anon` or `authenticated` roles beyond what RLS policies allow
+
+### RLS Helper Functions
+
+Use these existing functions in policies instead of writing inline queries:
+
+| Function | Returns | Use When |
+|----------|---------|----------|
+| `get_user_org_ids()` | `SETOF UUID` | User needs access to any org they belong to |
+| `get_user_admin_org_ids()` | `SETOF UUID` | Only OWNER or ADMIN roles should have access |
+| `get_user_owner_org_ids()` | `SETOF UUID` | Only OWNER role should have access |
+| `get_user_customer_ids()` | `SETOF UUID` | Billing data — includes personal + org customers |
+| `is_super_admin()` | `BOOLEAN` | Platform-wide admin operations |
+
+### RLS Policy Pattern
+
+```sql
+-- Correct: subquery form
+CREATE POLICY "Users can view own data"
+  ON my_table FOR SELECT
+  USING (user_id = (SELECT auth.uid()));
+
+-- Correct: using helper function
+CREATE POLICY "Users can view org data"
+  ON my_table FOR SELECT
+  USING (organization_id IN (SELECT get_user_org_ids()));
+
+-- WRONG: bare function call (performance issue)
+CREATE POLICY "bad_policy"
+  ON my_table FOR SELECT
+  USING (user_id = auth.uid());
+```
+
+## API Route Security
+
+- **MUST** check authentication on every endpoint: `const user = c.get('user'); if (!user) return c.json({ error: 'Unauthorized' }, 401);`
+- **MUST** validate all input with Zod schemas before processing
+- **MUST** use `c.get('supabase')` for user-facing database queries — this client respects RLS
+- **MUST** validate redirect URLs against an allowlist — never redirect to arbitrary user-supplied URLs
+- **MUST** use `createAuthClient()` for `signInWithPassword()` operations — never use the `supabaseAdmin` singleton for auth flows (it stores session state and contaminates subsequent queries)
+- **MUST** verify webhook signatures before processing webhook payloads (Stripe uses `stripe.webhooks.constructEvent()`)
+- **NEVER** use `supabaseAdmin` for data shown to end users — it bypasses RLS
+- **NEVER** return raw database errors to clients — always return a generic error message
+
+### Supabase Client Selection
+
+| Client | Import / Access | RLS | Use For |
+|--------|----------------|-----|---------|
+| `c.get('supabase')` | Hono context (middleware-injected) | Enforced | All user-facing queries |
+| `supabaseAdmin` | `import { supabaseAdmin } from '@/server/lib/supabase'` | Bypassed | Admin operations, webhooks, background jobs |
+| `createAuthClient()` | `import { createAuthClient } from '@/server/lib/supabase'` | N/A | `signInWithPassword()` and other auth flows |
+
+### API Endpoint Pattern
+
+```typescript
+myRoutes.post('/', async (c) => {
+  // 1. Auth check
+  const user = c.get('user');
+  if (!user) return c.json({ error: 'Unauthorized' }, 401);
+
+  // 2. Input validation
+  const body = await c.req.json();
+  const result = schema.safeParse(body);
+  if (!result.success) {
+    return c.json({ error: result.error.issues.map(e => e.message).join(', ') }, 400);
+  }
+
+  // 3. Use RLS-enforced client
+  const supabase = c.get('supabase');
+  const { data, error } = await supabase.from('items').insert(result.data).select().single();
+
+  // 4. Generic error response
+  if (error) return c.json({ error: 'Failed to create item' }, 500);
+  return c.json({ item: data }, 201);
+});
+```
+
+## Privileged Services
+
+- **MUST** protect Studio, n8n, Metabase, and Grafana with Traefik ForwardAuth in production
+- **MUST** use Docker socket proxy in production — never mount `/var/run/docker.sock` directly into Traefik
+- **NEVER** expose internal Supabase services (Auth, PostgREST, Realtime, Storage) directly — they must go through Kong
+- **NEVER** remove ForwardAuth middleware from production compose files or Kubernetes manifests
+
+### Adding a New Admin Service
+
+1. Add Traefik ForwardAuth label in the service's compose config:
+   ```yaml
+   labels:
+     - "traefik.http.routers.myservice.middlewares=super-admin-auth@file"
+   ```
+2. Create a dev override file that disables the middleware for local development:
+   ```yaml
+   labels:
+     - "traefik.http.routers.myservice.middlewares="
+   ```
+3. Use `Host(\`myservice.localhost\`)` for the routing rule
+
+### ForwardAuth Middleware Reference
+
+| Middleware | Required Role | Used By |
+|-----------|--------------|---------|
+| `admin-auth` | `super_admin` | Studio, n8n, Metabase, Grafana (Kubernetes) |
+| `super-admin-auth` | `super_admin` | Studio, n8n, Metabase, Grafana (Docker Compose) |
+
+## Environment & Secrets
+
+- **NEVER** commit `.env`, `.env.local`, or any file containing secrets
+- **NEVER** hardcode secrets, API keys, or passwords in source code
+- **MUST** use the `VITE_` prefix for any environment variable that needs client-side access
+- **NEVER** expose `SUPABASE_SERVICE_ROLE_KEY` to the client — it bypasses all RLS
+- **MUST** validate all server environment variables in `src/server/lib/env.ts`
+
+## Rate Limiting
+
+Three tiers are configured in `src/server/index.ts`:
+
+| Route Pattern | Limit | Reason |
+|--------------|-------|--------|
+| `/api/v1/*` | 100/min per IP | Standard API endpoints |
+| `/api/webhooks/*` | 500/min per IP | External services (Stripe) send bursts |
+| `/api/_internal/*` | 1000/min per IP | Infrastructure calls (Traefik ForwardAuth) |
+
+When adding new route groups, assign an appropriate rate limit tier.
+
+## Infrastructure (Kubernetes)
+
+- **MUST** use deny-all NetworkPolicy as the default — explicitly allowlist each communication path
+- **MUST** set pod security context on all new deployments:
+  ```yaml
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    runAsGroup: 1000
+    readOnlyRootFilesystem: true
+    allowPrivilegeEscalation: false
+    capabilities:
+      drop:
+        - ALL
+  ```
+- **MUST** use `emptyDir` volumes for any writable paths (e.g., `/tmp`)
+- **NEVER** run application containers as root (init containers are the only exception)
+- **NEVER** add capabilities — drop ALL and don't add any back

package/carbon/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+See [AGENTS.md](./AGENTS.md) for all guidance on this codebase — tech stack, commands, architecture, API routes, Supabase client usage, key patterns, database schema, path aliases, agent orchestration, and mandatory security rules.

package/carbon/DEVELOPMENT.md

@@ -0,0 +1,187 @@
+# Template Development Guide
+
+This guide covers developing and testing the `carbon/` template directory locally.
+
+## Template Variable System
+
+The CLI replaces placeholders like `{{PROJECT_NAME}}` when users run `npx vibecarbon create`. However, these placeholders cause issues when testing locally because:
+
+1. Services may reject special characters (`{}`) in identifiers
+2. YAML parsers may fail on unquoted template syntax
+3. Services expect actual values, not placeholder strings
+
+### Solution: Dev File Pattern
+
+Every config file with template placeholders needs a corresponding dev file:
+
+```
+volumes/<service>/config.yml          # Template with {{PLACEHOLDERS}}
+volumes/<service>/config.dev.yml      # Dev file with hardcoded values
+```
+
+Override files mount dev configs during local development. The build system automatically loads them in the correct order:
+
+```
+docker-compose.yml                           # Base services
+docker-compose.{service}.yml                 # Optional service (e.g., observability)
+docker-compose.{service}.override.yml        # Service-specific dev overrides
+docker-compose.override.yml                  # Main dev overrides (loaded last)
+```
+
+**Important:** Services defined in optional compose files must have their dev overrides in a matching `{service}.override.yml` file, not the main override file. This prevents errors when running without that service.
+
+## Adding a New Service
+
+### Step 1: Create template config
+
+```yaml
+# volumes/myservice/config.yml
+name: {{PROJECT_NAME}}
+api_key: {{MYSERVICE_KEY}}
+```
+
+### Step 2: Generate dev config
+
+Run the dev file generator:
+
+```bash
+./scripts/generate-dev-configs.sh
+```
+
+Or manually create with hardcoded values:
+
+```yaml
+# volumes/myservice/config.dev.yml
+name: vibecarbon
+api_key: dev-key-not-for-production
+```
+
+### Step 3: Add override mount
+
+Add the volume mount to the appropriate override file based on **which service** the volume is mounted to:
+
+- If mounting to a service in `docker-compose.yml` (db, kong, etc.) → use `docker-compose.override.yml`
+- If mounting to a service in `docker-compose.{feature}.yml` → use `docker-compose.{feature}.override.yml`
+
+Example for a service in the base compose file:
+
+```yaml
+# docker-compose.override.yml
+services:
+  db:
+    volumes:
+      - ./volumes/db/myservice-init.dev.sql:/docker-entrypoint-initdb.d/init-scripts/95-myservice.sql:Z
+```
+
+Example for a service in an optional compose file:
+
+```yaml
+# docker-compose.observability.override.yml
+services:
+  grafana:
+    volumes:
+      - ./volumes/grafana/config.dev.yml:/etc/grafana/config.yml:ro
+```
+
+### Step 4: Add placeholder to CLI
+
+In `src/create.js`, add to the replacements map:
+
+```javascript
+['{{MYSERVICE_KEY}}', generateSecret()],
+```
+
+### Step 5: Test both paths
+
+```bash
+# Test local development
+pnpm dev:start:all
+
+# Test CLI generation
+cd .. && node src/cli.js create test-app -y \
+  --admin-email=test@example.com \
+  --admin-password=testpass123
+cd test-app && pnpm dev:start
+```
+
+## Current Dev File Mappings
+
+### Compose Override Files
+
+| Service Compose | Dev Override | Notes |
+|-----------------|--------------|-------|
+| `docker-compose.yml` | `docker-compose.override.yml` | Core services (db, kong, traefik) |
+| `docker-compose.observability.yml` | `docker-compose.observability.override.yml` | Grafana: volumes + no ForwardAuth |
+| `docker-compose.n8n.yml` | `docker-compose.n8n.override.yml` | n8n: no ForwardAuth |
+| `docker-compose.metabase.yml` | `docker-compose.metabase.override.yml` | Metabase: no ForwardAuth |
+
+### Volume Config Files
+
+| Template File | Dev File | Notes |
+|--------------|----------|-------|
+| `volumes/db/super-admin.sql` | `volumes/db/super-admin.dev.sql` | Admin credentials |
+| `volumes/grafana/provisioning/dashboards/dashboards.yml` | `...dashboards.dev.yml` | Folder UIDs |
+| `volumes/grafana/dashboards/*.json` | `volumes/grafana/dashboards.dev/*.json` | Dashboard UIDs |
+| `volumes/traefik/middlewares.yml` | `volumes/traefik/middlewares.dev.yml` | ForwardAuth uses host.docker.internal |
+
+## Automation
+
+### Generate all dev configs from templates
+
+```bash
+./scripts/generate-dev-configs.sh
+```
+
+This script:
+- Finds all template files with `{{PROJECT_NAME}}`
+- Generates corresponding `.dev` versions
+- Replaces common placeholders with dev values
+
+### Validate dev files exist
+
+```bash
+./scripts/validate-dev-configs.sh
+```
+
+Run this in CI to ensure new template files have dev counterparts.
+
+## Common Issues
+
+### Container not picking up new mounts
+
+After modifying `docker-compose.override.yml`, recreate the container:
+
+```bash
+# Wrong - doesn't apply new mounts
+docker compose restart myservice
+
+# Correct - recreates with new mounts
+docker compose up -d myservice
+```
+
+### Service rejecting config
+
+Check if the service has restrictions on:
+- Special characters in identifiers/UIDs
+- Required fields that can't be template placeholders
+- Strict YAML parsing that rejects `{{}}`
+
+### Template works but dev fails (or vice versa)
+
+Ensure both files have identical structure - only values should differ.
+
+### Admin services (n8n, Metabase, Grafana) in development
+
+In production, these services use Traefik ForwardAuth to require `super_admin` role. In development, ForwardAuth is disabled via service-specific override files:
+
+- `docker-compose.n8n.override.yml`
+- `docker-compose.metabase.override.yml`
+- `docker-compose.observability.override.yml`
+
+These override files set `traefik.http.routers.{service}.middlewares=` (empty) to remove the ForwardAuth requirement. Docker Compose labels are **additive**, so you must explicitly set the middleware label to empty to override it.
+
+**If you get 401 errors:**
+
+1. Ensure the override files are included in your compose command
+2. Force recreate the containers: `docker compose ... up -d --force-recreate n8n metabase grafana`
+3. Verify the router has no middlewares: `curl http://traefik.localhost/api/http/routers/n8n@docker | jq .middlewares`