feat: add project workspaces (DB, API, service, and UI)

New project_workspaces table with primary workspace designation.
Full CRUD routes, service with auto-primary promotion on delete,
workspace management UI in project properties panel, and workspace
data included in project/issue ancestor responses.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/db/src/migrations/0019_public_victor_mancha.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "project_workspaces" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"name" text NOT NULL,
+	"cwd" text NOT NULL,
+	"repo_url" text,
+	"repo_ref" text,
+	"metadata" jsonb,
+	"is_primary" boolean DEFAULT false NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD CONSTRAINT "project_workspaces_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "project_workspaces" ADD CONSTRAINT "project_workspaces_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "project_workspaces_company_project_idx" ON "project_workspaces" USING btree ("company_id","project_id");--> statement-breakpoint
+CREATE INDEX "project_workspaces_project_primary_idx" ON "project_workspaces" USING btree ("project_id","is_primary");

packages/db/src/migrations/meta/_journal.json

@@ -127,6 +127,20 @@
       "when": 1771883888199,
       "tag": "0017_tiresome_gabe_jones",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1771897769629,
+      "tag": "0018_flat_sleepwalker",
+      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1772029333401,
+      "tag": "0019_public_victor_mancha",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/project_workspaces.ts

@@ -0,0 +1,32 @@
+import {
+  boolean,
+  index,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { projects } from "./projects.js";
+
+export const projectWorkspaces = pgTable(
+  "project_workspaces",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
+    name: text("name").notNull(),
+    cwd: text("cwd").notNull(),
+    repoUrl: text("repo_url"),
+    repoRef: text("repo_ref"),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>(),
+    isPrimary: boolean("is_primary").notNull().default(false),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyProjectIdx: index("project_workspaces_company_project_idx").on(table.companyId, table.projectId),
+    projectPrimaryIdx: index("project_workspaces_project_primary_idx").on(table.projectId, table.isPrimary),
+  }),
+);

packages/shared/src/types/project.ts

@@ -5,6 +5,20 @@ export interface ProjectGoalRef {
   title: string;
 }
 
+export interface ProjectWorkspace {
+  id: string;
+  companyId: string;
+  projectId: string;
+  name: string;
+  cwd: string;
+  repoUrl: string | null;
+  repoRef: string | null;
+  metadata: Record<string, unknown> | null;
+  isPrimary: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
 export interface Project {
   id: string;
   companyId: string;
@@ -18,6 +32,8 @@ export interface Project {
   leadAgentId: string | null;
   targetDate: string | null;
   color: string | null;
+  workspaces: ProjectWorkspace[];
+  primaryWorkspace: ProjectWorkspace | null;
   archivedAt: Date | null;
   createdAt: Date;
   updatedAt: Date;

packages/shared/src/validators/project.ts

@@ -19,3 +19,18 @@ export type CreateProject = z.infer<typeof createProjectSchema>;
 export const updateProjectSchema = createProjectSchema.partial();
 
 export type UpdateProject = z.infer<typeof updateProjectSchema>;
+
+export const createProjectWorkspaceSchema = z.object({
+  name: z.string().min(1),
+  cwd: z.string().min(1),
+  repoUrl: z.string().url().optional().nullable(),
+  repoRef: z.string().optional().nullable(),
+  metadata: z.record(z.unknown()).optional().nullable(),
+  isPrimary: z.boolean().optional().default(false),
+});
+
+export type CreateProjectWorkspace = z.infer<typeof createProjectWorkspaceSchema>;
+
+export const updateProjectWorkspaceSchema = createProjectWorkspaceSchema.partial();
+
+export type UpdateProjectWorkspace = z.infer<typeof updateProjectWorkspaceSchema>;

server/src/routes/projects.ts

@@ -1,6 +1,11 @@
 import { Router } from "express";
 import type { Db } from "@paperclip/db";
-import { createProjectSchema, updateProjectSchema } from "@paperclip/shared";
+import {
+  createProjectSchema,
+  createProjectWorkspaceSchema,
+  updateProjectSchema,
+  updateProjectWorkspaceSchema,
+} from "@paperclip/shared";
 import { validate } from "../middleware/validate.js";
 import { projectService, logActivity } from "../services/index.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
@@ -74,6 +79,122 @@ export function projectRoutes(db: Db) {
     res.json(project);
   });
 
+  router.get("/projects/:id/workspaces", async (req, res) => {
+    const id = req.params.id as string;
+    const existing = await svc.getById(id);
+    if (!existing) {
+      res.status(404).json({ error: "Project not found" });
+      return;
+    }
+    assertCompanyAccess(req, existing.companyId);
+    const workspaces = await svc.listWorkspaces(id);
+    res.json(workspaces);
+  });
+
+  router.post("/projects/:id/workspaces", validate(createProjectWorkspaceSchema), async (req, res) => {
+    const id = req.params.id as string;
+    const existing = await svc.getById(id);
+    if (!existing) {
+      res.status(404).json({ error: "Project not found" });
+      return;
+    }
+    assertCompanyAccess(req, existing.companyId);
+    const workspace = await svc.createWorkspace(id, req.body);
+    if (!workspace) {
+      res.status(404).json({ error: "Project not found" });
+      return;
+    }
+
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: existing.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      action: "project.workspace_created",
+      entityType: "project",
+      entityId: id,
+      details: {
+        workspaceId: workspace.id,
+        name: workspace.name,
+        cwd: workspace.cwd,
+        isPrimary: workspace.isPrimary,
+      },
+    });
+
+    res.status(201).json(workspace);
+  });
+
+  router.patch(
+    "/projects/:id/workspaces/:workspaceId",
+    validate(updateProjectWorkspaceSchema),
+    async (req, res) => {
+      const id = req.params.id as string;
+      const workspaceId = req.params.workspaceId as string;
+      const existing = await svc.getById(id);
+      if (!existing) {
+        res.status(404).json({ error: "Project not found" });
+        return;
+      }
+      assertCompanyAccess(req, existing.companyId);
+      const workspace = await svc.updateWorkspace(id, workspaceId, req.body);
+      if (!workspace) {
+        res.status(404).json({ error: "Project workspace not found" });
+        return;
+      }
+
+      const actor = getActorInfo(req);
+      await logActivity(db, {
+        companyId: existing.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        action: "project.workspace_updated",
+        entityType: "project",
+        entityId: id,
+        details: {
+          workspaceId: workspace.id,
+          changedKeys: Object.keys(req.body).sort(),
+        },
+      });
+
+      res.json(workspace);
+    },
+  );
+
+  router.delete("/projects/:id/workspaces/:workspaceId", async (req, res) => {
+    const id = req.params.id as string;
+    const workspaceId = req.params.workspaceId as string;
+    const existing = await svc.getById(id);
+    if (!existing) {
+      res.status(404).json({ error: "Project not found" });
+      return;
+    }
+    assertCompanyAccess(req, existing.companyId);
+    const workspace = await svc.removeWorkspace(id, workspaceId);
+    if (!workspace) {
+      res.status(404).json({ error: "Project workspace not found" });
+      return;
+    }
+
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: existing.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      action: "project.workspace_deleted",
+      entityType: "project",
+      entityId: id,
+      details: {
+        workspaceId: workspace.id,
+        name: workspace.name,
+      },
+    });
+
+    res.json(workspace);
+  });
+
   router.delete("/projects/:id", async (req, res) => {
     const id = req.params.id as string;
     const existing = await svc.getById(id);

server/src/services/projects.ts

@@ -1,13 +1,16 @@
-import { eq, inArray } from "drizzle-orm";
+import { and, asc, desc, eq, inArray } from "drizzle-orm";
 import type { Db } from "@paperclip/db";
-import { projects, projectGoals, goals } from "@paperclip/db";
+import { projects, projectGoals, goals, projectWorkspaces } from "@paperclip/db";
-import { PROJECT_COLORS, type ProjectGoalRef } from "@paperclip/shared";
+import { PROJECT_COLORS, type ProjectGoalRef, type ProjectWorkspace } from "@paperclip/shared";
 
 type ProjectRow = typeof projects.$inferSelect;
+type ProjectWorkspaceRow = typeof projectWorkspaces.$inferSelect;
 
 interface ProjectWithGoals extends ProjectRow {
   goalIds: string[];
   goals: ProjectGoalRef[];
+  workspaces: ProjectWorkspace[];
+  primaryWorkspace: ProjectWorkspace | null;
 }
 
 /** Batch-load goal refs for a set of projects. */
@@ -39,7 +42,61 @@ async function attachGoals(db: Db, rows: ProjectRow[]): Promise<ProjectWithGoals
 
   return rows.map((r) => {
     const g = map.get(r.id) ?? [];
-    return { ...r, goalIds: g.map((x) => x.id), goals: g };
+    return { ...r, goalIds: g.map((x) => x.id), goals: g } as ProjectWithGoals;
+  });
+}
+
+function toWorkspace(row: ProjectWorkspaceRow): ProjectWorkspace {
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    projectId: row.projectId,
+    name: row.name,
+    cwd: row.cwd,
+    repoUrl: row.repoUrl ?? null,
+    repoRef: row.repoRef ?? null,
+    metadata: (row.metadata as Record<string, unknown> | null) ?? null,
+    isPrimary: row.isPrimary,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function pickPrimaryWorkspace(rows: ProjectWorkspaceRow[]): ProjectWorkspace | null {
+  if (rows.length === 0) return null;
+  const explicitPrimary = rows.find((row) => row.isPrimary);
+  return toWorkspace(explicitPrimary ?? rows[0]);
+}
+
+/** Batch-load workspace refs for a set of projects. */
+async function attachWorkspaces(db: Db, rows: ProjectWithGoals[]): Promise<ProjectWithGoals[]> {
+  if (rows.length === 0) return [];
+
+  const projectIds = rows.map((r) => r.id);
+  const workspaceRows = await db
+    .select()
+    .from(projectWorkspaces)
+    .where(inArray(projectWorkspaces.projectId, projectIds))
+    .orderBy(desc(projectWorkspaces.isPrimary), asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id));
+
+  const map = new Map<string, ProjectWorkspaceRow[]>();
+  for (const row of workspaceRows) {
+    let arr = map.get(row.projectId);
+    if (!arr) {
+      arr = [];
+      map.set(row.projectId, arr);
+    }
+    arr.push(row);
+  }
+
+  return rows.map((row) => {
+    const projectWorkspaceRows = map.get(row.id) ?? [];
+    const workspaces = projectWorkspaceRows.map(toWorkspace);
+    return {
+      ...row,
+      workspaces,
+      primaryWorkspace: pickPrimaryWorkspace(projectWorkspaceRows),
+    };
   });
 }
 
@@ -65,11 +122,42 @@ function resolveGoalIds(data: { goalIds?: string[]; goalId?: string | null }): s
   return undefined;
 }
 
+async function ensureSinglePrimaryWorkspace(
+  dbOrTx: any,
+  input: {
+    companyId: string;
+    projectId: string;
+    keepWorkspaceId: string;
+  },
+) {
+  await dbOrTx
+    .update(projectWorkspaces)
+    .set({ isPrimary: false, updatedAt: new Date() })
+    .where(
+      and(
+        eq(projectWorkspaces.companyId, input.companyId),
+        eq(projectWorkspaces.projectId, input.projectId),
+      ),
+    );
+
+  await dbOrTx
+    .update(projectWorkspaces)
+    .set({ isPrimary: true, updatedAt: new Date() })
+    .where(
+      and(
+        eq(projectWorkspaces.companyId, input.companyId),
+        eq(projectWorkspaces.projectId, input.projectId),
+        eq(projectWorkspaces.id, input.keepWorkspaceId),
+      ),
+    );
+}
+
 export function projectService(db: Db) {
   return {
     list: async (companyId: string): Promise<ProjectWithGoals[]> => {
       const rows = await db.select().from(projects).where(eq(projects.companyId, companyId));
-      return attachGoals(db, rows);
+      const withGoals = await attachGoals(db, rows);
+      return attachWorkspaces(db, withGoals);
     },
 
     getById: async (id: string): Promise<ProjectWithGoals | null> => {
@@ -79,8 +167,10 @@ export function projectService(db: Db) {
         .where(eq(projects.id, id))
         .then((rows) => rows[0] ?? null);
       if (!row) return null;
-      const [enriched] = await attachGoals(db, [row]);
+      const [withGoals] = await attachGoals(db, [row]);
-      return enriched;
+      if (!withGoals) return null;
+      const [enriched] = await attachWorkspaces(db, [withGoals]);
+      return enriched ?? null;
     },
 
     create: async (
@@ -111,8 +201,9 @@ export function projectService(db: Db) {
         await syncGoalLinks(db, row.id, companyId, ids);
       }
 
-      const [enriched] = await attachGoals(db, [row]);
+      const [withGoals] = await attachGoals(db, [row]);
-      return enriched;
+      const [enriched] = withGoals ? await attachWorkspaces(db, [withGoals]) : [];
+      return enriched!;
     },
 
     update: async (
@@ -143,8 +234,9 @@ export function projectService(db: Db) {
         await syncGoalLinks(db, id, row.companyId, ids);
       }
 
-      const [enriched] = await attachGoals(db, [row]);
+      const [withGoals] = await attachGoals(db, [row]);
-      return enriched;
+      const [enriched] = withGoals ? await attachWorkspaces(db, [withGoals]) : [];
+      return enriched ?? null;
     },
 
     remove: (id: string) =>
@@ -153,5 +245,223 @@ export function projectService(db: Db) {
         .where(eq(projects.id, id))
         .returning()
         .then((rows) => rows[0] ?? null),
+
+    listWorkspaces: async (projectId: string): Promise<ProjectWorkspace[]> => {
+      const rows = await db
+        .select()
+        .from(projectWorkspaces)
+        .where(eq(projectWorkspaces.projectId, projectId))
+        .orderBy(desc(projectWorkspaces.isPrimary), asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id));
+      return rows.map(toWorkspace);
+    },
+
+    createWorkspace: async (
+      projectId: string,
+      data: Omit<typeof projectWorkspaces.$inferInsert, "projectId" | "companyId">,
+    ): Promise<ProjectWorkspace | null> => {
+      const project = await db
+        .select()
+        .from(projects)
+        .where(eq(projects.id, projectId))
+        .then((rows) => rows[0] ?? null);
+      if (!project) return null;
+
+      const existing = await db
+        .select()
+        .from(projectWorkspaces)
+        .where(eq(projectWorkspaces.projectId, projectId))
+        .orderBy(asc(projectWorkspaces.createdAt))
+        .then((rows) => rows);
+
+      const shouldBePrimary = data.isPrimary === true || existing.length === 0;
+      const created = await db.transaction(async (tx) => {
+        if (shouldBePrimary) {
+          await tx
+            .update(projectWorkspaces)
+            .set({ isPrimary: false, updatedAt: new Date() })
+            .where(
+              and(
+                eq(projectWorkspaces.companyId, project.companyId),
+                eq(projectWorkspaces.projectId, projectId),
+              ),
+            );
+        }
+
+        const row = await tx
+          .insert(projectWorkspaces)
+          .values({
+            companyId: project.companyId,
+            projectId,
+            name: data.name,
+            cwd: data.cwd,
+            repoUrl: data.repoUrl ?? null,
+            repoRef: data.repoRef ?? null,
+            metadata: (data.metadata as Record<string, unknown> | null | undefined) ?? null,
+            isPrimary: shouldBePrimary,
+          })
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        return row;
+      });
+
+      return created ? toWorkspace(created) : null;
+    },
+
+    updateWorkspace: async (
+      projectId: string,
+      workspaceId: string,
+      data: Partial<typeof projectWorkspaces.$inferInsert>,
+    ): Promise<ProjectWorkspace | null> => {
+      const existing = await db
+        .select()
+        .from(projectWorkspaces)
+        .where(
+          and(
+            eq(projectWorkspaces.id, workspaceId),
+            eq(projectWorkspaces.projectId, projectId),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+      if (!existing) return null;
+
+      const patch: Partial<typeof projectWorkspaces.$inferInsert> = {
+        updatedAt: new Date(),
+      };
+      if (data.name !== undefined) patch.name = data.name;
+      if (data.cwd !== undefined) patch.cwd = data.cwd;
+      if (data.repoUrl !== undefined) patch.repoUrl = data.repoUrl;
+      if (data.repoRef !== undefined) patch.repoRef = data.repoRef;
+      if (data.metadata !== undefined) patch.metadata = data.metadata;
+
+      const updated = await db.transaction(async (tx) => {
+        if (data.isPrimary === true) {
+          await tx
+            .update(projectWorkspaces)
+            .set({ isPrimary: false, updatedAt: new Date() })
+            .where(
+              and(
+                eq(projectWorkspaces.companyId, existing.companyId),
+                eq(projectWorkspaces.projectId, projectId),
+              ),
+            );
+          patch.isPrimary = true;
+        } else if (data.isPrimary === false) {
+          patch.isPrimary = false;
+        }
+
+        const row = await tx
+          .update(projectWorkspaces)
+          .set(patch)
+          .where(eq(projectWorkspaces.id, workspaceId))
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        if (!row) return null;
+
+        if (row.isPrimary) return row;
+
+        const hasPrimary = await tx
+          .select({ id: projectWorkspaces.id })
+          .from(projectWorkspaces)
+          .where(
+            and(
+              eq(projectWorkspaces.companyId, row.companyId),
+              eq(projectWorkspaces.projectId, row.projectId),
+              eq(projectWorkspaces.isPrimary, true),
+            ),
+          )
+          .then((rows) => rows[0] ?? null);
+
+        if (!hasPrimary) {
+          const nextPrimaryCandidate = await tx
+            .select({ id: projectWorkspaces.id })
+            .from(projectWorkspaces)
+            .where(
+              and(
+                eq(projectWorkspaces.companyId, row.companyId),
+                eq(projectWorkspaces.projectId, row.projectId),
+                eq(projectWorkspaces.id, row.id),
+              ),
+            )
+            .then((rows) => rows[0] ?? null);
+          const alternateCandidate = await tx
+            .select({ id: projectWorkspaces.id })
+            .from(projectWorkspaces)
+            .where(
+              and(
+                eq(projectWorkspaces.companyId, row.companyId),
+                eq(projectWorkspaces.projectId, row.projectId),
+              ),
+            )
+            .orderBy(asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id))
+            .then((rows) => rows.find((candidate) => candidate.id !== row.id) ?? null);
+
+          await ensureSinglePrimaryWorkspace(tx, {
+            companyId: row.companyId,
+            projectId: row.projectId,
+            keepWorkspaceId: alternateCandidate?.id ?? nextPrimaryCandidate?.id ?? row.id,
+          });
+          const refreshed = await tx
+            .select()
+            .from(projectWorkspaces)
+            .where(eq(projectWorkspaces.id, row.id))
+            .then((rows) => rows[0] ?? row);
+          return refreshed;
+        }
+
+        return row;
+      });
+
+      return updated ? toWorkspace(updated) : null;
+    },
+
+    removeWorkspace: async (projectId: string, workspaceId: string): Promise<ProjectWorkspace | null> => {
+      const existing = await db
+        .select()
+        .from(projectWorkspaces)
+        .where(
+          and(
+            eq(projectWorkspaces.id, workspaceId),
+            eq(projectWorkspaces.projectId, projectId),
+          ),
+        )
+        .then((rows) => rows[0] ?? null);
+      if (!existing) return null;
+
+      const removed = await db.transaction(async (tx) => {
+        const row = await tx
+          .delete(projectWorkspaces)
+          .where(eq(projectWorkspaces.id, workspaceId))
+          .returning()
+          .then((rows) => rows[0] ?? null);
+        if (!row) return null;
+
+        if (!row.isPrimary) return row;
+
+        const next = await tx
+          .select()
+          .from(projectWorkspaces)
+          .where(
+            and(
+              eq(projectWorkspaces.companyId, row.companyId),
+              eq(projectWorkspaces.projectId, row.projectId),
+            ),
+          )
+          .orderBy(asc(projectWorkspaces.createdAt), asc(projectWorkspaces.id))
+          .limit(1)
+          .then((rows) => rows[0] ?? null);
+
+        if (next) {
+          await ensureSinglePrimaryWorkspace(tx, {
+            companyId: row.companyId,
+            projectId: row.projectId,
+            keepWorkspaceId: next.id,
+          });
+        }
+
+        return row;
+      });
+
+      return removed ? toWorkspace(removed) : null;
+    },
   };
 }

ui/src/api/projects.ts

@@ -1,4 +1,4 @@
-import type { Project } from "@paperclip/shared";
+import type { Project, ProjectWorkspace } from "@paperclip/shared";
 import { api } from "./client";
 
 export const projectsApi = {
@@ -7,5 +7,13 @@ export const projectsApi = {
   create: (companyId: string, data: Record<string, unknown>) =>
     api.post<Project>(`/companies/${companyId}/projects`, data),
   update: (id: string, data: Record<string, unknown>) => api.patch<Project>(`/projects/${id}`, data),
+  listWorkspaces: (projectId: string) =>
+    api.get<ProjectWorkspace[]>(`/projects/${projectId}/workspaces`),
+  createWorkspace: (projectId: string, data: Record<string, unknown>) =>
+    api.post<ProjectWorkspace>(`/projects/${projectId}/workspaces`, data),
+  updateWorkspace: (projectId: string, workspaceId: string, data: Record<string, unknown>) =>
+    api.patch<ProjectWorkspace>(`/projects/${projectId}/workspaces/${workspaceId}`, data),
+  removeWorkspace: (projectId: string, workspaceId: string) =>
+    api.delete<ProjectWorkspace>(`/projects/${projectId}/workspaces/${workspaceId}`),
   remove: (id: string) => api.delete<Project>(`/projects/${id}`),
 };

ui/src/components/ProjectProperties.tsx

@@ -1,16 +1,17 @@
 import { useState } from "react";
 import { Link } from "react-router-dom";
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import type { Project } from "@paperclip/shared";
 import { StatusBadge } from "./StatusBadge";
 import { formatDate } from "../lib/utils";
 import { goalsApi } from "../api/goals";
+import { projectsApi } from "../api/projects";
 import { useCompany } from "../context/CompanyContext";
 import { queryKeys } from "../lib/queryKeys";
 import { Separator } from "@/components/ui/separator";
 import { Button } from "@/components/ui/button";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
-import { Plus, X } from "lucide-react";
+import { Plus, Star, Trash2, X } from "lucide-react";
 
 interface ProjectPropertiesProps {
   project: Project;
@@ -28,7 +29,11 @@ function PropertyRow({ label, children }: { label: string; children: React.React
 
 export function ProjectProperties({ project, onUpdate }: ProjectPropertiesProps) {
   const { selectedCompanyId } = useCompany();
+  const queryClient = useQueryClient();
   const [goalOpen, setGoalOpen] = useState(false);
+  const [workspaceName, setWorkspaceName] = useState("");
+  const [workspaceCwd, setWorkspaceCwd] = useState("");
+  const [workspaceRepoUrl, setWorkspaceRepoUrl] = useState("");
 
   const { data: allGoals } = useQuery({
     queryKey: queryKeys.goals.list(selectedCompanyId!),
@@ -50,6 +55,35 @@ export function ProjectProperties({ project, onUpdate }: ProjectPropertiesProps)
       }));
 
   const availableGoals = (allGoals ?? []).filter((g) => !linkedGoalIds.includes(g.id));
+  const workspaces = project.workspaces ?? [];
+
+  const invalidateProject = () => {
+    queryClient.invalidateQueries({ queryKey: queryKeys.projects.detail(project.id) });
+    if (selectedCompanyId) {
+      queryClient.invalidateQueries({ queryKey: queryKeys.projects.list(selectedCompanyId) });
+    }
+  };
+
+  const createWorkspace = useMutation({
+    mutationFn: (data: Record<string, unknown>) => projectsApi.createWorkspace(project.id, data),
+    onSuccess: () => {
+      setWorkspaceName("");
+      setWorkspaceCwd("");
+      setWorkspaceRepoUrl("");
+      invalidateProject();
+    },
+  });
+
+  const updateWorkspace = useMutation({
+    mutationFn: (input: { workspaceId: string; data: Record<string, unknown> }) =>
+      projectsApi.updateWorkspace(project.id, input.workspaceId, input.data),
+    onSuccess: invalidateProject,
+  });
+
+  const removeWorkspace = useMutation({
+    mutationFn: (workspaceId: string) => projectsApi.removeWorkspace(project.id, workspaceId),
+    onSuccess: invalidateProject,
+  });
 
   const removeGoal = (goalId: string) => {
     if (!onUpdate) return;
@@ -62,6 +96,16 @@ export function ProjectProperties({ project, onUpdate }: ProjectPropertiesProps)
     setGoalOpen(false);
   };
 
+  const submitWorkspace = () => {
+    if (!workspaceName.trim() || !workspaceCwd.trim()) return;
+    createWorkspace.mutate({
+      name: workspaceName.trim(),
+      cwd: workspaceCwd.trim(),
+      repoUrl: workspaceRepoUrl.trim() || null,
+      isPrimary: workspaces.length === 0,
+    });
+  };
+
   return (
     <div className="space-y-4">
       <div className="space-y-1">
@@ -148,6 +192,83 @@ export function ProjectProperties({ project, onUpdate }: ProjectPropertiesProps)
       <Separator />
 
       <div className="space-y-1">
+        <div className="py-1.5 space-y-2">
+          <div className="text-xs text-muted-foreground">Workspaces</div>
+          {workspaces.length === 0 ? (
+            <p className="text-sm text-muted-foreground">No project workspaces configured.</p>
+          ) : (
+            <div className="space-y-2">
+              {workspaces.map((workspace) => (
+                <div key={workspace.id} className="rounded-md border border-border p-2 space-y-1">
+                  <div className="flex items-center justify-between gap-2">
+                    <span className="text-sm font-medium truncate">{workspace.name}</span>
+                    <div className="flex items-center gap-1">
+                      {workspace.isPrimary ? (
+                        <span className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[10px] border border-border text-muted-foreground">
+                          <Star className="h-2.5 w-2.5" />
+                          Primary
+                        </span>
+                      ) : (
+                        <Button
+                          variant="outline"
+                          size="xs"
+                          className="h-5 px-1.5 text-[10px]"
+                          onClick={() => updateWorkspace.mutate({ workspaceId: workspace.id, data: { isPrimary: true } })}
+                        >
+                          Set primary
+                        </Button>
+                      )}
+                      <Button
+                        variant="ghost"
+                        size="icon-xs"
+                        onClick={() => removeWorkspace.mutate(workspace.id)}
+                        aria-label={`Delete workspace ${workspace.name}`}
+                      >
+                        <Trash2 className="h-3 w-3" />
+                      </Button>
+                    </div>
+                  </div>
+                  <p className="text-xs font-mono text-muted-foreground break-all">{workspace.cwd}</p>
+                  {workspace.repoUrl && (
+                    <p className="text-xs text-muted-foreground truncate">{workspace.repoUrl}</p>
+                  )}
+                </div>
+              ))}
+            </div>
+          )}
+          <div className="space-y-1.5 rounded-md border border-border p-2">
+            <input
+              className="w-full rounded border border-border bg-transparent px-2 py-1 text-xs outline-none"
+              value={workspaceName}
+              onChange={(e) => setWorkspaceName(e.target.value)}
+              placeholder="Workspace name"
+            />
+            <input
+              className="w-full rounded border border-border bg-transparent px-2 py-1 text-xs font-mono outline-none"
+              value={workspaceCwd}
+              onChange={(e) => setWorkspaceCwd(e.target.value)}
+              placeholder="/absolute/path/to/workspace"
+            />
+            <input
+              className="w-full rounded border border-border bg-transparent px-2 py-1 text-xs outline-none"
+              value={workspaceRepoUrl}
+              onChange={(e) => setWorkspaceRepoUrl(e.target.value)}
+              placeholder="Repo URL (optional)"
+            />
+            <Button
+              variant="outline"
+              size="xs"
+              className="h-6 px-2"
+              disabled={!workspaceName.trim() || !workspaceCwd.trim() || createWorkspace.isPending}
+              onClick={submitWorkspace}
+            >
+              Add workspace
+            </Button>
+          </div>
+        </div>
+
+        <Separator />
+
         <PropertyRow label="Created">
           <span className="text-sm">{formatDate(project.createdAt)}</span>
         </PropertyRow>