vibecarbon 0.1.0

package/carbon/content/docs/database.mdx

@@ -0,0 +1,236 @@
+---
+title: "Database"
+description: "Work with Supabase PostgreSQL, migrations, and row-level security."
+order: 5
+---
+
+## Overview
+
+Your application uses self-hosted Supabase with PostgreSQL. All database operations go through Supabase's client libraries, which provide built-in support for row-level security (RLS).
+
+## Schema Overview
+
+The initial migration (`supabase/migrations/00001_init.sql`) creates the following tables:
+
+| Table | Purpose |
+|-------|---------|
+| `organizations` | Multi-tenant orgs with name, slug, and plan (FREE, STARTER, PRO, ENTERPRISE) |
+| `memberships` | User-org relationships with role (OWNER, ADMIN, MEMBER) |
+| `customers` | Billing customer records, linked to a user or organization (any provider) |
+| `subscriptions` | Billing subscription data (status, period, cancellation) |
+| `notifications` | System-wide or org-specific notifications with scheduling |
+| `notification_dismissals` | Tracks which notifications each user has dismissed |
+| `failed_login_attempts` | Brute force protection (email, IP, timestamp) |
+| `app_settings` | Key-value store for global config (e.g., MFA enforcement) |
+| `cron_job_history` | Background job execution tracking (pg_cron, see [Background Jobs](/docs/background-jobs)) |
+| `contact_submissions` | Contact form submissions (name, email, subject, message, status) |
+| `newsletter_subscribers` | Newsletter subscribers with double opt-in (email, status, confirmation token) |
+
+## Migrations
+
+SQL migrations live in `supabase/migrations/`. Run them with:
+
+```bash
+pnpm db:migrate
+```
+
+### Conventions
+
+- **Naming**: Use zero-padded sequential numbering — `00001_init.sql`, `00002_my_feature.sql`
+- **RLS**: Always enable RLS on new tables and add policies
+- **Timestamps**: Include `created_at` and `updated_at` columns with `TIMESTAMPTZ DEFAULT NOW()`
+- **Triggers**: Always add the `update_updated_at()` trigger for auto-updating `updated_at`
+- **Indexes**: Add indexes for foreign keys and frequently queried columns
+
+### Creating a New Table
+
+Create a migration file with the table, index, RLS policies, and trigger:
+
+```sql
+-- supabase/migrations/00002_my_table.sql
+
+CREATE TABLE IF NOT EXISTS my_table (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_my_table_user_id ON my_table(user_id);
+
+-- Enable RLS
+ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;
+
+-- CRUD policies
+CREATE POLICY "Users can view their own items"
+  ON my_table FOR SELECT
+  USING (user_id = (SELECT auth.uid()));
+
+CREATE POLICY "Users can create their own items"
+  ON my_table FOR INSERT
+  WITH CHECK (user_id = (SELECT auth.uid()));
+
+CREATE POLICY "Users can update their own items"
+  ON my_table FOR UPDATE
+  USING (user_id = (SELECT auth.uid()));
+
+CREATE POLICY "Users can delete their own items"
+  ON my_table FOR DELETE
+  USING (user_id = (SELECT auth.uid()));
+
+-- Auto-update updated_at
+CREATE TRIGGER my_table_updated_at
+  BEFORE UPDATE ON my_table
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+```
+
+## Row-Level Security
+
+Every table has RLS enabled. Policies use helper functions defined in the initial migration:
+
+### RLS Helper Functions
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `get_user_org_ids()` | `SETOF UUID` | Org IDs where the user is a member (any role) |
+| `get_user_admin_org_ids()` | `SETOF UUID` | Org IDs where the user is OWNER or ADMIN |
+| `get_user_owner_org_ids()` | `SETOF UUID` | Org IDs where the user is OWNER |
+| `get_user_customer_ids()` | `SETOF UUID` | Customer IDs for the user or their orgs |
+| `is_super_admin()` | `BOOLEAN` | `true` if user's `app_metadata.role` is `super_admin` |
+
+All helper functions use `SECURITY DEFINER` so they can read the `memberships` table regardless of the calling user's permissions.
+
+### Common Policy Patterns
+
+**User-owned data** — rows belong to a specific user:
+
+```sql
+CREATE POLICY "Users can view their own items"
+  ON my_table FOR SELECT
+  USING (user_id = (SELECT auth.uid()));
+```
+
+**Organization data** — rows belong to an org the user is a member of:
+
+```sql
+CREATE POLICY "Members can view org data"
+  ON my_table FOR SELECT
+  USING (organization_id IN (SELECT get_user_org_ids()));
+```
+
+**Admin-only writes** — only org owners/admins can modify:
+
+```sql
+CREATE POLICY "Admins can update org data"
+  ON my_table FOR UPDATE
+  USING (organization_id IN (SELECT get_user_admin_org_ids()));
+```
+
+**Super admin access** — full access for super admins:
+
+```sql
+CREATE POLICY "Super admins can do anything"
+  ON my_table FOR ALL
+  USING (is_super_admin());
+```
+
+## Client-Side Queries
+
+```typescript
+import { supabase } from '@/lib/supabase';
+
+// Fetch data (RLS enforced automatically)
+const { data: items, error: fetchError } = await supabase
+  .from('my_table')
+  .select('*');
+
+// Insert data
+const { data: newItem, error: insertError } = await supabase
+  .from('my_table')
+  .insert({ name: 'New item' })
+  .select()
+  .single();
+```
+
+## Server-Side Queries
+
+```typescript
+// User-context (respects RLS)
+const supabase = c.get('supabase');
+const { data } = await supabase.from('my_table').select('*');
+
+// Admin operations (bypasses RLS)
+import { supabaseAdmin } from '@/server/lib/supabase';
+const { data } = await supabaseAdmin.from('my_table').select('*');
+```
+
+## TanStack Query
+
+Use TanStack Query for client-side data fetching with caching, deduplication, and automatic refetching.
+
+### Fetching Data
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { supabase } from '@/lib/supabase';
+
+export function useItems() {
+  return useQuery({
+    queryKey: ['items'],
+    queryFn: async () => {
+      const { data, error } = await supabase.from('items').select('*');
+      if (error) throw error;
+      return data;
+    },
+  });
+}
+```
+
+### Mutations with Cache Invalidation
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { supabase } from '@/lib/supabase';
+
+export function useCreateItem() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (item: { name: string }) => {
+      const { data, error } = await supabase
+        .from('items')
+        .insert(item)
+        .select()
+        .single();
+      if (error) throw error;
+      return data;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+    },
+  });
+}
+```
+
+### Usage in Components
+
+```tsx
+function ItemList() {
+  const { data: items, isLoading, error } = useItems();
+  const createItem = useCreateItem();
+
+  if (isLoading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <div>
+      {items?.map((item) => <p key={item.id}>{item.name}</p>)}
+      <button onClick={() => createItem.mutate({ name: 'New item' })}>
+        Add Item
+      </button>
+    </div>
+  );
+}
+```

package/carbon/content/docs/deployment.mdx

@@ -0,0 +1,227 @@
+---
+title: "Deployment"
+description: "Deploy your application to production with Docker or Kubernetes."
+order: 6
+---
+
+> **Deployment requires a Diamond or Fullerene license.** `create` and local development (`up`, `down`) are always free. See [Getting Started](/docs/getting-started) for licensing details.
+
+## Overview
+
+Your application can be deployed using Docker Compose, Compose HA, or Kubernetes — all available with a Diamond or Fullerene license. Fullerene is the commercial license for agencies and enterprise.
+
+## Prerequisites
+
+**Always required (all deploy modes):**
+- **GitHub CLI** (`gh`) — authenticated with `read:packages` + `delete_repo` scopes. Images are built by GitHub Actions and published to ghcr.io; deploy waits for the tagged image to appear before provisioning the cluster.
+- **Pulumi** (`curl -fsSL https://get.pulumi.com | sh`) — drives Hetzner VM provisioning.
+- A **domain name** with DNS access (Cloudflare or Hetzner DNS).
+- **SMTP credentials** for transactional email (auth confirmations, magic links, invitations).
+- (Optional) **Stripe API keys** for billing.
+
+**Additional for `-mode k8s` / `-mode k8s-ha`:**
+- **kubectl** — applies manifests + waits for the app rollout.
+- **docker** + **ssh** — image is built locally and sideloaded to each k3s node via `docker save | ssh node 'k3s ctr images import -'`. No registry round-trip on the deploy path.
+
+**Optional:**
+- `helm` — only required if you layer GitOps on top via [`vibecarbon configure cicd <env>`](/docs/cli#configure-cicd-env-subcommand) (Flux-managed Helm releases). The default deploy path doesn't use it.
+
+## Build
+
+Build the client and server for production:
+
+```bash
+pnpm build
+```
+
+This produces:
+- `dist/client/` — Static assets (Vite build with hashed filenames)
+- `dist/server/` — Bundled API server (esbuild output)
+
+The `Dockerfile` uses a multi-stage build: a Node.js build stage compiles both client and server, then copies the output into a slim runtime image.
+
+## Docker Compose
+
+For a single-server deployment:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+The production overlay (`docker-compose.prod.yml`) adds:
+- Production environment variables (`NODE_ENV=production`)
+- Resource limits for containers
+- Restart policies (`unless-stopped`)
+- Traefik SSL configuration with Let's Encrypt
+- Host-based routing for your domain
+
+Verify the deployment:
+
+```bash
+curl -s https://your-domain.com/api/health | jq
+```
+
+## Kubernetes
+
+For production deployments with auto-scaling and monitoring (requires Diamond or Fullerene license):
+
+```bash
+# Bare command opens a guided prompt for env, mode, region, etc.
+npx vibecarbon deploy
+
+# Or seed env + mode for a scripted deploy
+npx vibecarbon deploy prod -mode k8s
+```
+
+This command:
+1. Builds the app and sideloads images to every k3s node via SSH (no registry round-trip)
+2. Applies Kubernetes manifests with Kustomize overlays
+3. Configures Traefik ingress with automatic SSL
+4. Sets up monitoring (Grafana, Prometheus, Loki) if observability is enabled
+
+The `k8s/` directory structure:
+
+```
+k8s/
+├── base/                # Shared manifests
+│   ├── app/             # App deployment, service, ingress
+│   ├── supabase/        # Supabase services
+│   └── kustomization.yaml
+└── overlays/
+    ├── staging/         # Staging-specific config
+    └── production/      # Production-specific config
+```
+
+### Node Scaling
+
+Worker nodes are bounds-controlled at deploy time — the default is `min=1, max=3` (cluster-autoscaler scales 0..(max-min) workers on top of the static floor). Worker bounds and server types are configured interactively during `vibecarbon deploy` or in `.vibecarbon.json`; they don't have CLI flags (the design principle is "things you set once and forget belong in the config file").
+
+To re-tune bounds or worker server types on an existing cluster, run `npx vibecarbon scale` — the wizard walks you through what's changeable for your topology. Power users can seed a server-type change with `-type` (e.g. `npx vibecarbon scale prod -type cx33 -y`). Pod-level autoscaling (HPA) is configured for the app and rest services and scales pods within the existing worker pool based on CPU.
+
+> **Note**: k3s masters have no `NoSchedule` taint by default, so all application pods run on the master node when no workers are present.
+
+### High Availability
+
+**Compose HA** — multi-region Docker Compose with PostgreSQL streaming replication:
+
+```bash
+npx vibecarbon deploy prod -mode compose-ha
+```
+
+This adds:
+- PostgreSQL streaming replication across regions
+- DNS-based health checks with one-command failover (`vibecarbon failover`)
+- Primary + standby VPS architecture
+
+**Kubernetes HA** — full K8s clusters per region:
+
+```bash
+npx vibecarbon deploy prod -mode k8s-ha
+```
+
+This additionally includes:
+- Kubernetes HPA (pod-level autoscaling) per region
+- Cluster Autoscaler (VPS-level autoscaling) per region
+- Health monitoring across replicas
+
+## Environment Variables
+
+Production requires these environment variables in `.env.production` or your deployment secrets:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SUPABASE_URL` | Yes | Your Supabase API URL |
+| `SUPABASE_ANON_KEY` | Yes | Public anonymous key |
+| `SUPABASE_SERVICE_ROLE_KEY` | Yes | Server-side service role key |
+| `SITE_URL` | Yes | Your production URL (e.g., `https://app.example.com`) |
+| `DOMAIN` | Yes | Your root domain (e.g., `example.com`) |
+| `SMTP_HOST` | Yes | SMTP server hostname |
+| `SMTP_PORT` | No | SMTP port (default: 587) |
+| `SMTP_USER` | Yes | SMTP username |
+| `SMTP_PASS` | Yes | SMTP password |
+| `SMTP_SENDER_NAME` | No | Display name for outgoing emails |
+| `SMTP_ADMIN_EMAIL` | No | Admin contact email for system notifications |
+| `BILLING_PROVIDER` | No | Payment provider: `stripe` (default), `paddle`, or `polar` |
+| `STRIPE_SECRET_KEY` | No | Stripe API key (required if using Stripe) |
+| `STRIPE_WEBHOOK_SECRET` | No | Stripe webhook signing secret |
+| `STRIPE_PRICE_STARTER` | No | Stripe price ID for the Startup plan |
+| `STRIPE_PRICE_PRO` | No | Stripe price ID for the Pro plan |
+| `PADDLE_API_KEY` | No | Paddle API key (required if using Paddle) |
+| `PADDLE_WEBHOOK_SECRET` | No | Paddle webhook signing secret |
+| `PADDLE_ENVIRONMENT` | No | `sandbox` or `production` (default: sandbox) |
+| `PADDLE_PRICE_STARTER` | No | Paddle price ID for the Startup plan |
+| `PADDLE_PRICE_PRO` | No | Paddle price ID for the Pro plan |
+| `POLAR_ACCESS_TOKEN` | No | Polar access token (required if using Polar) |
+| `POLAR_WEBHOOK_SECRET` | No | Polar webhook signing secret |
+| `POLAR_ORGANIZATION_ID` | No | Polar organization ID |
+| `POLAR_PRICE_STARTER` | No | Polar product ID for the Startup plan |
+| `POLAR_PRICE_PRO` | No | Polar product ID for the Pro plan |
+| `VITE_PLAUSIBLE_DOMAIN` | No | Plausible analytics domain (e.g., `myapp.com`) |
+| `VITE_PLAUSIBLE_SCRIPT_URL` | No | Plausible script URL (default: Plausible Cloud) |
+| `REDIS_URL` | No | Redis connection URL (for distributed rate limiting) |
+
+## SMTP Configuration
+
+SMTP credentials are shared between Supabase Auth (for email confirmation, password reset, magic links) and the application's email service (for welcome emails, team invitations, billing notifications).
+
+**Required variables**: `SMTP_HOST`, `SMTP_USER`, `SMTP_PASS`
+
+**Optional variables**: `SMTP_PORT` (defaults to 587), `SMTP_SENDER_NAME`, `SMTP_ADMIN_EMAIL`
+
+Without SMTP configured:
+- Email confirmation is disabled — users can sign in immediately after sign-up
+- Magic link authentication is unavailable
+- Team invitation emails won't send (invitations still work via shareable link)
+- Transactional emails (welcome, billing) are skipped silently
+
+## DNS Configuration
+
+Point your domain to the server's IP address:
+
+| Record | Name | Value |
+|--------|------|-------|
+| A | `app.example.com` | `<server-ip>` |
+| A | `api.example.com` | `<server-ip>` |
+
+If you have optional services enabled, add records for their subdomains too (e.g., `grafana.example.com`, `n8n.example.com`).
+
+SSL certificates are handled automatically by Traefik via Let's Encrypt — no manual certificate management required.
+
+## Backup & Restore
+
+Create and manage database backups with the CLI:
+
+```bash
+# Interactive — prompts for env and action
+npx vibecarbon backup
+
+# Create a backup for a specific env
+npx vibecarbon backup prod
+
+# List existing backups
+npx vibecarbon backup prod -l
+
+# Restore from a backup (interactive picker)
+npx vibecarbon restore prod
+```
+
+Backups include the full PostgreSQL database (schema, data, and auth tables).
+
+## Monitoring
+
+Add the observability stack for metrics, dashboards, and log aggregation:
+
+```bash
+npx vibecarbon add observability
+```
+
+This enables:
+- **Prometheus** — Metrics collection from all services
+- **Grafana** — Pre-built dashboards for API performance, database metrics, and container health
+- **Loki** — Centralized log aggregation with Grafana integration
+
+Access Grafana at `https://grafana.your-domain.com` (requires `super_admin` role in production).
+
+## SSL Certificates
+
+Traefik automatically obtains and renews SSL certificates via Let's Encrypt. No manual certificate management required.

package/carbon/content/docs/development.mdx

@@ -0,0 +1,238 @@
+---
+title: "Development"
+description: "Day-to-day development workflow, commands, and how to add pages, routes, and content."
+order: 3
+---
+
+## CLI Commands
+
+If you installed Vibecarbon globally, you can manage your dev environment with these commands:
+
+| Command | Purpose |
+|---------|---------|
+| `npx vibecarbon up` | Full cold start — Docker, migrations, and dev servers |
+| `npx vibecarbon down` | Stop all Docker services |
+| `npx vibecarbon reset` | Remove containers, volumes, and built images (run `npx vibecarbon up` to restart) |
+
+These are wrappers around the `pnpm` scripts listed below — use whichever you prefer.
+
+## Dev Commands
+
+| Command | Purpose |
+|---------|---------|
+| `pnpm dev:start` | Full cold start — Docker, migrations, and dev servers |
+| `pnpm dev` | Start API + Vite (assumes Docker is already running) |
+| `pnpm dev:reset` | Remove containers, volumes, and built images (run `pnpm dev:start` to restart) |
+| `pnpm docker:up` | Start Supabase and infrastructure services |
+| `pnpm docker:down` | Stop all Docker services |
+| `pnpm db:migrate` | Run SQL migrations from `supabase/migrations/` |
+| `pnpm build` | Build client (Vite) and server (esbuild) for production |
+| `pnpm lint` | Biome linting and formatting check |
+| `pnpm lint:fix` | Auto-fix lint and formatting issues |
+| `pnpm typecheck` | TypeScript type checking |
+| `pnpm test` | Run vitest tests |
+| `pnpm start` | Run production server (`node dist/server/index.js`) |
+| `pnpm stripe:listen` | Forward Stripe webhooks to local API |
+| `pnpm docker:logs` | Tail logs from all Docker containers |
+
+## How It Works
+
+`pnpm dev:start` runs three phases in sequence:
+
+1. **Docker startup** — Starts PostgreSQL, Kong, GoTrue, PostgREST, Realtime, Storage, Studio, and Traefik. Blocks until all services are healthy.
+2. **Migrations** — Executes all SQL files in `supabase/migrations/` to set up the schema, RLS policies, and initial admin user.
+3. **Dev servers** — Spawns two processes in parallel:
+   - **Hono API** on port 3000 via `tsx watch` (auto-restarts on file changes)
+   - **Vite** on port 5173 with full HMR (instant browser updates)
+
+Vite proxies all `/api/*` requests to the Hono server, so the client can call `fetch('/api/v1/...')` without worrying about ports or CORS.
+
+## Development URLs
+
+Traefik routes `*.localhost` subdomains to each service:
+
+| Service | URL |
+|---------|-----|
+| App | http://app.localhost |
+| Supabase Studio | http://studio.localhost |
+| Traefik Dashboard | http://traefik.localhost |
+
+Optional services (n8n, Metabase, Grafana) get their own subdomains when enabled — see [Optional Services](/docs/optional-services).
+
+## Hot Reloading
+
+**Client changes** (React components, CSS, MDX) update instantly in the browser via Vite HMR. Component state is preserved.
+
+**Server changes** (API routes, middleware) trigger a full process restart via `tsx watch`. The API is briefly unavailable during restart.
+
+**Database changes** require running `pnpm db:migrate` manually — migrations are not watched.
+
+## Debugging
+
+**Container logs** — Run `pnpm docker:logs` to tail logs from all Docker services. Useful for debugging Supabase Auth errors, PostgREST issues, or Kong routing problems.
+
+**Supabase Studio** — Open [http://studio.localhost](http://studio.localhost) to browse your database, inspect tables, view RLS policies, and manage auth users directly.
+
+**React DevTools** — Vite's dev server supports React DevTools out of the box. Install the browser extension for component inspection and state debugging.
+
+## Adding a Page
+
+1. Create a component in `src/client/pages/`:
+
+```tsx
+export default function MyPage() {
+  return <h1>My Page</h1>;
+}
+```
+
+2. Add a route in `src/client/App.tsx`:
+
+```tsx
+<Route
+  path="/my-page"
+  element={
+    <ProtectedRoute>
+      <MyPage />
+    </ProtectedRoute>
+  }
+/>
+```
+
+Wrap with `<ProtectedRoute>` to require authentication, or omit it for public pages.
+
+## Adding an API Route
+
+1. Create a route file in `src/server/routes/v1/`:
+
+```typescript
+import { Hono } from 'hono';
+import { z } from 'zod';
+import type { HonoVariables } from '../../types';
+
+const items = new Hono<{ Variables: HonoVariables }>();
+
+const createSchema = z.object({
+  name: z.string().min(1).max(100),
+});
+
+items.get('/', async (c) => {
+  const user = c.get('user');
+  if (!user) return c.json({ error: 'Unauthorized' }, 401);
+
+  const supabase = c.get('supabase');
+  const { data, error } = await supabase.from('items').select('*');
+  if (error) return c.json({ error: 'Failed to fetch items' }, 500);
+  return c.json(data);
+});
+
+items.post('/', async (c) => {
+  const user = c.get('user');
+  if (!user) return c.json({ error: 'Unauthorized' }, 401);
+
+  const body = await c.req.json();
+  const result = createSchema.safeParse(body);
+  if (!result.success) {
+    return c.json({ error: result.error.issues.map((e) => e.message).join(', ') }, 400);
+  }
+
+  const supabase = c.get('supabase');
+  const { data, error } = await supabase
+    .from('items')
+    .insert(result.data)
+    .select()
+    .single();
+  if (error) return c.json({ error: 'Failed to create item' }, 500);
+  return c.json({ item: data }, 201);
+});
+
+export { items };
+```
+
+2. Mount in `src/server/index.ts`:
+
+```typescript
+import { items } from './routes/v1/items';
+app.route('/api/v1/items', items);
+```
+
+The Vite proxy forwards `/api/*` to the Hono server automatically.
+
+## Adding MDX Content
+
+MDX files in `content/` are auto-discovered at build time. Drop a file in the right directory and it appears on the site.
+
+**Blog post** — `content/blog/my-post.mdx`:
+
+```markdown
+---
+title: "My Post"
+description: "A short summary."
+date: "2025-01-15"
+author: "Your Name"
+---
+
+Post content with **markdown** and JSX.
+```
+
+**Documentation page** — `content/docs/my-page.mdx`:
+
+```markdown
+---
+title: "My Page"
+description: "What this page covers."
+order: 7
+---
+
+Page content here.
+```
+
+**Changelog entry** — `content/changelog/v1-1-0.mdx`:
+
+```markdown
+---
+title: "v1.1.0"
+description: "What changed."
+date: "2025-01-15"
+version: "1.1.0"
+---
+
+## Features
+- New feature
+```
+
+The `order` field controls sidebar position in docs. Blog and changelog entries sort by `date` (newest first).
+
+## Running Multiple Projects
+
+To run two Vibecarbon projects simultaneously, set a port offset in `.env.local`:
+
+```bash
+DEV_PORT_OFFSET=100
+```
+
+This shifts all ports by 100 (Vite → 5273, API → 3100, Kong → 8100, etc.). You can also override individual ports:
+
+```bash
+DEV_VITE_PORT=5273
+DEV_API_PORT=3100
+DEV_KONG_PORT=8100
+```
+
+## Resetting the Environment
+
+If your database gets into a bad state or you want a clean slate:
+
+```bash
+pnpm dev:reset     # Remove containers, volumes, and built images
+pnpm dev:start     # Cold start: Docker + migrations + dev servers
+```
+
+`dev:reset` removes all Docker containers, volumes (including database data), and locally-built images. It does **not** restart services — run `pnpm dev:start` afterward to start fresh.
+
+To stop services without losing data:
+
+```bash
+pnpm docker:down   # Stop services, data preserved in volumes
+pnpm docker:up     # Restart services with existing data
+pnpm dev           # Start dev servers
+```