vibecarbon 0.1.0

package/carbon/.github/workflows/deploy.yml

@@ -0,0 +1,346 @@
+name: Deploy
+
+# Phase 4 of the GitOps refactor (2026-04-20). Deploy is now driven by
+# GitHub Actions rather than the vibecarbon CLI applying manifests from a
+# local workstation. This keeps:
+#
+#   • Secrets in GitHub Environments (never committed, env-scoped).
+#   • Source of truth in the repo under k8s/.
+#   • Reconciliation via Flux (the cluster's own GitRepository +
+#     Kustomization watches the repo's main branch every minute).
+#
+# The CLI still creates the cluster (Pulumi) and bootstraps the first
+# workflow run — thereafter, `git push` is the deploy verb.
+#
+# Security note: all external-input interpolation flows through the
+# `env:` block rather than inline `${{ }}` in `run:` blocks, to avoid the
+# script-injection class of workflow CVEs. Secrets are written to files
+# via base64 when possible (kubeconfig) to avoid shell quoting hazards.
+
+on:
+  # No `push` trigger: this workflow requires a per-environment KUBECONFIG_B64
+  # secret which only exists after `vibecarbon deploy --k8s` has seeded the
+  # matching GitHub Environment. A `push` trigger would fail fast (kubectl
+  # connection refused) for every deploy, whether k8s or compose-only. The
+  # vibecarbon CLI invokes this workflow explicitly via the gh CLI
+  # (triggerDeployWorkflow in gitops-deploy.js) with the right environment,
+  # so manual dispatch is the only entry point.
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to deploy (dev / staging / prod)'
+        type: environment
+        required: true
+
+concurrency:
+  # Serialize per-environment so two pushes don't race against Flux's
+  # reconcile loop.
+  group: deploy-${{ inputs.environment || 'prod' }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write  # for future OIDC to cloud providers; not used today
+
+jobs:
+  apply-secrets:
+    # Reads env-specific secrets from GitHub Environments and applies them
+    # to the cluster as the `vibecarbon-secrets` Secret. Flux does NOT
+    # manage this Secret (no manifest in k8s/) so there's no drift.
+    name: Apply env secrets → cluster
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment || 'prod' }}
+    env:
+      KUBECONFIG: ${{ github.workspace }}/kubeconfig
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+        with:
+          # Pin to a specific minor; bump deliberately.
+          version: 'v1.32.0'
+
+      - name: Write kubeconfig from env secret
+        env:
+          KUBECONFIG_B64: ${{ secrets.KUBECONFIG_B64 }}
+        run: |
+          printf '%s' "$KUBECONFIG_B64" | base64 -d > "$KUBECONFIG"
+          chmod 600 "$KUBECONFIG"
+          kubectl version --client=true
+
+      - name: Ensure vibecarbon namespace exists
+        run: kubectl create namespace vibecarbon --dry-run=client -o yaml | kubectl apply -f -
+
+      # Apply the vibecarbon-secrets Secret. Server-side apply with a
+      # distinct field manager ensures Flux doesn't try to prune these
+      # fields later, and that rotations simply overwrite. Secret values
+      # are written via stdin heredoc using $ENV_VARS rather than
+      # `${{ secrets.X }}` interpolation (defense-in-depth).
+      - name: Apply vibecarbon-secrets Secret
+        env:
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          JWT_SECRET: ${{ secrets.JWT_SECRET }}
+          SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
+          HETZNER_API_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
+          SITE_URL: ${{ vars.SITE_URL }}
+        run: |
+          # `kubectl create secret --from-literal=KEY=VALUE` handles
+          # arbitrary VALUEs correctly (passes through Unix argv, no
+          # shell interpretation). `--dry-run -o yaml | kubectl apply`
+          # is the idempotent create-or-update pattern.
+          kubectl create secret generic vibecarbon-secrets \
+            --namespace=vibecarbon \
+            --from-literal=DB_PASSWORD="$DB_PASSWORD" \
+            --from-literal=JWT_SECRET="$JWT_SECRET" \
+            --from-literal=SUPABASE_ANON_KEY="$SUPABASE_ANON_KEY" \
+            --from-literal=SUPABASE_SERVICE_ROLE_KEY="$SUPABASE_SERVICE_ROLE_KEY" \
+            --from-literal=HETZNER_API_TOKEN="$HETZNER_API_TOKEN" \
+            --from-literal=CLOUDFLARE_API_TOKEN="$CLOUDFLARE_API_TOKEN" \
+            --from-literal=SMTP_PASSWORD="$SMTP_PASSWORD" \
+            --from-literal=SITE_URL="$SITE_URL" \
+            --dry-run=client -o yaml \
+          | kubectl apply --server-side --force-conflicts \
+              --field-manager=github-actions-deploy -f -
+
+      - name: Apply hetzner-api-token Secret (cert-manager-webhook-hetzner)
+        if: vars.DNS_PROVIDER == 'hetzner'
+        env:
+          HETZNER_API_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+        run: |
+          kubectl create namespace cert-manager --dry-run=client -o yaml | kubectl apply -f -
+          kubectl create secret generic hetzner-api-token \
+            --namespace=cert-manager \
+            --from-literal=api-token="$HETZNER_API_TOKEN" \
+            --dry-run=client -o yaml \
+          | kubectl apply --server-side --force-conflicts \
+              --field-manager=github-actions-deploy -f -
+
+      - name: Apply kube-system/hcloud Secret (CCM + CSI)
+        env:
+          HETZNER_API_TOKEN: ${{ secrets.HETZNER_API_TOKEN }}
+          HCLOUD_NETWORK_ID: ${{ vars.HCLOUD_NETWORK_ID }}
+        run: |
+          kubectl create secret generic hcloud \
+            --namespace=kube-system \
+            --from-literal=token="$HETZNER_API_TOKEN" \
+            --from-literal=network="$HCLOUD_NETWORK_ID" \
+            --dry-run=client -o yaml \
+          | kubectl apply --server-side --force-conflicts \
+              --field-manager=github-actions-deploy -f -
+
+  bootstrap-flux:
+    # Phase 4.3b.C of the GitOps refactor: idempotently install Flux +
+    # the flux-system Secret (Git auth) + the root GitRepository and
+    # Kustomizations that watch the customer's repo. Runs every deploy
+    # (safe — kubectl apply --server-side is a no-op when state matches).
+    #
+    # After this job succeeds, Flux is in charge of reconciling
+    # k8s/gitops/{supabase,cert-manager-webhook-hetzner}/ and k8s/base/
+    # from the main branch. The apply-secrets job is what keeps the
+    # per-env vibecarbon-secrets / hetzner-api-token / hcloud Secrets
+    # in sync with GitHub Environment secrets.
+    name: Bootstrap Flux + root Kustomization
+    needs: apply-secrets
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment || 'prod' }}
+    env:
+      KUBECONFIG: ${{ github.workspace }}/kubeconfig
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+        with:
+          version: 'v1.32.0'
+
+      - name: Write kubeconfig from env secret
+        env:
+          KUBECONFIG_B64: ${{ secrets.KUBECONFIG_B64 }}
+        run: |
+          printf '%s' "$KUBECONFIG_B64" | base64 -d > "$KUBECONFIG"
+          chmod 600 "$KUBECONFIG"
+
+      - name: Install Flux if not present
+        # FLUX_INSTALL_URL matches src/lib/deploy/k8s/index.js so the
+        # imperative path and GitOps path land on the same Flux version.
+        # Bumping here requires a matching bump there + a re-test.
+        run: |
+          if ! kubectl -n flux-system get deployment source-controller > /dev/null 2>&1; then
+            kubectl apply -f https://github.com/fluxcd/flux2/releases/download/v2.8.5/install.yaml
+            kubectl -n flux-system wait --for=condition=available \
+              deployment/source-controller deployment/kustomize-controller \
+              deployment/helm-controller deployment/notification-controller \
+              --timeout=5m
+          fi
+
+      # cert-manager + Traefik CRDs must be installed BEFORE the root
+      # Kustomization reconciles. k8s/base/traefik/ contains IngressRoute
+      # (traefik.io/v1alpha1) and Certificate (cert-manager.io/v1)
+      # resources; Flux's vibecarbon-base Kustomization will sit with
+      # "Ready=False: resource mapping not found" forever without the
+      # CRDs installed out-of-band.
+      #
+      # Under the pre-GitOps flow these were installed imperatively by
+      # applyKubernetesManifests before Flux was bootstrapped (see
+      # src/lib/deploy/k8s/index.js and the CERT_MANAGER_INSTALL_URL
+      # constant). The GitOps refactor moved Flux bootstrap here but
+      # left this step out — e2e run 2026-04-22 18:29 UTC showed
+      # vibecarbon-base timing out after 10m on exactly this.
+      #
+      # cert-manager v1.20.2 matches k8s/infra/kustomization.yaml +
+      # CERT_MANAGER_VERSION in src/lib/deploy/k8s/k3s.js; bump in lockstep.
+      - name: Install cert-manager + Traefik CRDs
+        run: |
+          kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.20.2/cert-manager.yaml
+          kubectl apply -k k8s/infra/traefik-crds/
+          kubectl -n cert-manager wait --for=condition=available \
+            deployment/cert-manager \
+            deployment/cert-manager-webhook \
+            deployment/cert-manager-cainjector \
+            --timeout=5m
+
+      - name: Create flux-system Secret (Git auth for private repo)
+        # Flux uses `username`/`password` keys on a namespace Secret to
+        # pull the GitRepository. Using the workflow's GITHUB_TOKEN keeps
+        # everything within the repo's own perms — no separate PAT to
+        # rotate. `x-access-token` is GitHub's convention for short-lived
+        # Actions tokens.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          kubectl create namespace flux-system --dry-run=client -o yaml | kubectl apply -f -
+          kubectl create secret generic flux-system \
+            --namespace=flux-system \
+            --from-literal=username=x-access-token \
+            --from-literal=password="$GITHUB_TOKEN" \
+            --dry-run=client -o yaml \
+          | kubectl apply --server-side --force-conflicts \
+              --field-manager=github-actions-deploy -f -
+
+      - name: Apply root GitRepository + Kustomizations
+        # Template at carbon/k8s/flux/clusters/primary/vibecarbon.yaml
+        # (copied to k8s/flux/clusters/primary/vibecarbon.yaml in the
+        # customer repo by `vibecarbon create`). `{{GITHUB_OWNER}}` +
+        # `{{PROJECT_NAME}}` in that template are substituted at create
+        # time, so by the time Actions runs this file has the real URL.
+        run: |
+          kubectl apply --server-side --force-conflicts \
+            --field-manager=github-actions-deploy \
+            -f k8s/flux/clusters/primary/vibecarbon.yaml
+
+  trigger-reconcile:
+    # After Secrets are fresh + Flux is bootstrapped, nudge Flux to
+    # reconcile now rather than wait up to 10 min for its interval.
+    name: Trigger Flux reconcile
+    needs: [apply-secrets, bootstrap-flux]
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment || 'prod' }}
+    env:
+      KUBECONFIG: ${{ github.workspace }}/kubeconfig
+    steps:
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+        with:
+          version: 'v1.32.0'
+
+      - name: Write kubeconfig from env secret
+        env:
+          KUBECONFIG_B64: ${{ secrets.KUBECONFIG_B64 }}
+        run: |
+          printf '%s' "$KUBECONFIG_B64" | base64 -d > "$KUBECONFIG"
+          chmod 600 "$KUBECONFIG"
+
+      - name: Annotate GitRepository + root Kustomizations
+        run: |
+          now="$(date -u +%FT%TZ)"
+          kubectl -n flux-system annotate --overwrite gitrepository/vibecarbon \
+            reconcile.fluxcd.io/requestedAt="$now" || true
+          for ks in vibecarbon-base vibecarbon-supabase vibecarbon-cert-manager-webhook-hetzner; do
+            kubectl -n flux-system annotate --overwrite kustomization/"$ks" \
+              reconcile.fluxcd.io/requestedAt="$now" || true
+          done
+
+      # State dump is inlined into the SAME shell as the wait commands so
+      # its output shows up in `gh run view <id> --log-failed`. A separate
+      # `if: failure()` job-step would run but wouldn't be in the failed-
+      # step logs (which is what waitForLatestWorkflowRun fetches), so
+      # debugging from the operator's machine would still be opaque.
+      - name: Wait for reconciliation (20 min budget)
+        run: |
+          set +e
+          kubectl -n flux-system wait --for=condition=Ready kustomization/vibecarbon-base --timeout=10m
+          BASE_RC=$?
+          kubectl -n flux-system wait --for=condition=Ready kustomization/vibecarbon-supabase --timeout=20m
+          SUPABASE_RC=$?
+          if [ $BASE_RC -ne 0 ] || [ $SUPABASE_RC -ne 0 ]; then
+            echo "=== RECONCILE FAILED — dumping Flux state ==="
+            echo "base=$BASE_RC supabase=$SUPABASE_RC"
+            echo
+            echo "=== Flux GitRepository ==="
+            kubectl -n flux-system describe gitrepository/vibecarbon || true
+            for ks in vibecarbon-base vibecarbon-supabase vibecarbon-cert-manager-webhook-hetzner; do
+              echo
+              echo "=== Kustomization: $ks ==="
+              kubectl -n flux-system describe kustomization/"$ks" || true
+            done
+            echo
+            echo "=== Flux events (last 80) ==="
+            kubectl -n flux-system get events --sort-by=.lastTimestamp 2>/dev/null | tail -80
+            echo
+            echo "=== vibecarbon namespace events (last 80) ==="
+            kubectl -n vibecarbon get events --sort-by=.lastTimestamp 2>/dev/null | tail -80
+            echo
+            echo "=== Non-ready pods (all namespaces) ==="
+            kubectl get pods -A --field-selector=status.phase!=Running,status.phase!=Succeeded 2>/dev/null
+            echo
+            echo "=== vibecarbon pods ==="
+            kubectl -n vibecarbon get pods -o wide 2>/dev/null
+            echo
+            echo "=== nodes (internal/external IPs) ==="
+            kubectl get nodes -o wide 2>/dev/null
+            echo
+            echo "=== kube-system pods (CoreDNS + CCM + CSI) ==="
+            kubectl -n kube-system get pods -o wide 2>/dev/null
+            echo
+            echo "=== CoreDNS ConfigMap (upstream resolvers) ==="
+            kubectl -n kube-system get configmap coredns -o yaml 2>/dev/null | sed -n '/data:/,/^[^ ]/p' | head -40
+            echo
+            echo "=== CoreDNS logs (last 30 lines per pod) ==="
+            for pod in $(kubectl -n kube-system get pods -l k8s-app=kube-dns -o name 2>/dev/null); do
+              echo "--- $pod ---"
+              kubectl -n kube-system logs "$pod" --tail=30 2>/dev/null
+            done
+            echo
+            echo "=== Hetzner CCM logs (last 40 lines) ==="
+            for pod in $(kubectl -n kube-system get pods -l app.kubernetes.io/name=hcloud-cloud-controller-manager -o name 2>/dev/null); do
+              echo "--- $pod ---"
+              kubectl -n kube-system logs "$pod" --tail=40 2>/dev/null
+            done
+            echo
+            echo "=== source-controller logs (last 40 lines) ==="
+            SC_POD=$(kubectl -n flux-system get pods -l app=source-controller -o name 2>/dev/null | head -1)
+            if [ -n "$SC_POD" ]; then
+              kubectl -n flux-system logs "$SC_POD" --tail=40 2>/dev/null || true
+              kubectl -n flux-system logs "$SC_POD" --previous --tail=40 2>/dev/null || true
+            fi
+            echo
+            echo "=== pod DNS probe (busybox in kube-system) ==="
+            # kube-system has relaxed PodSecurity (allows system pods).
+            # A plain pod can curl/nslookup without host namespaces —
+            # this is what Flux's source-controller is actually doing.
+            kubectl -n kube-system run dns-probe-$RANDOM --image=busybox:1.36 \
+              --restart=Never --rm -i --timeout=60s \
+              --overrides='{"spec":{"containers":[{"name":"probe","image":"busybox:1.36","command":["sh","-c","echo \"--- /etc/resolv.conf ---\"; cat /etc/resolv.conf; echo; echo \"--- nslookup github.com (via coredns) ---\"; nslookup github.com; echo; echo \"--- nslookup github.com @1.1.1.1 ---\"; nslookup github.com 1.1.1.1; echo; echo \"--- wget github.com ---\"; wget -qO- --timeout=5 https://github.com 2>&1 | head -5 || echo wget-failed"]}]}}' \
+              2>&1 | head -50 || echo "(pod dns-probe failed)"
+            echo
+            echo "=== kube-proxy / node routing (kube-proxy pod logs) ==="
+            for pod in $(kubectl -n kube-system get pods -l k8s-app=kube-proxy -o name 2>/dev/null | head -1); do
+              echo "--- $pod ---"
+              kubectl -n kube-system logs "$pod" --tail=20 2>/dev/null
+            done
+            exit 1
+          fi

package/carbon/.github/workflows/vibecarbon-build.yml

@@ -0,0 +1,81 @@
+name: Build & Push
+
+# Builds the app image on every push to main and every tagged release, then
+# publishes to GitHub Container Registry. `vibecarbon deploy` pulls from this
+# registry — no deploy logic lives in CI. This keeps CI fast and focused, and
+# lets users deploy from their laptop (or a CI runner) against any cluster.
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+concurrency:
+  group: build-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: pnpm test || true
+
+  build:
+    needs: [test]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      # Native amd64 build on the GitHub runner — no QEMU. Hetzner cpx* + cx*
+      # server types are all amd64 (ARM cax* isn't supported by the deploy
+      # preflight in src/lib/deploy/k8s/k3s.js). Users who need arm64 for
+      # other cloud providers can add `platforms: linux/amd64,linux/arm64`
+      # back and re-enable docker/setup-qemu-action@v3 — cutting it here
+      # saves 2-4 min per CI build on the hot path.
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=sha,format=short,prefix=
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # GHA cache keyed on Dockerfile + lockfile. `mode=max` caches every
+          # layer including intermediate ones, so re-builds with an unchanged
+          # install step reuse the pnpm-store layer (biggest single layer).
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

package/carbon/.windsurfrules

@@ -0,0 +1,74 @@
+# {{PROJECT_NAME}} Development Rules
+
+> **Read and follow all rules in AGENTS.md at the project root.** It contains mandatory security constraints for database, API, and infrastructure code.
+
+## Security Quick Reference
+
+- MUST check auth on every endpoint: `if (!c.get('user')) return c.json({ error: 'Unauthorized' }, 401)`
+- MUST validate all input with Zod schemas before processing
+- MUST use `c.get('supabase')` for user-facing queries (respects RLS) — never `supabaseAdmin`
+- MUST enable RLS on every new table with `(SELECT auth.uid())` in policies
+- MUST use `createAuthClient()` for `signInWithPassword()` — never the `supabaseAdmin` singleton
+- NEVER return raw database errors to clients
+- NEVER expose `SUPABASE_SERVICE_ROLE_KEY` to the client
+
+## Stack
+- Frontend: React 19, Vite, React Router, TanStack Query, Shadcn UI, Tailwind CSS v4
+- Backend: Hono (Node.js), Pino logger, Zod validation
+- Auth/Database: Self-hosted Supabase (PostgreSQL, Auth, REST API, Realtime, Storage)
+- Tooling: Biome (lint/format), TypeScript, esbuild, Vitest
+
+## Commands
+- `pnpm dev:start` - Full cold start (Docker + migrations + dev servers)
+- `pnpm dev` - Start API and Vite dev servers
+- `pnpm build` - Build client and server
+- `pnpm lint` - Biome linting
+- `pnpm typecheck` - TypeScript checking
+- `pnpm test` - Run vitest tests
+- `pnpm db:migrate` - Run SQL migrations
+
+## Path Aliases
+- `@/*` → `src/client/*`
+- `@shared/*` → `src/shared/*`
+- Never use `@/shared/*` - it won't resolve
+
+## Key Patterns
+
+### Supabase
+- Client-side (`src/client/lib/supabase.ts`): anon key, RLS enforced
+- Server-side (`src/server/lib/supabase.ts`): service role key, bypasses RLS
+- Auth is handled by Supabase - don't implement custom auth
+- Use `(SELECT auth.uid())` in RLS policies (not `auth.uid()` directly)
+
+### API Routes
+- Create in `src/server/routes/v1/`, mount in `src/server/index.ts`
+- Validate input with Zod schemas
+- Get user via `c.get('user')`, get Supabase client via `c.get('supabase')`
+
+### React Pages
+- Protected pages: wrap with `<ProtectedRoute>` in `App.tsx`
+- Admin pages: wrap with `<SuperAdminProtectedRoute>`
+- App pages use `<SidebarProvider>` + `<AppSidebar />` + `<SidebarInset>` layout
+
+### UI
+- Shadcn UI components in `src/client/components/ui/`
+- Use `cn()` from `@/lib/utils` for conditional classes
+- Use `toast` from `sonner` for notifications
+- Button `asChild` with Link children: add `className="inline-flex items-center gap-2"` to the Link, `shrink-0` on icons
+
+### Data Fetching
+- **NEVER use raw `fetch` in `useEffect`** — always use `useQuery` for reads, `useMutation` for writes. Raw fetch bypasses deduplication/caching and React StrictMode will double-fire it.
+- **Gate authenticated queries** with `enabled: !!user` to prevent 401s for logged-out users
+- **Use `getAuthHeaders()`** from `@/lib/api.ts` — never duplicate it locally, never send empty `Authorization` headers
+- Shared hooks in `src/client/hooks/api/`
+- Invalidate related queries after mutations: `queryClient.invalidateQueries({ queryKey: ['items'] })`
+
+### Database
+- Migrations in `supabase/migrations/` with incrementing prefix
+- Always enable RLS on new tables
+- Helper functions: `get_user_org_ids()`, `get_user_admin_org_ids()`, `is_super_admin()`
+
+### Environment Variables
+- Server env vars validated in `src/server/lib/env.ts`
+- Client env vars must start with `VITE_`
+- Feature flags use `isXConfigured()` pattern