feat: project workspace clear/update UX and creation docs

Add granular workspace management — clear local folder or repo URL
independently instead of deleting the whole workspace. Fix project
create route typing. Document inline workspace creation in API docs
and skill references.

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

skills/paperclip/SKILL.md

@@ -75,6 +75,19 @@ Status values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`,
 
 **Step 9 — Delegate if needed.** Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`. Set `billingCode` for cross-team work.
 
+## Project Setup Workflow (CEO/Manager Common Path)
+
+When asked to set up a new project with workspace config (local folder and/or GitHub repo), use:
+
+1. `POST /api/companies/{companyId}/projects` with project fields.
+2. Optionally include `workspace` in that same create call, or call `POST /api/projects/{projectId}/workspaces` right after create.
+
+Workspace rules:
+
+- Provide at least one of `cwd` (local folder) or `repoUrl` (remote repo).
+- For repo-only setup, omit `cwd` and provide `repoUrl`.
+- Include both `cwd` + `repoUrl` when local and remote references should both be tracked.
+
 ## Critical Rules
 
 - **Always checkout** before working. Never PATCH to `in_progress` manually.
@@ -152,6 +165,8 @@ pls show the costs in either token or dollars on the /issues/{id} page. Make a p
 | Update task          | `PATCH /api/issues/:issueId` (optional `comment` field)                                    |
 | Add comment          | `POST /api/issues/:issueId/comments`                                                       |
 | Create subtask       | `POST /api/companies/:companyId/issues`                                                    |
+| Create project       | `POST /api/companies/:companyId/projects`                                                  |
+| Create project workspace | `POST /api/projects/:projectId/workspaces`                                             |
 | Release task         | `POST /api/issues/:issueId/release`                                                        |
 | List agents          | `GET /api/companies/:companyId/agents`                                                     |
 | Dashboard            | `GET /api/companies/:companyId/dashboard`                                                  |

skills/paperclip/references/api-reference.md

@@ -280,6 +280,58 @@ Use the dashboard for situational awareness, especially if you're a manager or C
 
 ---
 
+## Project Setup (Create + Workspace)
+
+When a CEO/manager task asks you to "set up a new project" and wire local + GitHub context, use this sequence.
+
+### Option A: One-call create with workspace
+
+```
+POST /api/companies/{companyId}/projects
+{
+  "name": "Paperclip Mobile App",
+  "description": "Ship iOS + Android client",
+  "status": "planned",
+  "goalIds": ["{goalId}"],
+  "workspace": {
+    "name": "paperclip-mobile",
+    "cwd": "/Users/me/paperclip-mobile",
+    "repoUrl": "https://github.com/acme/paperclip-mobile",
+    "repoRef": "main",
+    "isPrimary": true
+  }
+}
+```
+
+### Option B: Two calls (project first, then workspace)
+
+```
+POST /api/companies/{companyId}/projects
+{
+  "name": "Paperclip Mobile App",
+  "description": "Ship iOS + Android client",
+  "status": "planned"
+}
+
+POST /api/projects/{projectId}/workspaces
+{
+  "cwd": "/Users/me/paperclip-mobile",
+  "repoUrl": "https://github.com/acme/paperclip-mobile",
+  "repoRef": "main",
+  "isPrimary": true
+}
+```
+
+Workspace rules:
+
+- Provide at least one of `cwd` or `repoUrl`.
+- For repo-only setup, omit `cwd` and provide `repoUrl`.
+- The first workspace is primary by default.
+
+Project responses include `primaryWorkspace` and `workspaces`, which agents can use for execution context resolution.
+
+---
+
 ## Governance and Approvals
 
 Some actions require board approval. You cannot bypass these gates.
@@ -406,7 +458,7 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/companies/:companyId`          | Company details    |
 | GET    | `/api/companies/:companyId/projects` | List projects      |
 | GET    | `/api/projects/:projectId`           | Project details    |
-| POST   | `/api/companies/:companyId/projects` | Create project     |
+| POST   | `/api/companies/:companyId/projects` | Create project (optional inline `workspace`) |
 | PATCH  | `/api/projects/:projectId`           | Update project     |
 | GET    | `/api/projects/:projectId/workspaces` | List project workspaces |
 | POST   | `/api/projects/:projectId/workspaces` | Create project workspace |