Add workspace management and isolated worktree environments

README.md

@@ -15,23 +15,27 @@ AI-native task management platform — like Linear, but with AI agents as first-
 # 1. Install dependencies
 pnpm install
 
-# 2. Copy environment variables
+# 2. Copy environment variables for the shared main environment
 cp .env.example .env
 
-# 3. Start PostgreSQL
-docker compose up -d
+# 3. One-time setup: start DB, run migrations, seed data
+make setup
 
-# 4. Run database migrations
-make migrate-up
-
-# 5. Start the Go backend (port 8080)
-make dev
-
-# 6. In another terminal, start the frontend (port 3000)
-pnpm dev:web
+# 4. Start backend + frontend
+make start
 ```
 
-Open [http://localhost:3000](http://localhost:3000) in your browser.
+Open your configured `FRONTEND_ORIGIN` in the browser. By default that is [http://localhost:3000](http://localhost:3000).
+
+Default behavior now prefers the shared main environment in `.env`. If you want an isolated environment for a Git worktree, generate `.env.worktree` and use the explicit worktree targets:
+
+```bash
+make worktree-env
+make setup-worktree
+make start-worktree
+```
+
+This lets you keep `.env` connected to your main database while using `.env.worktree` only for isolated feature testing.
 
 ## Project Structure
 
@@ -61,7 +65,7 @@ Open [http://localhost:3000](http://localhost:3000) in your browser.
 
 | Command | Description |
 |---------|-------------|
-| `pnpm dev:web` | Start Next.js dev server (port 3000) |
+| `pnpm dev:web` | Start Next.js dev server (uses `FRONTEND_PORT`, default `3000`) |
 | `pnpm build` | Build all TypeScript packages |
 | `pnpm typecheck` | Run TypeScript type checking |
 | `pnpm test` | Run TypeScript tests |
@@ -70,7 +74,7 @@ Open [http://localhost:3000](http://localhost:3000) in your browser.
 
 | Command | Description |
 |---------|-------------|
-| `make dev` | Run Go server (port 8080) |
+| `make dev` | Run Go server (uses `PORT`, default `8080`) |
 | `make daemon` | Run local agent daemon |
 | `make test` | Run Go tests |
 | `make build` | Build server & daemon binaries |
@@ -85,13 +89,19 @@ Open [http://localhost:3000](http://localhost:3000) in your browser.
 | `make migrate-up` | Run database migrations |
 | `make migrate-down` | Rollback database migrations |
 | `make seed` | Seed test data |
+| `make worktree-env` | Generate an isolated `.env.worktree` for the current worktree |
+| `make setup-main` / `make start-main` | Force use of the shared main `.env` |
+| `make setup-worktree` / `make start-worktree` | Force use of isolated `.env.worktree` |
 
 ## Environment Variables
 
 See [`.env.example`](.env.example) for all available variables:
 
 - `DATABASE_URL` — PostgreSQL connection string
+- `COMPOSE_PROJECT_NAME` — Docker Compose project name
+- `POSTGRES_DB` / `POSTGRES_PORT` — Per-worktree PostgreSQL database and host port
 - `PORT` — Backend server port (default: 8080)
+- `FRONTEND_PORT` / `FRONTEND_ORIGIN` — Frontend port and browser origin
 - `JWT_SECRET` — JWT signing secret
 - `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` — Google OAuth (optional)
 - `NEXT_PUBLIC_API_URL` — Frontend → backend API URL