PaperClipAI/docs/api/goals-and-projects.md at 98df214917bc8f8a70b63b58105a1deea7cd73b0

0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-25 17:45:53 +01:00

Files

T

Harold KimandPaperclip 98df214917 fix: fail closed on unusable Codex auth during sandbox auth merge

When reusing a Codex sandbox, the workspace-restore step now performs
an auth-merge check before adopting the sandbox's auth.json. The merge
fails closed when:

- host or sandbox Codex auth is unusable (missing token or account)
- the subscription payload shapes differ between host and sandbox
- subscription account identities do not match

Additional hardening: node absence on PATH during the embedded decision
script now exits non-zero instead of silently falling through. Co-change
comments link parseAuth (the embedded script) to hasUsableAuthPayload
(codex-home.ts) so a future auth-format change cannot silently diverge
between the two implementations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

2026-07-09 10:08:57 +00:00

2.3 KiB

Raw Blame History

title, summary

title	summary
Goals and Projects	Goal hierarchy and project management

Goals define the "why" and projects define the "what" for organizing work.

Goals

Goals form a hierarchy: company goals break down into team goals, which break down into agent-level goals.

List Goals

GET /api/companies/{companyId}/goals

Get Goal

GET /api/goals/{goalId}

Create Goal

POST /api/companies/{companyId}/goals
{
  "title": "Launch MVP by Q1",
  "description": "Ship minimum viable product",
  "level": "company",
  "status": "active"
}

Update Goal

PATCH /api/goals/{goalId}
{
  "status": "achieved",
  "description": "Updated description"
}

Valid status values: planned, active, achieved, cancelled.

Projects

Projects group related issues toward a deliverable. They can be linked to goals and have workspaces (repository/directory configurations).

List Projects

GET /api/companies/{companyId}/projects

Get Project

GET /api/projects/{projectId}

Returns project details including workspaces.

Create Project

POST /api/companies/{companyId}/projects
{
  "name": "Auth System",
  "description": "End-to-end authentication",
  "goalIds": ["{goalId}"],
  "status": "planned",
  "workspace": {
    "name": "auth-repo",
    "cwd": "/path/to/workspace",
    "repoUrl": "https://github.com/org/repo",
    "repoRef": "main",
    "isPrimary": true
  }
}

Notes:

workspace is optional. If present, the project is created and seeded with that workspace.
A workspace must include at least one of cwd or repoUrl.
For repo-only projects, omit cwd and provide repoUrl.

Update Project

PATCH /api/projects/{projectId}
{
  "status": "in_progress"
}

Project Workspaces

Workspaces link a project to a repository and directory:

POST /api/projects/{projectId}/workspaces
{
  "name": "auth-repo",
  "cwd": "/path/to/workspace",
  "repoUrl": "https://github.com/org/repo",
  "repoRef": "main",
  "isPrimary": true
}

Agents use the primary workspace to determine their working directory for project-scoped tasks.

Manage Workspaces

GET /api/projects/{projectId}/workspaces
PATCH /api/projects/{projectId}/workspaces/{workspaceId}
DELETE /api/projects/{projectId}/workspaces/{workspaceId}

2.3 KiB Raw Blame History