docs: document v0.3.0 — pagination, cycle scopes, --assignee, states, relations

Update README usage + comparison sizes (76 KB / ~2,100 lines), skill.md agent
reference (new filters + relations + states), and add the 0.3.0 CHANGELOG entry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: muqsitnawaz

CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-06-24
+
+Closes the load-bearing read gaps for agent workflows. The headline is
+pagination: lists no longer silently truncate at Linear's 50-issue page cap —
+on a real cycle this surfaced 137 tasks where the old code showed 50, the exact
+cause of "search before you create" missing existing tickets and filing
+duplicates.
+
+### Added
+- Full pagination on every issue list (`tasks`, `--query`, `--board`) — follows
+  `pageInfo` to the end instead of stopping at the first 50 results
+- `tasks --cycle all` (whole team: every cycle + backlog) and `--cycle none`
+  (backlog only) — previously listing was locked to the active/next cycle
+- `tasks --assignee me|none|<email>` — filter by real assignee, not just the
+  `agent:` label lane
+- `linear states` — list the team's workflow states, so agents stop guessing
+  status names and learning they were wrong only when a mutation fails
+- `update --blocks`, `--blocked-by`, `--relates` (repeatable) — create issue
+  relations via `issueRelationCreate`
+- Detail view (`tasks ANT-N`) now shows relations (Blocks / Blocked by / Related
+  to / Duplicate of), plus project, cycle, parent, url, estimate, and due date
+
+### Changed
+- `tasks --json` shape: `{ scope, cycle, count, issues }` (the `issues` array is
+  unchanged; `cycle` is null for `all`/`none` scopes)
+- Detail-view query enriched — `--json` no longer drops project/cycle/parent/
+  url/estimate/dueDate/relations
+
 ## [0.2.0] - 2026-06-07
 
 Broad expansion of the create/update surface to cover the fields agents actually

README.md

@@ -6,7 +6,7 @@
 [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
 [![Dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-dependencies-literally)
 [![Supply chain: 0 attack surface](https://img.shields.io/badge/supply%20chain-0%20attack%20surface-brightgreen.svg)](#zero-supply-chain-attack-surface)
-[![Single file](https://img.shields.io/badge/single%20file-67%20KB-brightgreen.svg)](./linear)
+[![Single file](https://img.shields.io/badge/single%20file-76%20KB-brightgreen.svg)](./linear)
 [![Team CLI](https://img.shields.io/badge/team-CLI-a3e635.svg)](#why-the-mcp-server-isnt-always-the-answer)
 
 Issue tracking from the shell — for humans and their agents. Query your queue, claim tasks, report progress, close with proof. Works the same whether you're typing or a subagent is.
@@ -57,6 +57,9 @@ linear tasks                         # your queue in the active cycle
 linear tasks --board                 # whole team board
 linear tasks ANT-42                   # detail view
 linear tasks --query "auth refresh"  # search title + description
+linear tasks --cycle all             # whole team: every cycle + backlog
+linear tasks --cycle none            # the backlog (issues in no cycle)
+linear tasks --assignee me           # by assignee: me | none | someone@x.com
 linear tasks --json | jq             # machine-readable
 
 linear update ANT-42 --pickup         # claim (In Progress)
@@ -65,6 +68,7 @@ linear update ANT-42 --done --proof https://pr/123 --proof "deployed"
 linear update ANT-42 --priority urgent --assign someone@x.com
 linear update ANT-42 --title "Renamed"  --description "Rewritten body"
 linear update ANT-42 --project "Foo" --milestone "v1.0"
+linear update ANT-42 --blocked-by ANT-7 --blocks ANT-9   # relations
 linear update ANT-42 --unlabel agent:claude --label agent:codex   # hand off
 
 linear create "Fix auth bug" --label security --priority high
@@ -77,18 +81,23 @@ linear projects                       # list projects + progress
 linear projects "Phoenix"             # detail view with milestones
 linear labels                         # available labels
 linear users                          # assignable users (for --assign lookup)
+linear states                         # the team's workflow states (valid --status values)
 linear cycles
 
 linear --team ENG tasks               # one-shot override (multi-team workspace)
 ```
 
+> Every list is fully paginated — no silent truncation at Linear's 50-issue
+> page cap, so `linear tasks` and `--query` see the *whole* cycle/team before
+> you create a duplicate.
+
 Full help: `linear <command> --help`.
 
 ## For humans and agents
 
 The same CLI works whether you're typing or a subagent is. Driving Linear from either shouldn't require shelling out to `@linear/sdk`, hand-rolling GraphQL, or parsing HTML.
 
-- **Assignee-as-queue.** `linear tasks` returns what *you* own, filtered to the active cycle. No dashboards, no saved views.
+- **Assignee-as-queue.** `linear tasks` returns what *you* own in the active cycle. Widen with `--cycle all` (whole team) or `--cycle none` (backlog), or filter by `--assignee me|none|<email>`. No dashboards, no saved views.
 - **Agent-lane labels.** Set `--agent claude` at setup and `linear tasks` filters to issues labeled for that agent. Multiple agents can share a team without stepping on each other.
 - **Proof-first completion.** `--done --proof <file|url|text>` uploads attachments, records links, and appends notes in one call — so reviewers see evidence without digging.
 - **JSON everywhere.** `--json` on every read command. Pipe to `jq` or hand to a subagent.
@@ -129,13 +138,13 @@ import subprocess
 import sys
 ```
 
-Every symbol is in the Python standard library. No `pip install`. No `npm install`. No `cargo build`. No Deno. The whole tool is one ~43 KB file you can read top-to-bottom in an hour.
+Every symbol is in the Python standard library. No `pip install`. No `npm install`. No `cargo build`. No Deno. The whole tool is one ~76 KB file you can read top-to-bottom in an hour.
 
 ### How it compares
 
 | Tool | Runtime | Deps | Install footprint | Last published |
 |------|---------|------|-------------------|----------------|
-| **linear-cli** (this) | Python 3.9+ stdlib | **0** | 67 KB, 1 file | active |
+| **linear-cli** (this) | Python 3.9+ stdlib | **0** | 76 KB, 1 file | active |
 | [`@linear/cli`](https://www.npmjs.com/package/@linear/cli) (official) | Node | 0 | 5 MB npm pkg | Nov 2021 (abandoned) |
 | [Linearis](https://github.com/czottmann/linearis) | Node | `@linear/sdk` + `commander` | 27 MB `node_modules` | 2025 |
 | [schpet/linear-cli](https://github.com/schpet/linear-cli) | Deno | 25+ imports (cliffy, graphql-codegen, unified, valibot…) | Deno + codegen | active |
@@ -152,7 +161,7 @@ This is the boring superpower of having no dependencies.
 
 Every notable CLI supply chain attack of the last few years — `event-stream`, `colors`/`faker`, `ua-parser-js`, `node-ipc`, the `xz` backdoor, `polyfill.io`, the dozens of [npm typosquats](https://socket.dev) caught monthly — happened through a compromised dependency, not the tool itself. linear-cli has none. The full audit surface is:
 
-- The ~1700 lines of Python in this repo (read it: [`linear`](./linear))
+- The ~2,100 lines of Python in this repo (read it: [`linear`](./linear))
 - Python's standard library
 - Linear's own GraphQL API at `api.linear.app`
 
@@ -181,7 +190,7 @@ If you want the MCP, use it. If you want a subagent to burn through 50 tickets w
 
 Yes. If your agent has its own Linear account (many teams provision one seat per agent — e.g. `claude@yourcompany.com`, `codex@yourcompany.com`), run `linear setup --api-key <agent's own key>` without `--agent`. Then `linear tasks` returns tickets assigned *directly to the agent's user*. No labels, no filtering — the assignee IS the lane.
 
-Use `--agent <label>` when you want multiple agents to share one Linear seat; skip it when each agent has its own.
+Use `--agent <label>` when you want multiple agents to share one Linear seat; skip it when each agent has its own. To query any assignee on demand, `linear tasks --assignee me|none|<email>`.
 
 ### How do I rotate the API key?
 

skill.md

@@ -21,19 +21,28 @@ linear cycles                         # list cycles
 linear projects                       # list projects (with milestones via `linear projects "Name"`)
 linear labels                         # list available labels
 linear users                          # list assignable users
+linear states                         # the team's workflow states (valid --status values)
 ```
 
 ## Filters
 
+Lists are fully paginated — `linear tasks` returns the *whole* cycle/team, not a
+truncated first page. Always search before creating, to avoid duplicates.
+
 ```
 linear tasks --status todo         # backlog | todo | progress | done | open
 linear tasks --label security      # by any label
-linear tasks --cycle next          # active | next
+linear tasks --cycle active        # active (default) | next | all | none
+linear tasks --cycle all           # whole team: every cycle + backlog
+linear tasks --cycle none          # backlog only (issues in no cycle)
+linear tasks --assignee me         # by assignee: me | none | someone@x.com
 linear tasks --query "auth"        # search title + description
 linear tasks --json                # machine-readable
 linear tasks --all                 # ignore default agent filter
 ```
 
+If unsure of a status name, run `linear states` instead of guessing.
+
 ## Editing existing issues
 
 Everything you can set on `create` can be changed on `update` with the same flag. Examples:
@@ -43,10 +52,16 @@ linear update ANT-42 --priority urgent --assign someone@x.com
 linear update ANT-42 --title "Renamed" --description "Rewritten body"
 linear update ANT-42 --project "Phoenix" --milestone "v1.0"
 linear update ANT-42 --estimate 3 --parent ANT-10
+linear update ANT-42 --blocked-by ANT-7 --blocks ANT-9            # relations
+linear update ANT-42 --relates ANT-5                              # non-blocking link
 linear update ANT-42 --label agent:codex --unlabel agent:claude   # hand off
 linear update ANT-42 --project none                               # detach
 ```
 
+Relations are read back in the detail view (`linear tasks ANT-42`) as
+Blocks / Blocked by / Related to. Use `--blocked-by` before picking up a task to
+record what it depends on.
+
 ## Creating issues — what's required
 
 Only one thing: a title OR a description. Everything else has a sensible default.
@@ -87,6 +102,7 @@ linear tasks --json | jq '.issues[] | {id: .identifier, title, state: .state.nam
 
 - `linear tasks` without flags returns issues assigned to the identity that owns the API key.
 - If `cfg.agent` is set at setup time (e.g. `claude`, `codex`), `linear tasks` additionally filters by a matching label — the "agent lane" pattern. Override with `--all`.
+- Default scope is the active cycle. Use `--cycle all` to search the whole team (e.g. before creating, to avoid duplicates), `--cycle none` for the backlog, or `--assignee <email>` to query someone else's queue.
 - `linear update <id> --pickup` = claim the task. Follow with `--done --proof` when shipped.
 
 ## Proof-of-completion