feat(projects)!: complete the projects and labels domains

README.md

@@ -145,7 +145,9 @@ A schema is the input contract only: it cannot know your team's workflow states,
 
 ## Coverage
 
-Linear's GraphQL API exposes **537 root operations** (164 queries, 373 mutations). Linearis wires **83 of them** directly, plus a number of nested reads — chosen to cover planning and issue work end to end rather than the whole API.
+Linear's GraphQL API exposes **520 root operations** (159 queries, 361 mutations). Linearis wires **114 of them** directly, plus a number of nested reads — chosen to cover planning and issue work end to end rather than the whole API.
+
+Both figures are checkable rather than asserted: `npm run count:root-fields -- --verify` parses `graphql/**/*.graphql` and cross-checks the result against a live introspection of the schema.
 
 The table below is the honest picture of the whole surface — what works today, and what you'll need the [Linear MCP](#linearis-vs-linear-mcp) or a raw API call for.
 
@@ -154,26 +156,26 @@ The table below is the honest picture of the whole surface — what works today,
 | Area | Extent | What you can do | Not covered |
 |---|---|---|---|
 | `auth` | ✅ | Interactive login, token status, logout | — |
-| Discussions | ✅ | Root threads and replies on issues, projects, and initiatives; edit, delete, resolve/unresolve; emoji reactions on any of them | Custom workspace emoji management |
+| Discussions | ✅ | Root threads and replies on issues, projects, and initiatives; edit, delete, resolve/unresolve; emoji reactions on any of them | Custom workspace emoji management, and comment threads on a status update — `CommentCreateInput.projectUpdateId` makes an update its own discussion surface, which neither `projects updates` nor `initiatives updates` exposes |
 | `issues` | ✅ | List, filter, full-text search, read, create, update, batch create/update, archive/unarchive, delete/restore, snooze; assign labels/assignee/delegate/state/priority/project/cycle/team (including moves between teams); subscribe/unsubscribe, share/unshare, reminders; find the issue for a git branch (`from-branch`); relations (list/add/remove); activity history | Deliberately excluded: the AI-assist and integration-suggestion queries (Figma file lookup, filter/repository suggestions, title-from-customer-request) — see the Integrations row — and `issuePriorityValues`, a static list already in the help text |
 | `initiatives` | 🟡 | List, read, create, update, archive/unarchive, delete; attach/detach projects; initiative-to-initiative relations; initiative updates (list, read, create, update, archive/unarchive); discussions | Initiative labels, lead-team reassignment, relation reordering |
-| `projects` | 🟡 | List, read, create, update, archive/unarchive, delete; assign project labels by name (`--labels`, `--label-mode`, `--clear-labels`); discussions | Project updates (status posts), project-label CRUD, project relations, project status administration, Slack channel creation |
+| `projects` | ✅ | List, full-text search, read, create, update, delete (trash) and unarchive (restore), disable external sync; assign project labels by name (`--labels`, `--label-mode`, `--clear-labels`); status updates (list, read, create, edit, archive/unarchive, remind); dependency relations (list, read, add, update, remove); administer the workspace project status flow (`projects statuses`); discussions; activity timeline | Deliberately excluded: Slack-channel creation and the AI filter suggestion, which are `[Internal]` integration plumbing — see the Integrations row. Project labels live under `labels --type project`; milestone delete/move under `milestones` |
 | `documents` | 🟡 | List, read, create, update, delete | Content history, document full-text search, unarchive |
 | `milestones` | 🟡 | List, read, create, update (per project) | Delete, reordering/move between projects |
 | `attachments` | 🟡 | List on an issue, create from a URL, delete, disable external sync | Update, and the provider-specific link mutations (GitHub PR/issue, GitLab MR, Slack, Jira, Zendesk, Intercom, Front, Salesforce, Discord) |
 | `files` | 🟡 | Upload a file, download via signed URL | Delete uploads, image-from-URL, CSV export reports |
 | `teams` | 🟡 | List, read, create, update; list/add/remove members | Delete, workflow-state administration, triage responsibility, git automation, SLA configuration |
-| `labels` | 🟠 | Issue labels: list, read, create, update, delete; project labels: list (`--type project`) | Project-label create/update/delete, initiative labels, retire/restore |
+| `labels` | 🟡 | Issue and project labels alike (`--type issue\|project`): list, read, create, update, delete, retire/restore; label groups (`--group`, `--parent`) | Initiative labels |
 | `cycles` | 🟠 | List cycles, read a cycle with its issues | Create, update, archive, shift all, start upcoming cycle |
 | `users` | 🟠 | List workspace members | Read a single user, update, role changes, suspend/unsuspend, user settings, session management |
-| Integrations | 🔴 | — | All 73 integration root fields (65 mutations, 8 queries): Slack, GitHub, GitLab, Jira, Figma, Sentry, PagerDuty, Intercom, Salesforce, and more |
+| Integrations | 🔴 | — | All 70 integration root fields (62 mutations, 8 queries): Slack, GitHub, GitLab, Jira, Figma, Sentry, PagerDuty, Intercom, Salesforce, and more. Also the `[Internal]` per-entity integration plumbing excluded from the `issues` and `projects` rows: Slack channel creation and dismissal on a project, Slack/Teams/Jira project posts, and the AI-assist suggestion queries (issue and project filter suggestions, Figma file lookup, title-from-customer-request) |
 | Organization & admin | 🔴 | — | Org settings, invites, domains, webhooks, OAuth apps, audit log, SSO |
 | Releases | 🔴 | — | Releases, release pipelines, stages, release notes |
 | Customers (CRM) | 🔴 | — | Customers, needs, tiers, customer statuses |
 | Views & templates | 🔴 | — | Custom views, favorites, templates, view preferences |
 | Notifications | 🔴 | — | Inbox, subscriptions, snooze, mark read, push subscriptions |
 | Agent sessions | 🔴 | — | Agent sessions, activities, skills, semantic search |
-| Roadmaps | 🔴 | — | Roadmaps and roadmap-to-project links |
+| Roadmaps | 🔴 | — | Roadmaps and roadmap-to-project links. `roadmapToProject*` is deprecated in favour of `initiativeToProject*`, which `initiatives` already wires |
 | Imports & exports | 🔴 | — | Jira/Asana/Clubhouse/GitHub/CSV import jobs |
 | Schedules | 🔴 | — | Time schedules and on-call rotations |
 

docs/architecture.md

@@ -127,7 +127,7 @@ Shared utilities used across layers.
 - **src/commands/cycles.ts** - Cycle listing and reading
 - **src/commands/teams.ts** - Team listing
 - **src/commands/users.ts** - User listing
-- **src/commands/projects.ts** - Project listing
+- **src/commands/projects/** - Project commands (`index.ts` registers the domain, `entity.ts` holds CRUD and discussions)
 - **src/commands/labels.ts** - Label listing
 - **src/commands/comments.ts** - Comment creation
 - **src/commands/embeds.ts** - File operations

docs/files.md

@@ -22,7 +22,9 @@ Each resolver converts a human-friendly identifier (name, key, or slug) into a U
 - **cycle-resolver.ts** -- `resolveCycleId(client, nameOrId, teamFilter?)`
 - **status-resolver.ts** -- `resolveStatusId(client, nameOrId, teamId?)`
 - **issue-resolver.ts** -- `resolveIssueId(client, issueIdOrIdentifier)`
-- **milestone-resolver.ts** -- `resolveMilestoneId(gqlClient, sdkClient, nameOrId, projectNameOrId?)`
+- **milestone-resolver.ts** -- `resolveMilestoneId(gqlClient, nameOrId, projectNameOrId?)` — a project scope is authoritative, never widened to the workspace
+- **project-status-resolver.ts** -- `resolveProjectStatusId(client, nameOrId, { includeArchived? })`
+- **project-relation-resolver.ts** -- `resolveProjectRelation(client, relationOrProjectId, relatedProjectId?)` — returns `{ id, inverted }`; `inverted` tells callers writing per-end fields to swap the two ends
 
 ## Service Layer (`src/services/`)
 
@@ -35,8 +37,12 @@ Business logic and CRUD operations. Services use `GraphQLClient` exclusively and
 - **cycle-service.ts** -- `listCycles`, `getCycle`
 - **team-service.ts** -- `listTeams`
 - **user-service.ts** -- `listUsers`
-- **project-service.ts** -- `listProjects`
-- **label-service.ts** -- `listLabels`
+- **project-service.ts** -- `listProjects`, `searchProjects`, `getProject`, `createProject`, `updateProject`, `applyProjectLabels`, `disableProjectExternalSync`, `unarchiveProject`, `deleteProject`
+- **project-update-service.ts** -- Project status posts: `listProjectUpdates`, `getProjectUpdate`, `createProjectUpdate`, `editProjectUpdate`, archive/unarchive, `remindProjectUpdate`
+- **project-status-service.ts** -- The workspace project status flow: list/get/create/update, `reassignProjectStatus`, archive/unarchive
+- **project-relation-service.ts** -- Project dependencies: list (per project and workspace-wide), get, create, update, delete
+- **project-activity-service.ts** -- Merges project discussions, history and status updates into one chronological timeline
+- **label-service.ts** -- `listLabels`, `listProjectLabels`, and get/create/update/delete/retire/restore dispatching on `LabelType`
 - **comment-service.ts** -- `createComment`
 - **file-service.ts** -- File upload and download operations for Linear uploads
 
@@ -52,8 +58,8 @@ CLI orchestration. Each file registers a command group via a `setup*Commands(pro
 - **cycles.ts** -- Cycle listing and detail reading
 - **teams.ts** -- Team listing
 - **users.ts** -- User listing
-- **projects.ts** -- Project listing
-- **labels.ts** -- Label listing
+- **projects/** -- Project commands. `index.ts` owns `PROJECTS_META` and registers the domain; `entity.ts` holds CRUD, search, sync and discussions; `updates.ts`, `statuses.ts` and `relations.ts` hold the subgroups
+- **labels.ts** -- Label commands for both issue and project labels (`--type`)
 - **comments.ts** -- Comment creation
 - **embeds.ts** -- File download from Linear upload URLs
 

graphql/mutations/labels.graphql

@@ -1,5 +1,8 @@
 # ------------------------------------------------------------
-# GraphQL mutations for Linear issue labels
+# GraphQL mutations for Linear issue and project labels
+#
+# The two label kinds are separate types with parallel mutations;
+# `labels --type issue|project` picks between them.
 # ------------------------------------------------------------
 
 mutation CreateIssueLabel($input: IssueLabelCreateInput!) {
@@ -26,3 +29,68 @@ mutation DeleteIssueLabel($id: String!) {
     entityId
   }
 }
+
+# Retire an issue label
+#
+# Retired labels stay on the issues that already carry them but cannot be
+# applied to new ones — a softer alternative to delete.
+mutation RetireIssueLabel($id: String!) {
+  issueLabelRetire(id: $id) {
+    success
+    issueLabel {
+      ...LabelFields
+    }
+  }
+}
+
+mutation RestoreIssueLabel($id: String!) {
+  issueLabelRestore(id: $id) {
+    success
+    issueLabel {
+      ...LabelFields
+    }
+  }
+}
+
+mutation CreateProjectLabel($input: ProjectLabelCreateInput!) {
+  projectLabelCreate(input: $input) {
+    success
+    projectLabel {
+      ...ProjectLabelFields
+    }
+  }
+}
+
+mutation UpdateProjectLabel($id: String!, $input: ProjectLabelUpdateInput!) {
+  projectLabelUpdate(id: $id, input: $input) {
+    success
+    projectLabel {
+      ...ProjectLabelFields
+    }
+  }
+}
+
+mutation DeleteProjectLabel($id: String!) {
+  projectLabelDelete(id: $id) {
+    success
+    entityId
+  }
+}
+
+mutation RetireProjectLabel($id: String!) {
+  projectLabelRetire(id: $id) {
+    success
+    projectLabel {
+      ...ProjectLabelFields
+    }
+  }
+}
+
+mutation RestoreProjectLabel($id: String!) {
+  projectLabelRestore(id: $id) {
+    success
+    projectLabel {
+      ...ProjectLabelFields
+    }
+  }
+}

graphql/mutations/project-relations.graphql

@@ -0,0 +1,31 @@
+# ------------------------------------------------------------
+# GraphQL mutations for Linear project dependency relations
+# ------------------------------------------------------------
+
+mutation CreateProjectRelation($input: ProjectRelationCreateInput!) {
+  projectRelationCreate(input: $input) {
+    success
+    projectRelation {
+      ...ProjectRelationCoreFields
+    }
+  }
+}
+
+mutation UpdateProjectRelation(
+  $id: String!
+  $input: ProjectRelationUpdateInput!
+) {
+  projectRelationUpdate(id: $id, input: $input) {
+    success
+    projectRelation {
+      ...ProjectRelationCoreFields
+    }
+  }
+}
+
+mutation DeleteProjectRelation($id: String!) {
+  projectRelationDelete(id: $id) {
+    success
+    entityId
+  }
+}

graphql/mutations/project-statuses.graphql

@@ -0,0 +1,58 @@
+# ------------------------------------------------------------
+# GraphQL mutations for the workspace project status flow
+# ------------------------------------------------------------
+
+mutation CreateProjectStatus($input: ProjectStatusCreateInput!) {
+  projectStatusCreate(input: $input) {
+    success
+    status {
+      ...ProjectStatusCoreFields
+    }
+  }
+}
+
+mutation UpdateProjectStatus($id: String!, $input: ProjectStatusUpdateInput!) {
+  projectStatusUpdate(id: $id, input: $input) {
+    success
+    status {
+      ...ProjectStatusCoreFields
+    }
+  }
+}
+
+# Archive a status
+#
+# Linear refuses this while projects are still assigned to the status, or
+# when it is the last status of its type.
+mutation ArchiveProjectStatus($id: String!) {
+  projectStatusArchive(id: $id) {
+    success
+    entity {
+      ...ProjectStatusCoreFields
+    }
+  }
+}
+
+mutation UnarchiveProjectStatus($id: String!) {
+  projectStatusUnarchive(id: $id) {
+    success
+    entity {
+      ...ProjectStatusCoreFields
+    }
+  }
+}
+
+# Move every project off one status and onto another
+#
+# The payload carries no entity — only whether the reassignment ran.
+mutation ReassignProjectStatus(
+  $originalProjectStatusId: String!
+  $newProjectStatusId: String!
+) {
+  projectReassignStatus(
+    originalProjectStatusId: $originalProjectStatusId
+    newProjectStatusId: $newProjectStatusId
+  ) {
+    success
+  }
+}

graphql/mutations/project-updates.graphql

@@ -0,0 +1,52 @@
+# ------------------------------------------------------------
+# GraphQL mutations for Linear project status updates
+#
+# `projectUpdateDelete` is deliberately not wired: Linear deprecates it
+# in favour of `projectUpdateArchive`, which is reversible.
+# ------------------------------------------------------------
+
+mutation CreateProjectUpdate($input: ProjectUpdateCreateInput!) {
+  projectUpdateCreate(input: $input) {
+    success
+    projectUpdate {
+      ...ProjectUpdateCoreFields
+    }
+  }
+}
+
+mutation EditProjectUpdate($id: String!, $input: ProjectUpdateUpdateInput!) {
+  projectUpdateUpdate(id: $id, input: $input) {
+    success
+    projectUpdate {
+      ...ProjectUpdateCoreFields
+    }
+  }
+}
+
+mutation ArchiveProjectUpdate($id: String!) {
+  projectUpdateArchive(id: $id) {
+    success
+    entity {
+      ...ProjectUpdateCoreFields
+    }
+  }
+}
+
+mutation UnarchiveProjectUpdate($id: String!) {
+  projectUpdateUnarchive(id: $id) {
+    success
+    entity {
+      ...ProjectUpdateCoreFields
+    }
+  }
+}
+
+# Nudge someone to post the next update
+#
+# The payload carries no entity — there is nothing to return but whether
+# the notification was created.
+mutation CreateProjectUpdateReminder($projectId: String!, $userId: String) {
+  createProjectUpdateReminder(projectId: $projectId, userId: $userId) {
+    success
+  }
+}

graphql/mutations/projects.graphql

@@ -30,28 +30,64 @@ mutation UpdateProject($id: String!, $input: ProjectUpdateInput!) {
   }
 }
 
-mutation ArchiveProject($id: String!) {
-  projectArchive(id: $id) {
+# Restore a trashed project
+#
+# Linear collapses "archived" and "trashed" into a single state, so this
+# restores whatever projectDelete put away.
+mutation UnarchiveProject($id: String!) {
+  projectUnarchive(id: $id) {
     success
     entity {
       ...ProjectDetailWithDefaultConnectionsFields
     }
   }
 }
 
-mutation UnarchiveProject($id: String!) {
-  projectUnarchive(id: $id) {
+# Trash a project
+#
+# Reversible: UnarchiveProject restores it.
+mutation DeleteProject($id: String!) {
+  projectDelete(id: $id) {
     success
     entity {
       ...ProjectDetailWithDefaultConnectionsFields
     }
   }
 }
 
-mutation DeleteProject($id: String!) {
-  projectDelete(id: $id) {
+# Stop syncing a project with an external tracker
+#
+# Mirrors `attachments disable-sync`: the link stays, the updates stop.
+mutation DisableProjectExternalSync(
+  $projectId: String!
+  $syncSource: ExternalSyncService!
+) {
+  projectExternalSyncDisable(projectId: $projectId, syncSource: $syncSource) {
     success
-    entity {
+    project {
+      ...ProjectDetailWithDefaultConnectionsFields
+    }
+  }
+}
+
+# Add one label to a project
+#
+# Incremental, unlike `ProjectUpdateInput.labelIds`, which replaces the
+# whole set — so `--label-mode add` needs no read of the current labels
+# and cannot drop the ones it did not see.
+mutation AddProjectLabel($id: String!, $labelId: String!) {
+  projectAddLabel(id: $id, labelId: $labelId) {
+    success
+    project {
+      ...ProjectDetailWithDefaultConnectionsFields
+    }
+  }
+}
+
+mutation RemoveProjectLabel($id: String!, $labelId: String!) {
+  projectRemoveLabel(id: $id, labelId: $labelId) {
+    success
+    project {
       ...ProjectDetailWithDefaultConnectionsFields
     }
   }