diff --git a/.github/workflows/linear-project.yml b/.github/workflows/linear-project.yml
new file mode 100644
index 00000000..13004c7e
--- /dev/null
+++ b/.github/workflows/linear-project.yml
@@ -0,0 +1,45 @@
+# Puts each new GitHub issue's Linear copy into the Linear project cloudpid (scripts/linear-project.sh). Linear's GitHub
+# Issues sync copies the issue into the team SPI but into no project, and agents read issues by project
+# (docs/agents/issue-tracker.md). It runs for `cloudpid-report` issues too: the GitHub App opens them, and an issue
+# opened by an App starts workflows (one opened with GITHUB_TOKEN would not). A dispatch takes an issue number, to retry
+# one whose run failed; an issue opened before the sync existed has no copy to move. Needs the repository secret
+# LINEAR_API_KEY: a Linear API key that may edit SPI's issues.
+name: linear project
+
+on:
+  issues:
+    types: [opened]
+  workflow_dispatch:
+    inputs:
+      issue:
+        description: GitHub issue number
+        required: true
+        type: number
+
+permissions: {}
+
+concurrency:
+  group: linear-project-${{ github.event.issue.number || inputs.issue }}
+
+jobs:
+  project:
+    name: project
+    # Forks have neither the secret nor the Linear project.
+    if: github.repository == 'ian-pascoe/cloudpid'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read # sparse checkout of the script
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          sparse-checkout: scripts/linear-project.sh
+          sparse-checkout-cone-mode: false
+      - name: Add to the project
+        env:
+          LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+          # The Linear project cloudpid (team SPI).
+          LINEAR_PROJECT: c5b4ec54-51b3-4742-88a1-0a75c7c646a8
+          ISSUE_URL: ${{ github.event.issue.html_url || format('{0}/{1}/issues/{2}', github.server_url, github.repository, inputs.issue) }}
+        run: scripts/linear-project.sh
diff --git a/AGENTS.md b/AGENTS.md
index e81c014a..eb2c6856 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -50,7 +50,7 @@ Every workspace package (`apps/*`, `infra`, `packages/*`) is named `@cloudpid/<d
 
 ### Issue tracker
 
-Issues are tracked in GitHub Issues for `ian-pascoe/cloudpid` via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+Issues live in Linear (team SPI, project cloudpid); GitHub Issues are the public intake and sync one-way into it. Reach Linear through Executor's Linear app, falling back to the `linear` CLI. See `docs/agents/issue-tracker.md`.
 
 ### Triage labels
 
diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index b1ccd008..046934e0 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -1,48 +1,101 @@
-# Issue tracker: GitHub
+# Issue tracker: Linear
 
-Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+Issues and specs for this repo live in **Linear**: workspace `spiritledsoftware`, team **SPI** (Spirit-Led Software), project **cloudpid**. The team also holds other repos' projects (Commissary, lspctl, Neopane, …), so create every issue for this repo in project `cloudpid`, and scope every read to it.
 
-## Conventions
+**GitHub Issues are the public intake.** Outside users open issues on GitHub, and cloudpid agents file `cloudpid-report` issues there through the GitHub App (below). A one-way sync (GitHub → Linear) copies each new one into team SPI, carrying its GitHub URL as an attachment. Comments in its synced thread sync both ways (**Comment on an issue**), and closing it in Linear closes it on GitHub. The sync puts the copy in no project; the workflow `linear project` (`.github/workflows/linear-project.yml`, `scripts/linear-project.sh`) moves it into cloudpid once it appears. Dispatch that workflow with an issue number to retry one whose run failed (an issue opened before the sync existed has no copy to move). Work every issue in Linear and refer to it by its Linear identifier (`SPI-123`). Never create issues with `gh issue create`. A GitHub number (`#745`) resolves to the Linear issue that carries its URL (**Read an issue** below); issues and PRs share GitHub's numbers, so when none carries it, try `gh pr view <n>`.
+
+Issues labelled `cloudpid-report` were filed by a cloudpid agent through the GitHub App about cloudpid itself (the `cloudpid_report` tool, ADR-0051); their footer, after the last `---`, names the stage, version, model and Session they came from. Triage their Linear copies like any `needs-triage` issue (`docs/agents/triage-labels.md`).
 
-- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
-- **Read an issue**: `gh issue view <number> --json number,title,body,labels,comments`.
-- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
-- **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body.
-- **Comment on an issue**: `gh issue comment <number> --body "..."`
-- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
-- **Close**: `gh issue close <number> --comment "..."`
+## How to reach Linear
 
-Issues labelled `cloudpid-report` were filed by a cloudpid agent through the GitHub App about cloudpid itself (the `cloudpid_report` tool, ADR-0051); their footer, after the last `---`, names the stage, version, model and Session they came from. Triage them like any `needs-triage` issue (`docs/agents/triage-labels.md`).
+1. **Executor (default).** Executor's Linear app, through its MCP tools `call` / `execute`, under `tools.linear.*` with account `acc_0c3d8286-c8a7-491e-ae0c-e433e1367c79`.
+   - Every tool takes `{ accountId, input: { arguments: { … }, select: "<GraphQL selection>" } }`.
+   - Issue ids accept identifiers (`SPI-123`).
+   - A call may pause for the user's approval. Show the request and resume it; never repeat the call.
+2. **The `linear` CLI (fallback)**, `@schpet/linear-cli`, installed globally through mise and signed in with `linear auth login`. Use it when:
+   - Executor's tools aren't available in the session;
+   - its Linear app fails;
+   - the user declines an approval.
 
-Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+   With the CLI:
+   - Pass `--team SPI` to every query (no repo default is configured).
+   - Pass `--no-input` to writes.
+   - Pass markdown through `--description-file` / `--body-file`.
+   - Use `linear api` (GraphQL on stdin) for anything without a dedicated command.
 
-## Pull requests as a triage surface
+Both reach the same API, so the GraphQL selections below work in either.
 
-**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+| Thing               | Value                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Team `SPI`          | `86ad747a-262a-4ab8-a716-3a7b3cd5a6af`                                                                                                                                                                                                                                                                                                                                                                                      |
+| Project `cloudpid`  | `c5b4ec54-51b3-4742-88a1-0a75c7c646a8`                                                                                                                                                                                                                                                                                                                                                                                      |
+| States (name: type) | Backlog: backlog `0b2345bf-8a16-4fd5-8150-ab08e0d74a26` · Todo: unstarted `ad8f9e8b-f89d-4623-8571-68607c315057` · Blocked: unstarted `e417759b-5003-44fd-bfdd-fc6159afb145` · In Progress: started `a52ed858-c23e-4098-8fd1-a313fb0f2204` · In Review: started `62d08185-be69-4fe5-873a-1710a52fb9aa` · Done: completed `d8e326e4-cff3-4cca-a760-5b19efccf264` · Canceled: canceled `9bff72eb-c2dc-4f1a-a6a5-c7522d98fc15` |
 
-When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+Label ids are in `docs/agents/triage-labels.md`. For any other label: `tools.linear.query_issueLabels` with `filter: { name: { eq: "<name>" }, team: { key: { eq: "SPI" } } }`, or `linear label list --team SPI --json`.
 
-- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
-- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
-- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+## Conventions
 
-GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+- **Create an issue**:
+  - Executor: `tools.linear.mutation_issueCreate`, `arguments: { input: { teamId, projectId, title, description, labelIds?, parentId? } }`, `select: "identifier url"`.
+  - CLI: `linear issue create --team SPI --project cloudpid --title "…" --description-file body.md [--label <name>] [--parent SPI-1] --no-input`.
+- **Read an issue**:
+  - Executor: `tools.linear.query_issue`, `arguments: { id: "SPI-123" }`, `select: "identifier title description url state { name type } labels { nodes { name } } assignee { name } parent { identifier } children { nodes { identifier title state { type } } } comments { nodes { body createdAt user { name } } } attachments { nodes { url } }"`.
+  - CLI: `linear issue view SPI-123 --json`.
+  - From a GitHub number: Executor `tools.linear.query_attachmentsForURL`, `arguments: { url: "https://github.com/ian-pascoe/cloudpid/issues/<n>" }`, `select: "nodes { sourceType issue { identifier } }"`; take the node whose `sourceType` is `github` (the sync's; another issue may link the same URL by hand). The CLI uses the same query through `linear api`.
+- **List issues**:
+  - Executor: `tools.linear.query_issues`, `arguments: { first: 100, filter: { project: { id: { eq: "<cloudpid>" } }, state: { type: { nin: ["completed", "canceled"] } }, labels: { name: { eq: "<label>" } } } }`, `select: "nodes { identifier title state { name } labels { nodes { name } } assignee { name } }"`.
+  - CLI: `linear issue query --team SPI --project cloudpid [--label <name>] [--state backlog --state unstarted --state started] --json`.
+- **Make an issue a sub-issue of a parent**:
+  - Executor: `parentId: "SPI-1"` at creation, or `tools.linear.mutation_issueUpdate` with `arguments: { id, input: { parentId } }`.
+  - CLI: `--parent SPI-1` on `issue create` / `issue update`.
+- **Comment on an issue**:
+  - Executor: `tools.linear.mutation_commentCreate`, `arguments: { input: { issueId: "SPI-123", body } }`.
+  - CLI: `linear issue comment add SPI-123 --body-file comment.md`.
+  - A plain comment stays in Linear. To reach the reporter of a synced GitHub issue (a `needs-info` question, a won't-fix reason), reply in its **synced thread**: the root comment whose body starts "This comment thread is synced to a corresponding GitHub issue" (read the issue's `comments { nodes { id body parent { id } } }`, or `linear issue comment list SPI-123 --json`). Executor: add `parentId: "<root comment id>"`; CLI: `--reply-to <root comment id>`. A reply there shows on GitHub.
+- **Apply / remove labels**:
+  - Executor: `tools.linear.mutation_issueAddLabel` / `mutation_issueRemoveLabel`, `arguments: { id: "SPI-123", labelId }`.
+  - CLI: `linear issue update SPI-123 --add-label <name>` / `--remove-label <name>`.
+- **Close**:
+  - Comment first, then set the state to Done, or Canceled for won't-do: Executor `tools.linear.mutation_issueUpdate`, `arguments: { id, input: { stateId } }`; CLI `linear issue update SPI-123 --state Done`.
+  - A duplicate is a relation: `mutation_issueRelationCreate` with `type: "duplicate"`, or `linear issue relation add SPI-2 duplicate SPI-1`.
+  - Closing a synced issue closes its GitHub copy.
+
+## Pull requests
+
+Code and PRs stay on GitHub (`gh`, the `code-host` skill). To close an issue from a PR, put `Fixes SPI-123` in the PR body (Linear's magic words). Linear's GitHub integration links the PR and moves the issue to Done when it merges. Use the Linear identifier for synced GitHub issues too: closing in Linear closes the GitHub copy.
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ When `yes`, read and act on external PRs with `gh` (`gh pr view <n> --comments`, `gh pr diff <n>`, `gh pr comment`, `gh pr edit --add-label`, `gh pr close`), and list them with `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, labels: [.labels[].name]}'`.
 
 ## When a skill says "publish to the issue tracker"
 
-Create a GitHub issue.
+Create a Linear issue in team SPI, project cloudpid.
 
 ## When a skill says "fetch the relevant ticket"
 
-Read it as in **Read an issue** above.
+Read it as in **Read an issue** above; a GitHub number resolves through its URL.
 
 ## Wayfinding operations
 
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
 
-- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
-- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
-- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
-- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
-- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
-- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
+- **Map**: an issue labelled `wayfinder:map` in project cloudpid, holding the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: a sub-issue of the map (**Make an issue a sub-issue of a parent**), labelled `wayfinder:<type>` (`research` / `prototype` / `grilling` / `task`). Once claimed, it is assigned to the driving dev.
+- **Blocking**: Linear's `blocks` relation, from the blocker to the blocked ticket.
+  - Executor: `tools.linear.mutation_issueRelationCreate`, `arguments: { input: { type: "blocks", issueId: "<blocker>", relatedIssueId: "<child>" } }`.
+  - CLI: `linear issue relation add <child> blocked-by <blocker>`.
+  - A ticket is unblocked when every blocker is completed or canceled.
+- **Frontier query**: one query lists every child with its state, labels, assignee and blockers.
+  - Executor: `tools.linear.query_issue` with `arguments: { id: "<map>" }` and the block below as its `select`.
+  - CLI: `linear api --variable id=<map>` with `query($id: String!) { issue(id: $id) { … } }` on stdin, the block below in place of `…`.
+
+  ```graphql
+  children(first: 250) { nodes { identifier title state { type } labels { nodes { name } } assignee { name }
+    inverseRelations { nodes { type issue { identifier state { type } } } } } }
+  ```
+
+  A child's `blocks` entries in `inverseRelations` are its blockers. Keep the children whose state type is not `completed` / `canceled`, that have no assignee, and whose blockers are all `completed` / `canceled`; the first one wins.
+
+- **Claim**, the session's first write:
+  - Executor: `tools.linear.mutation_issueUpdate`, `arguments: { id, input: { assigneeId: "<viewer id>" } }` (`tools.linear.query_viewer`, `select: "id"`).
+  - CLI: `linear issue update <n> --assignee @me`.
+- **Resolve**: comment the answer, set the state to Done (**Close**), then append a context pointer (gist + link) to the map's Decisions-so-far. Read the map's description first: `issueUpdate`'s `description` replaces it whole, and the CLI's `--description-file` does the same.
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
index 21317b18..75cb3ef8 100644
--- a/docs/agents/triage-labels.md
+++ b/docs/agents/triage-labels.md
@@ -1,17 +1,19 @@
 # Triage Labels
 
-The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker: labels of the Linear team **SPI** (`docs/agents/issue-tracker.md`), with the ids Executor's Linear tools take (`labelId`, `labelIds`). The `linear` CLI takes the names.
 
-| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
-| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
-| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
-| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+| Label in mattpocock/skills | Label in our tracker | Linear label id                        | Meaning                                  |
+| -------------------------- | -------------------- | -------------------------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | `60b09003-73ce-4341-b886-9d152402cfb6` | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | `5faac0a3-c8be-42da-8dd5-f724c463dc7a` | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | `58973407-93c2-4c40-bad0-97e93b2a0610` | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | `84c02e07-a608-487b-9b73-4c47683d7565` | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | `617a55ae-8e6c-4b26-9688-e3c678454e9b` | Will not be actioned                     |
 
 When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
 
-Besides these, `cloudpid-report` marks an issue a cloudpid agent filed about cloudpid itself with the `cloudpid_report` tool (GLOSSARY.md → cloudpid report; ADR-0051). Such an issue is filed with `needs-triage` too, and triaged like any other: it is the agent's account, public, and may be wrong. Remove neither label to hide one; close it instead. The label must exist (`gh label create cloudpid-report`): while it is missing, cloudpid refuses every report.
+Besides these, `cloudpid-report` (`244a4f0c-c158-49a5-a7df-40a49c89d282`) marks an issue a cloudpid agent filed about cloudpid itself with the `cloudpid_report` tool (GLOSSARY.md → cloudpid report; ADR-0051). Such an issue is filed on GitHub with `needs-triage` too, synced into Linear, and triaged like any other: it is the agent's account, public, and may be wrong. Remove neither label to hide one; close it instead. The label must exist on GitHub (`gh label create cloudpid-report`): while it is missing, cloudpid refuses every report.
+
+The wayfinder labels are SPI's too: `wayfinder:map` `42d85e9b-40b2-40bf-9c45-e98799d23930`, `wayfinder:research` `e03d2ce5-67b9-4c99-923f-deaade4195be`, `wayfinder:prototype` `21dda5a9-ab19-4b9b-b429-df49aa2bb39e`, `wayfinder:grilling` `642c5812-78ae-4e1d-b15e-0c130b0ca861`, `wayfinder:task` `ebe3749e-2cee-4b3d-b0a4-9c514bd8a60c`.
 
 Edit the "Label in our tracker" column to match whatever vocabulary you actually use.
diff --git a/docs/development/infra.md b/docs/development/infra.md
index b2f4e415..fd258414 100644
--- a/docs/development/infra.md
+++ b/docs/development/infra.md
@@ -94,6 +94,8 @@ Every deploy, `alchemy dev` and a preview's destroy (which evaluates the stack)
   - **First deploy:** a new stage creates every Worker. After each Worker's script upload alchemy reads the script's deployments, and Cloudflare can answer that read with `WorkerNotFound` (10007) for a script it registered moments ago, for minutes at times (on #610, `Browsers` still at 93 s, found by 234 s). The read had no retry, so a new Worker's create could fail (`McpWorker` on #609, `Browsers` on #610), and `Server` and `PreviewComment`, which wait on it, failed with the same error; a rerun passed once Cloudflare caught up (#615). The alchemy patch retries that read for about five minutes ([`dependencies.md`](dependencies.md)). No binding cycle is involved: `Server` and `Workspaces` are pre-created for cycles of their own (`Server` with its Access application, `Workspaces` with its Container application), and the failing Workers bind only `Workspaces`, which is uploaded by then.
   - **Access applications:** the job's last step deletes any Access application whose destinations are all `public` ones on `cloudpid-server-pr-<number>.<subdomain>.workers.dev` (the host exactly, never another stage's), such as the bypass or hooks application a failed destroy left behind ([_Stages and Access_](#stages-and-access)). It runs even when the destroy or the Container check failed (those leave a bypass behind), lists the account's applications, deletes the matches, finds none on a rerun, and fails only if a list or a delete fails, not for a leftover it removed.
 
+**The `linear project` workflow** (`.github/workflows/linear-project.yml`) is separate from `ci.yml`. It runs for each new GitHub issue: Linear's GitHub Issues sync copies it into the Linear team SPI but into no project, and the workflow puts the copy into the project cloudpid (`scripts/linear-project.sh`; [`../agents/issue-tracker.md`](../agents/issue-tracker.md)). It reads the repository secret `LINEAR_API_KEY` (_CI credentials_ → `LINEAR_API_KEY`, below); dispatch it with an issue number to retry one.
+
 ### CI credentials
 
 They are code: `infra/github.ts` (stack `cloudpid-github`, stage `ci`) creates the scoped API token `cloudpid-ci-deploy` (Workers Scripts, Workers Containers, Secrets Store for alchemy's state store, Access apps and policies, and zone/DNS/routes on `ianpascoe.dev` and on `ianpascoe.app`: Zone Read, DNS Write and Workers Routes Write on each) and writes `CLOUDFLARE_API_TOKEN` (secret) and `CLOUDFLARE_ACCOUNT_ID`, `MODEL_PROXY_URL` (variables) into `production`. It also creates the `preview` environment and its token `cloudpid-ci-preview` (the same account permissions, no zone ones: nothing on `ianpascoe.dev`, because previews are served on `workers.dev`, and nothing on `ianpascoe.app`, because only `prod` deploys the App sandbox's Worker, route and record) with the same secret and variables, and one analytics token per environment (`cloudpid-container-analytics`, `cloudpid-container-analytics-preview`) written as `CLOUDPID_ANALYTICS_TOKEN`.
@@ -105,6 +107,7 @@ Any branch can use `preview`'s token, and Workers Scripts Write covers every Wor
 - **Access: Service Tokens Write** (`a1c0fec57cf94af79479a6d827fa518c`) is no longer in either token's permissions ([#636](https://github.com/ian-pascoe/cloudpid/issues/636) removed the Local agent's service token, the stack's only one). The tokens `ci:setup` made earlier keep it until `ci:setup` is rerun from the merged `main`; keep it until `prod`'s deploy of that change has deleted `cloudpid-local-agent` (deleting a service token needs it), then rerun. A change that declares an Access service token again must put the permission back first: "Apps and Policies Write" does not cover `POST /access/service_tokens` (`1010 auth.forbidden`), and a deploy that declares one fails without it, a pull request's preview and `prod` alike.
 - **Rotate the token:** `bun --cwd infra alchemy destroy --config github.ts --stage ci --profile admin`, then `ci:setup` again. The `production` and `preview` environments are retained on destroy, so the hand-set secrets and the `main` branch policy survive; only the token, its secret and the variables are replaced.
 - **Hand-set secrets:** the stack does not manage `MODEL_PROXY_API_KEY`, `SECRETS_ENCRYPTION_KEY`, the VAPID three, `EXA_API_KEY` or `PARALLEL_API_KEY`. Set each in both environments with `gh secret set <NAME> --env production` and `--env preview`, giving `preview` an encryption key and VAPID pair of its own (the dev ones from `~/.config/cloudpid/dev.env` will do), since the previews share them.
+- **`LINEAR_API_KEY`** is a repository secret, not an environment's, and deploys nothing: a Linear API key that may edit the team SPI's issues, for the `linear project` workflow (_CI_ above). Set it with `gh secret set LINEAR_API_KEY`; without it that workflow fails and nothing else changes.
 
 Workers Scripts Write also covers what rides on the script upload: observability (`WORKER_OBSERVABILITY`) and the Images binding need no extra permission.
 
diff --git a/scripts/linear-project.sh b/scripts/linear-project.sh
new file mode 100755
index 00000000..1fce84b0
--- /dev/null
+++ b/scripts/linear-project.sh
@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Puts the Linear issue that Linear's GitHub Issues sync created for a GitHub issue into the Linear project
+# LINEAR_PROJECT (docs/agents/issue-tracker.md): the sync copies GitHub issues into the team, but in no project. Waits
+# for the copy (the issue whose sync attachment, `sourceType` github, is the GitHub URL) up to WAIT_SECONDS, then sets
+# the project only when the issue has none, so a project someone already chose is kept. Retries Linear's errors, each
+# step up to WAIT_SECONDS, but a rejected key, which no retry fixes. Exits 0 when nothing is left to do (set, or kept), 1
+# otherwise.
+# Usage: LINEAR_API_KEY=… LINEAR_PROJECT=<project id> ISSUE_URL=https://github.com/<owner>/<repo>/issues/<n> \
+#   [WAIT_SECONDS=600] scripts/linear-project.sh
+set -euo pipefail
+
+key="${LINEAR_API_KEY:?LINEAR_API_KEY is required}"
+project="${LINEAR_PROJECT:?LINEAR_PROJECT is required}"
+url="${ISSUE_URL:?ISSUE_URL is required}"
+wait_seconds="${WAIT_SECONDS:-600}"
+deadline=$((SECONDS + wait_seconds))
+
+# Exit statuses of `graphql` and the steps built on it.
+readonly FAILED=1 KEY_REJECTED=2
+
+# One GraphQL request; `$1` is the document, `$2` its variables as JSON. Prints `.data`; fails with KEY_REJECTED when
+# Linear rejects the key, and with FAILED on any other error.
+graphql() {
+  local response http_code body
+  response="$(
+    jq -n --arg query "$1" --argjson variables "$2" '{query: $query, variables: $variables}' |
+      curl -sS --max-time 20 -w '\n%{http_code}' https://api.linear.app/graphql \
+        -H "Content-Type: application/json" \
+        -H "Authorization: $key" \
+        --data-binary @-
+  )" || return "$FAILED"
+  http_code="${response##*$'\n'}"
+  body="${response%$'\n'*}"
+  case "$http_code" in
+  401 | 403)
+    echo "Linear rejected LINEAR_API_KEY (HTTP $http_code)." >&2
+    return "$KEY_REJECTED"
+    ;;
+  2??) ;;
+  *)
+    echo "Linear answered HTTP $http_code." >&2
+    return "$FAILED"
+    ;;
+  esac
+  if jq -e '(.errors // []) | length > 0' <<<"$body" >/dev/null; then
+    echo "Linear refused the request: $(jq -c '.errors' <<<"$body")" >&2
+    return "$FAILED"
+  fi
+  jq -c '.data' <<<"$body"
+}
+
+# Runs `$@` until it succeeds; stops at once on KEY_REJECTED, and at the deadline with `$1`'s name in the message.
+until_deadline() {
+  local result
+  while true; do
+    result=0
+    "$@" || result=$?
+    if [ "$result" -eq 0 ]; then return 0; fi
+    if [ "$result" -eq "$KEY_REJECTED" ]; then exit 1; fi
+    if [ "$SECONDS" -ge "$deadline" ]; then
+      echo "$1 did not succeed within ${wait_seconds}s." >&2
+      exit 1
+    fi
+    sleep 15
+  done
+}
+
+# The synced copy of the GitHub issue, as `{id, identifier, project}` in $issue; fails while there is none yet.
+find_issue() {
+  # shellcheck disable=SC2016 # GraphQL variables, not shell ones.
+  issue="$(
+    graphql 'query($url: String!) { attachmentsForURL(url: $url) { nodes { sourceType issue { id identifier project { name } } } } }' \
+      "$(jq -n --arg url "$url" '{url: $url}')" |
+      jq -c '.attachmentsForURL.nodes | map(select(.sourceType == "github") | .issue) | first // empty'
+  )" || return
+  if [ -z "$issue" ]; then
+    echo "No synced Linear issue carries $url yet." >&2
+    return "$FAILED"
+  fi
+}
+
+set_project() {
+  local data
+  # shellcheck disable=SC2016 # GraphQL variables, not shell ones.
+  data="$(
+    graphql 'mutation($id: String!, $project: String!) { issueUpdate(id: $id, input: {projectId: $project}) { success } }' \
+      "$(jq -n --arg id "$(jq -r '.id' <<<"$issue")" --arg project "$project" '{id: $id, project: $project}')"
+  )" || return
+  if ! jq -e '.issueUpdate.success' <<<"$data" >/dev/null; then
+    echo "Linear did not move $(jq -r '.identifier' <<<"$issue") into the project." >&2
+    return "$FAILED"
+  fi
+}
+
+issue=""
+until_deadline find_issue
+
+identifier="$(jq -r '.identifier' <<<"$issue")"
+current="$(jq -r '.project.name // empty' <<<"$issue")"
+if [ -n "$current" ]; then
+  echo "$identifier is already in project $current; kept."
+  exit 0
+fi
+
+deadline=$((SECONDS + wait_seconds))
+until_deadline set_project
+echo "$identifier ($url) is now in project $project."