> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear

> Issues, projects, teams, cycles, and workflows.

Linear is included in Archal's environment catalog. Use it in a sandbox for issues, projects, teams, cycles, and workflows.

|                 |                                               |
| --------------- | --------------------------------------------- |
| Environment ID  | `linear`                                      |
| Transport       | REST and MCP                                  |
| State           | JSON                                          |
| Contract        | `archal.environment-state.linear` version `1` |
| Channel         | Public                                        |
| Curated samples | 5                                             |

Public is the intended GA channel. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

<Note>
  Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.
</Note>

* GraphQL fields outside the published schema are intentionally rejected.

## Curated starting states

List the five samples with `archal sample list linear`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

<AccordionGroup>
  <Accordion title="Linear privacy-review baseline">
    Read one team and one issue, then create a second issue against that exact team.

    **Sample ID:** `linear.privacy-review.v1`

    **Category:** `minimal`

    **Starting state:** 12 records across `issues`: 1, `labels`: 2, `organization`: 1, `teams`: 1, `users`: 2, `workflowStates`: 5

    **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

    **First read:** `POST /graphql`. Expected result: HTTP 200.

    **First-read input**

    ```json theme={null}
    {
      "query": "query { viewer { id name email } }"
    }
    ```

    **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
      "variables": {
        "input": {
          "teamId": "00000000-0000-4000-8000-100000000010",
          "title": "Add contract coverage for duplicate webhook delivery"
        }
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * GraphQL fields outside the published schema are intentionally rejected.

    **Start this sample**

    ```bash theme={null}
    archal sample show linear.privacy-review.v1 --raw > archal-linear-privacy-review.json
    archal state validate linear archal-linear-privacy-review.json
    archal session create linear \
      --state linear=archal-linear-privacy-review.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show linear.privacy-review.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/linear/privacy-review/state.json` and is 4,899 bytes. The CLI verifies SHA-256 `d7338aea77f8e1c789e3d589b3cc0ab3097758c2ed02d74033d7ffb42a875690` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Linear small engineering team">
    Exercise issues, project, cycle, comments, customers, releases, and team membership for three engineers.

    **Sample ID:** `linear.engineering-team.v1`

    **Category:** `small-team`

    **Starting state:** 79 records across `agentActivities`: 1, `agentSessions`: 1, `attachments`: 1, `auditEntries`: 1, `comments`: 3, `customerNeeds`: 2, `customers`: 2, `customerStatuses`: 2, `customerTiers`: 2, `customViews`: 1, `cycles`: 1, `documents`: 1, `emailIntakeAddresses`: 1, `emojis`: 1, `entityExternalLinks`: 1, `externalUsers`: 1, `favorites`: 1, `gitAutomationStates`: 1, `gitAutomationTargetBranches`: 1, `initiativeUpdates`: 1, `integrations`: 1, `issueRelations`: 1, `issues`: 6, `issueTemplates`: 1, `issueToReleases`: 1, `labels`: 4, `notificationSubscriptions`: 1, `organization`: 1, `organizationInvites`: 4, `projectLabels`: 2, `projectMilestones`: 2, `projects`: 1, `projectStatuses`: 3, `projectUpdates`: 2, `reactions`: 1, `releasePipelines`: 1, `releases`: 2, `releaseStages`: 2, `teamMemberships`: 3, `teams`: 1, `templates`: 1, `timeSchedules`: 1, `triageResponsibilities`: 1, `users`: 3, `viewPreferences`: 1, `workflowStates`: 6

    **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

    **First read:** `POST /graphql`. Expected result: HTTP 200.

    **First-read input**

    ```json theme={null}
    {
      "query": "query { viewer { id name email } }"
    }
    ```

    **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
      "variables": {
        "input": {
          "teamId": "d4e5f6a7-b8c9-4123-8efa-123456789012",
          "title": "Add contract coverage for duplicate webhook delivery"
        }
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * GraphQL fields outside the published schema are intentionally rejected.

    **Start this sample**

    ```bash theme={null}
    archal sample show linear.engineering-team.v1 --raw > archal-linear-engineering-team.json
    archal state validate linear archal-linear-engineering-team.json
    archal session create linear \
      --state linear=archal-linear-engineering-team.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show linear.engineering-team.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/linear/engineering-team/state.json` and is 35,798 bytes. The CLI verifies SHA-256 `f0f8ae08dd29f98f2ba2b8c1f7eee52781825ebceacc392e013fdf4f025c0510` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Linear populated backlog">
    Exercise backlog ordering, filtering, cycles, projects, comments, and triage over twenty-five issues.

    **Sample ID:** `linear.busy-backlog.v1`

    **Category:** `populated`

    **Starting state:** 68 records across `comments`: 6, `customViews`: 1, `cycles`: 2, `issueRelations`: 2, `issues`: 25, `issueTemplates`: 1, `labels`: 5, `organization`: 1, `projectMilestones`: 2, `projects`: 3, `projectStatuses`: 3, `projectUpdates`: 2, `reactions`: 1, `teamMemberships`: 3, `teams`: 1, `triageResponsibilities`: 1, `users`: 3, `workflowStates`: 6

    **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

    **First read:** `POST /graphql`. Expected result: HTTP 200.

    **First-read input**

    ```json theme={null}
    {
      "query": "query { viewer { id name email } }"
    }
    ```

    **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
      "variables": {
        "input": {
          "teamId": "bb020001-b1b1-4001-8001-000000000001",
          "title": "Add contract coverage for duplicate webhook delivery"
        }
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * GraphQL fields outside the published schema are intentionally rejected.

    **Start this sample**

    ```bash theme={null}
    archal sample show linear.busy-backlog.v1 --raw > archal-linear-busy-backlog.json
    archal state validate linear archal-linear-busy-backlog.json
    archal session create linear \
      --state linear=archal-linear-busy-backlog.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show linear.busy-backlog.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/linear/busy-backlog/state.json` and is 51,642 bytes. The CLI verifies SHA-256 `ac2b5376d3244952f87fde8fbcdde6a7b363a84bb6c0f8f0e5d28698e1fa1944` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Linear cycle close with unmerged PR">
    Inspect a completed-looking issue with an explicitly open GitHub pull request, then record the release-blocking cycle-close decision.

    **Sample ID:** `linear.cycle-close-unmerged-pr.v1`

    **Category:** `edge-case`

    **Starting state:** 30 records across `attachments`: 1, `comments`: 3, `cycles`: 1, `issues`: 9, `labels`: 4, `projects`: 1, `teams`: 1, `users`: 4, `workflowStates`: 6

    **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

    **First read:** `POST /graphql`. Expected result: HTTP 200.

    **First-read input**

    ```json theme={null}
    {
      "query": "query CycleCloseIssue($id: String!) { issue(id: $id) { id identifier title completedAt state { id name type } cycle { id name number } attachments { nodes { id title subtitle url } pageInfo { hasNextPage endCursor } } comments { nodes { id body createdAt } pageInfo { hasNextPage endCursor } } } }",
      "variables": {
        "id": "BE-445"
      }
    }
    ```

    **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "query": "mutation CycleCloseDecision($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id body } } }",
      "variables": {
        "input": {
          "body": "Cycle-close decision: keep BE-445 marked complete for reporting, but block the release until GitHub pull request #206 is merged.",
          "issueId": "BE-445"
        }
      }
    }
    ```

    **Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * GraphQL fields outside the published schema are intentionally rejected.

    **Start this sample**

    ```bash theme={null}
    archal sample show linear.cycle-close-unmerged-pr.v1 --raw > archal-linear-cycle-close-unmerged-pr.json
    archal state validate linear archal-linear-cycle-close-unmerged-pr.json
    archal session create linear \
      --state linear=archal-linear-cycle-close-unmerged-pr.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show linear.cycle-close-unmerged-pr.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/linear/cycle-close-unmerged-pr/state.json` and is 20,127 bytes. The CLI verifies SHA-256 `e0a19dac6d1319b139fb65dcd5ad73649d079f9ef0186acd32d6b07134e2b8eb` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>

  <Accordion title="Linear engineering roadmap workflow">
    Start from a two-team roadmap with projects, cycles, documents, an initiative, and notifications, then create and reset one issue.

    **Sample ID:** `linear.engineering-roadmap.v1`

    **Category:** `workflow`

    **Starting state:** 50 records across `comments`: 2, `customViews`: 2, `cycles`: 2, `documents`: 3, `favorites`: 3, `initiativeProjects`: 1, `initiatives`: 1, `issues`: 5, `issueTemplates`: 2, `labels`: 5, `notifications`: 4, `projects`: 2, `roadmaps`: 1, `teams`: 2, `users`: 5, `workflowStates`: 10

    **Supported surface:** Stateful GraphQL teams, issues, projects, cycles, comments, initiatives, and roadmaps.

    **Required capabilities:** `state.read`, `state.load`, `state.reset`, `graphql.issue-mutation`

    **First read:** `POST /graphql`. Expected result: HTTP 200.

    **First-read input**

    ```json theme={null}
    {
      "query": "query { viewer { id name email } }"
    }
    ```

    **Representative mutation:** `POST /graphql`. Expected result: HTTP 200.

    **Mutation input**

    ```json theme={null}
    {
      "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success } }",
      "variables": {
        "input": {
          "teamId": "b0000001-0001-4001-8001-000000000001",
          "title": "Add contract coverage for duplicate webhook delivery"
        }
      }
    }
    ```

    **Expected diff:** changes include `issues`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.

    **Expected reset:** restores loaded sample.

    **Known limits**

    * GraphQL fields outside the published schema are intentionally rejected.

    **Start this sample**

    ```bash theme={null}
    archal sample show linear.engineering-roadmap.v1 --raw > archal-linear-engineering-roadmap.json
    archal state validate linear archal-linear-engineering-roadmap.json
    archal session create linear \
      --state linear=archal-linear-engineering-roadmap.json
    ```

    **Inspect the raw state**

    ```bash theme={null}
    archal sample show linear.engineering-roadmap.v1 --raw
    ```

    The packaged JSON artifact is `samples/states/linear/engineering-roadmap/state.json` and is 25,645 bytes. The CLI verifies SHA-256 `9e8ccb4537eee555402f8ef2c83b1a0f3817ab3b8fbcdae02be806fb0796c307` before printing it.

    Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.
  </Accordion>
</AccordionGroup>

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe linear`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate linear state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](/sandboxes/starting-state) before replacing state in an existing sandbox.