i-plane 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/AGENTS.md +134 -74
  2. package/README.md +53 -240
  3. package/dist/cli.js +65 -64
  4. package/docs/api-coverage.md +78 -0
  5. package/package.json +20 -6
package/AGENTS.md CHANGED
@@ -1,94 +1,154 @@
1
1
  # Working on this repository
2
2
 
3
- Read this before changing anything here. It is not documentation of what the tool
4
- does — that is `README.md` — it is what breaks when the rules below are ignored.
3
+ Read this before changing the CLI. README.md is the short package introduction;
4
+ `i-plane guide` and command help explain usage. `docs/api-coverage.md` records the
5
+ supported API surface, compatibility details and development checks.
5
6
 
6
- ## What this is
7
+ ## Purpose
7
8
 
8
- A CLI for [Plane](https://plane.so) whose caller is a coding agent, not a person
9
- at a terminal. Plane's REST answer for seven work items is ~6,500 tokens of JSON;
10
- this prints ~145 tokens of lines. Every rule below follows from that one fact.
11
-
12
- ## Authorship
13
-
14
- Written by Claude (Anthropic) with the repository owner. The owner decides what
15
- gets built and what ships; the model writes the code, runs the checks, and
16
- reports what it finds — including when the finding is its own bug.
9
+ A Plane CLI for coding agents and automation. Compact, predictable output is a
10
+ product requirement: callers should not need large REST responses or an
11
+ interactive terminal to understand and update their work.
17
12
 
18
13
  ## Invariants
19
14
 
20
- Breaking one of these is a bug even when tests pass.
21
-
22
- **Nothing prompts, ever.** A CLI that waits for input hangs an agent forever. A
23
- missing argument is a `UsageError` naming what was expected; `src/commands/guide.ts`
24
- turns it into a hint with that command's real examples.
25
-
26
- **Exit codes are a contract.** `2` the call was wrong, `1` Plane refused or was
27
- unreachable. Callers branch on the code instead of parsing text, so a
28
- misclassified error is worse than a vague message.
29
-
30
- **`--json` is never optional.** Commands build a model and hand it to a formatter;
31
- `printValue` in `src/output.ts` decides between them. Print directly and you have
32
- silently dropped `--json` for that command.
33
-
34
- **`src/registry.ts` is the single source for commands.** It feeds the guide, every
35
- `<command> --help`, and the hint on a failed call — and it is what rejects unknown
36
- flags. Add a flag to a command without adding it there and the CLI will refuse it.
37
-
38
- **Never trust a server-side filter.** The list endpoint honours `fields` and
39
- `expand` (11 KB → 737 bytes on the wire) but accepts `state_group`, `priority` and
40
- `order_by` with a 200 and ignores them. Narrowing happens in `src/commands/issues.ts`.
41
-
42
- **Never let the token reach text.** `redact` in `src/client.ts` guards every error
43
- path; `maskToken` guards `config`. Node puts an offending header value into its
44
- own error message, and a server can echo a key back in an error body.
45
-
46
- **Pin versions exactly.** A range once meant the tree tested here and the tree a
47
- user installs were different — undici, `^7.16.0` against 8.10.2 installed.
48
-
49
- ## Ground already lost once
50
-
51
- Twenty-one findings came out of one review. These are the ones worth remembering:
52
-
53
- | What happened | Why |
54
- |---|---|
55
- | ` ```c++ ` hung the process forever | a fence pattern that refused a line without consuming it |
56
- | `--yes=false` deleted a work item | a switch tested for presence, not value |
57
- | a misspelled `--priority` returned an unfiltered list, exit 0 | no flag validation |
58
- | the API token appeared in an error message | masking guarded one command, not the error paths |
59
- | a description lost `<div>` inside inline code | entity decoding followed by tag stripping |
60
-
61
- The Markdown conversion was hand-written and lost five ways at once. It now uses
62
- `markdown-it` and `turndown`. `markdown-it` rather than `marked` for one reason:
63
- with `html:false` it escapes raw HTML instead of passing `<img src=x onerror=…>`
64
- into other people's browsers.
15
+ **Nothing prompts.** Missing arguments and invalid values raise `UsageError`
16
+ with an actionable hint. Never wait for interactive input.
17
+
18
+ **Exit codes are a contract.** Use `2` for an invalid call and `1` for an API or
19
+ connection failure. Do not classify a transport failure as invalid user input.
20
+
21
+ **Every command supports JSON.** Build an output model and pass it through
22
+ `printValue` in `src/output.ts`. Text and JSON must describe the same result.
23
+ Guide/help models include global options and usage notes as well as commands.
24
+
25
+ **The registry owns the CLI contract.** `src/registry.ts` declares command names,
26
+ aliases, arguments, options, required markers, examples, usage notes and next
27
+ steps. The parser derives value flags from it. Online handlers live in
28
+ `src/dispatch.ts`; the registry and handler table must agree in both directions.
29
+ Required markers document the contract; handlers still validate the arguments.
30
+
31
+ **Help is part of the implementation.** A new command needs a purpose, supported
32
+ fields, requirements, realistic examples and follow-up calls. Keep summaries
33
+ short; put decisions and limitations in usage notes. All example flags must be
34
+ accepted by that command. Do not advertise API/UI fields that the CLI cannot set.
35
+ Keep README concise and point readers to `guide` and `--help` for workflows.
36
+
37
+ **Never trust a server-side filter without checking it.** Use `fields`, `expand`
38
+ and pagination to limit wire size while collecting all pages. The work item
39
+ endpoint can accept state, priority and ordering filters without applying them;
40
+ those filters are handled in the client. Check behavior, not only HTTP status.
41
+
42
+ **Never let a token escape.** Register `guardSecret` before diagnostics. All
43
+ output goes through the guards in `src/output.ts`; client errors are redacted,
44
+ and config output uses `maskToken`. Redact before truncating or formatting.
45
+ A server response or a native error can echo credentials back.
46
+
47
+ **A successful write stays successful.** Resolve and validate inputs before
48
+ writing. Do not report a successful mutation as failed because an optional
49
+ follow-up read or setup step failed. Return the created identifier and a clear
50
+ warning with a recovery command. Do not automatically retry uncertain writes.
51
+
52
+ **Markdown has a defined scope.** Work item and intake descriptions, and comment
53
+ bodies, use Markdown converted at the API boundary. Project, label, state, cycle
54
+ and module descriptions are plain text. Keep the established `markdown-it` and
55
+ `turndown` conversion; raw HTML must remain escaped in Markdown input.
56
+
57
+ **Runtime and dependency claims must agree.** Support Node 22.21+ on the 22.x
58
+ line or Node 24+. Keep README and `package.json` engines consistent. Undici 8.x
59
+ requires Node 22.19+; the native proxy fallback requires Node 22.21 or Node 24.
60
+ Pin dependencies exactly and keep optional `undici` external to the bundle.
61
+ Do not infer minimum-version compatibility from a build on a newer runtime.
62
+
63
+ ## API behavior that must survive changes
64
+
65
+ - Project names reject special characters, including hyphens. Validate before
66
+ the creation request. API routes and defaults must be checked on the target
67
+ server; newer UI documentation can describe different behavior.
68
+ - `--label` merges with existing labels; `--labels` replaces them. Plane replaces
69
+ the whole labels array. Read-modify-write can still race with another editor.
70
+ - Resolve readable work item references and names before writes. Reject ambiguous
71
+ matches, and validate project membership for bulk cycle/module assignment.
72
+ - `project create --intake` must initialize the queue with a project PATCH.
73
+ Setting the creation flag alone can leave a missing queue and cause HTTP 500.
74
+ - Cycle updates preserve the existing owner when `--owner` is absent. Some
75
+ servers otherwise default ownership to the requesting user.
76
+ - Cycle dates must be supplied or cleared together, including `none`. Format
77
+ their timestamps in the project timezone; retain raw timestamps in JSON.
78
+ - A work item has one cycle but can belong to several modules. Cycle transfer
79
+ moves unfinished work and leaves completed/cancelled work in the source.
80
+ - Expired snoozes may disappear from intake GET and normal triage lookup.
81
+ Intake update/delete by work item UUID must not require a preliminary GET.
82
+ If a readable reference cannot resolve, explain how to use saved `issueId`.
83
+ - Intake status is separate from work item state. Acceptance moves triage work
84
+ to the project default state on the supported API path. Removing an accepted
85
+ intake entry keeps the work item; removing an unaccepted entry deletes it too.
86
+
87
+ Regression history also includes infinite Markdown fence parsing, lost inline
88
+ HTML inside code, ignored unknown flags, and `--yes=false` confirming deletion.
89
+ Preserve coverage for these cases when refactoring.
65
90
 
66
91
  ## Checks
67
92
 
68
93
  ```bash
69
- bun test # every case is a bug that shipped once
70
- ./node_modules/.bin/tsc --noEmit # src and types; tests are checked by bun
94
+ bun test
95
+ ./node_modules/.bin/tsc --noEmit
71
96
  ./node_modules/.bin/biome check .
72
- node scripts/release.mjs # the full gate, without publishing
97
+ node scripts/release.mjs
73
98
  ```
74
99
 
75
- Tests are deliberately not in `tsc`'s `include`: pulling `bun-types` in collides
76
- with `@types/node` inside the library's own declarations, and a type error in
77
- someone else's file says nothing about this code.
100
+ Tests cover regressions, registry/handler agreement, executable help examples,
101
+ request payloads, output and errors. A test that only accepts any exception or
102
+ checks that a function was called does not establish correct behavior.
103
+
104
+ TypeScript checks `src` and `types`; tests run under Bun. Do not add `bun-types`
105
+ to the project's TypeScript compilation just to include tests: its declarations
106
+ can conflict with `@types/node`. Exercise the built Node entry point too.
78
107
 
79
- ## Testing against a live instance
108
+ ## Live checks
80
109
 
81
- Credentials are at `~/.config/plane/credentials` and the CLI reads them itself, so
82
- `node dist/cli.js list CLOUD` works with no arguments. Delete anything you create:
110
+ The CLI reads `~/.config/plane/credentials` itself. Keep secrets out of command
111
+ arguments and logs where possible. Use the local build when checking new code:
83
112
 
84
113
  ```bash
85
- node dist/cli.js delete CLOUD-42 --yes
114
+ bun run build
115
+ node dist/cli.js list CLOUD
86
116
  ```
87
117
 
88
- ## Releasing
89
-
90
- Publishing is irreversible — a version cannot be reused, and a tarball that
91
- shipped too much stays in every mirror. `node scripts/release.mjs` does
92
- everything except publish; `--publish` is the only path to `npm publish`. The gate
93
- empties `dist`, runs the checks, smoke-tests the built command, enforces package
94
- contents and size, and refuses when the registry cannot be reached.
118
+ Prefer a short, targeted scenario for the behavior changed. Use a temporary
119
+ project for writes and remove it afterwards. Do not change working project data
120
+ as test fixtures. Preserve a created project's identifier if cleanup fails.
121
+
122
+ The full scripts `scripts/acceptance.mjs --live` and
123
+ `scripts/planning-acceptance.mjs --live` use real CLI commands and clean up their
124
+ projects in `finally`. They take several minutes because they space requests.
125
+ Do not repeat both scripts for a documentation edit or a narrow fix that can be
126
+ verified with a focused check. Respect the API request budget and use bounded,
127
+ observable waits. A forced termination can interrupt cleanup.
128
+
129
+ `EPERM`/`EACCES` before an HTTP response indicates an operating-system permission
130
+ failure. Check the selected proxy route and sandbox network access before
131
+ changing credentials or application code. An installed CLI can also differ from
132
+ the local build: check its version before diagnosing missing commands.
133
+
134
+ ## Releases and tracking
135
+
136
+ Keep `package.json` and `src/cli.ts` versions in sync. The release gate empties
137
+ `dist`, runs checks, builds, smoke-tests the command, validates the exact package
138
+ contents and size, and checks registry availability. Changes to shipped files
139
+ must update both `package.json` files and the gate's allowlist.
140
+
141
+ Publishing is irreversible. `node scripts/release.mjs` does not publish;
142
+ `--publish` is the publishing path. Obtain authorization for publication and
143
+ reuse it within the authorized release rather than asking repeatedly.
144
+
145
+ A successful npm upload can return HTTP 202 while registry processing continues.
146
+ Do not republish the same version or treat a transient post-upload 404 as a
147
+ failed upload. Distinguish submission from public availability, use short bounded
148
+ checks, and verify the published version and `latest` tag before claiming both
149
+ are available.
150
+
151
+ Keep project task statuses aligned with the work. Move a task into progress when
152
+ starting, close it after its checks, and reopen it when a confirmed review finding
153
+ invalidates completion. Report whether a change is local, installed or published;
154
+ these are separate states. Keep commits and public metadata provider-agnostic.
package/README.md CHANGED
@@ -1,272 +1,85 @@
1
1
  # i-plane
2
2
 
3
- A command-line client for [Plane](https://plane.so) that prints lines instead of
4
- JSON dumps.
3
+ **Plane project management from the command line.**
5
4
 
6
- Ask Plane's API for seven work items and it answers with twenty-nine fields
7
- each — about 6,500 tokens. The same seven through `i-plane` are 145. If you are
8
- piping work items into a coding agent, that difference is the entire point.
5
+ Find the next task, read the discussion, update the work and keep moving.
6
+ `i-plane` brings your [Plane](https://plane.so) workspace into the terminal,
7
+ with compact output for coding agents and scripts.
9
8
 
10
- ```
11
- $ i-plane list CLOUD --state started
12
- CLOUD-4 Create and assign work items [high] (In Progress)
13
- CLOUD-5 Visualize your work (In Progress)
9
+ ```console
10
+ $ i-plane list APP --state started
11
+ APP-9 Fix search indexing [urgent] (In Progress)
12
+ APP-8 Refresh the onboarding guide [high] (In Progress)
14
13
  ```
15
14
 
16
- ## Install
15
+ Readable references like `APP-8`, Markdown for work item descriptions and
16
+ comments, and `--json` whenever you need structured data. Nothing prompts for input.
17
17
 
18
- ```bash
19
- npm install -g i-plane
20
- ```
18
+ ## What you can do
21
19
 
22
- Node 20 or newer.
20
+ - **Manage tasks:** search, create, update and complete work; set parents,
21
+ assignees, labels and dates; read and write comments.
22
+ - **Set up projects:** create projects, configure workflow states and labels,
23
+ enable planning features, and archive finished projects.
24
+ - **Plan delivery:** schedule work in cycles, carry unfinished tasks forward,
25
+ and group related work in modules that can span multiple cycles.
26
+ - **Triage requests:** collect reports in intake, then accept, reject, snooze
27
+ or mark them as duplicates before committing to the work.
28
+ - **Automate:** use concise lists, JSON output and distinct exit codes in
29
+ agent workflows and shell scripts.
23
30
 
24
- ## Set it up
31
+ ## Install and connect
25
32
 
26
- You need three things: the address of your Plane, an API key, and a workspace.
27
- The key comes from **Workspace settings → API tokens**.
28
-
29
- Supply them however suits you — flags win over environment, environment wins over
30
- the file:
33
+ Requires **Node 22.21+ on the 22.x line, or Node 24+**.
31
34
 
32
35
  ```bash
33
- # once, in a file
34
- mkdir -p ~/.config/plane && chmod 700 ~/.config/plane
35
- cat > ~/.config/plane/credentials <<'EOF'
36
- PLANE_URL=https://plane.example.com
37
- PLANE_API_KEY=plane_api_…
38
- PLANE_WORKSPACE=my-workspace
39
- EOF
40
- chmod 600 ~/.config/plane/credentials
41
-
42
- # or per call
43
- i-plane list CLOUD --url https://plane.example.com --token … --workspace my-workspace
44
- ```
45
-
46
- Not sure what is in effect:
47
-
48
- ```
49
- $ i-plane config
50
- url https://plane.example.com (file)
51
- workspace my-workspace (env)
52
- token plane_…856f (file)
53
- file /home/you/.config/plane/credentials
54
- ```
55
-
56
- ## Use it
57
-
58
- Run `i-plane` with no arguments and it shows the command map, the usual order of
59
- work, and how it behaves. `i-plane <command> --help` gives one command's flags
60
- and real examples.
61
-
62
- ```
63
- summary projects and how much is in each
64
- list [project] work items, one line each --state --priority --limit
65
- show <ID> one work item, description included
66
- search <text> across the whole workspace
67
- create <title> --project --priority --state --description --label --parent --assignee --due --start
68
- update <ID> --state --priority --name --description --label --labels --parent --assignee --due --start
69
- done <ID> move to the first completed state
70
- comment <ID> <text> add a comment
71
- comments <ID> read comments; show <ID> --comments includes them too
72
- delete <ID> --yes delete; refuses without --yes
73
- project create|update|archive|rm
74
- label create|rm --project
75
- state create|update|rm --project
76
- cycles cycle create|update|add|issues|transfer
77
- modules module create|add|issues
78
- intake list|create|show|update|rm
79
- projects states labels members whoami config guide
80
- ```
81
-
82
- Short forms for what fingers type: `ls`, `new`, `set`, `rm`, `find`.
83
-
84
- Work items go by the name people say — `CLOUD-8`. Projects take an identifier
85
- (`CLOUD`), a full name, or a unique prefix of one.
86
-
87
- Every command accepts `--json` and then prints the whole model, for when you need
88
- ids and timestamps rather than a readable line.
89
-
90
- ## Set up a project
91
-
92
- ```bash
93
- i-plane project create "Knowledge Base" --identifier KB --description "Team notes"
94
- i-plane label create epic --project KB --color '#8ED1FC'
95
- i-plane label create task --project KB --color '#3B82F6'
96
- i-plane create "Build the knowledge base" --project KB --label epic --priority high
97
- # Use the identifier returned by create as the parent of each child:
98
- i-plane create "Define the structure" --project KB --parent KB-1 --label task --priority urgent
99
- i-plane update KB-2 --assignee "Reader" --start 2026-10-01 --due 2026-10-08
100
- i-plane state create Review --project KB --group started --color '#336699'
101
- i-plane update KB-2 --state Review
102
- i-plane comments KB-2
103
- i-plane show KB-2 --comments
36
+ npm install -g i-plane
104
37
  ```
105
38
 
106
- `project update` changes the name, identifier or description. Project names cannot
107
- contain special characters, including hyphens; the CLI checks before sending a
108
- request. Identifiers contain 1–12 letters or digits, start with a letter, and are
109
- normalized to uppercase. `project archive` hides a project from active lists.
110
- `project rm <project> --yes` permanently deletes it and its contents.
111
-
112
- `--label task,review` adds labels and preserves the current ones. `--labels task`
113
- replaces the entire list; `--labels none` clears it. Both flags accept names, unique
114
- name prefixes or IDs and cannot be combined. Repeating a flag keeps its last
115
- value, so use one comma-separated list for multiple labels. Addition reads the
116
- current labels before writing the merged list; concurrent label edits can still
117
- race because the API replaces the array.
39
+ Create a [Plane API token](https://developers.plane.so/api-reference/introduction#authentication)
40
+ and save these settings in `~/.config/plane/credentials`:
118
41
 
119
- `--parent` accepts a readable work item identifier, or a UUID in the same project.
120
- `--assignee` replaces the list with comma-separated display names, emails or UUIDs.
121
- Ambiguous names fail instead of selecting a match. `--parent none`, `--assignee none`,
122
- `--due none` and `--start none` clear their fields. Dates use `YYYY-MM-DD`.
123
-
124
- `label rm <label> --project KB --yes` removes a label. `state update` changes a
125
- state's name, color, group or description; `state rm` requires `--yes`. State and
126
- label names accept an exact match, unique prefix or ID. Descriptions of projects,
127
- labels and states are plain text; work item descriptions and comments are Markdown.
128
-
129
- ## Plan work and triage incoming requests
130
-
131
- ```bash
132
- i-plane project update KB --cycles --modules --intake
133
- i-plane cycle create "Sprint 1" --project KB --start 2026-10-01 --end 2026-10-14
134
- i-plane cycle create "Sprint 2" --project KB --start 2026-10-15 --end 2026-10-28
135
- i-plane cycles KB
136
- i-plane cycle add KB-2 KB-3 --project KB --cycle "Sprint 1"
137
- i-plane cycle issues "Sprint 1" --project KB
138
- # After Sprint 1 has ended:
139
- i-plane cycle transfer "Sprint 1" "Sprint 2" --project KB
140
-
141
- i-plane module create Documentation --project KB --status planned
142
- i-plane modules KB
143
- i-plane module add KB-2 KB-3 --project KB --module Documentation
144
- i-plane module issues Documentation --project KB
145
-
146
- i-plane intake create "Investigate a reported problem" --project KB --priority high
147
- i-plane intake list KB --status pending
148
- # Use the work item reference returned by intake create:
149
- i-plane intake show KB-4 --project KB
150
- i-plane intake update KB-4 --project KB --status accepted
42
+ ```ini
43
+ PLANE_URL=https://plane.example.com
44
+ PLANE_API_KEY=your-api-token
45
+ PLANE_WORKSPACE=your-workspace-slug
151
46
  ```
152
47
 
153
- A cycle groups work by time; a module groups related work independently of sprint
154
- dates. Names and unique prefixes resolve within `--project`; UUIDs also work.
155
- Adding work items resolves all references and checks project membership before
156
- writing. A work item belongs to one cycle, so adding it to another cycle moves it.
157
- `cycle transfer` uses the API's unfinished-work transfer: completed and cancelled
158
- work stays in the source cycle. Plane rejects transfers from a dated cycle that
159
- has not ended yet.
160
-
161
- Cycle creation accepts both `--start` and `--end`, or neither for a draft. The owner
162
- defaults to the token's user; `--owner` accepts a name, email or UUID. `cycle update`
163
- changes the name, description, owner or both dates. Passing `--start none --end none`
164
- clears the dates; either flag alone is rejected even when its value is `none`.
165
- Updating other fields preserves the existing cycle owner. Cycle dates are shown
166
- in the project timezone; JSON retains the original timestamps and includes that
167
- timezone. Module creation accepts `--start`, `--due`, `--description` and
168
- `--status backlog|planned|in-progress|paused|completed|cancelled`.
169
-
170
- The project switches `--cycles`, `--modules` and `--intake` enable these features;
171
- `--intake=false` (and likewise for the others) disables a feature. They work during
172
- both project creation and update. On creation, `--intake` also initializes the
173
- queue through a project update: setting the creation flag alone leaves the queue
174
- missing on some servers. If this follow-up step fails, the project remains created
175
- and a warning gives the `project update --intake` command to retry.
176
-
177
- Intake statuses are `pending`, `rejected`, `snoozed`, `accepted` and `duplicate`.
178
- `--status snoozed` requires `--snooze-until YYYY-MM-DD` (midnight UTC);
179
- `--status duplicate` requires `--duplicate-of KB-2`. Other status changes clear
180
- stale snooze and duplicate metadata. `intake update` also accepts `--name`,
181
- `--priority` and a Markdown `--description`. Accepting a request moves its work item
182
- from triage into the project's default state.
183
-
184
- Intake commands accept readable work item references or the underlying work item
185
- UUID, exposed as `issueId` in JSON. The intake entry's own `id` is different and is
186
- not the detail endpoint's key. Some servers hide expired snoozes from both intake
187
- GET and the normal work item lookup. In that case, use the saved `issueId` for
188
- `intake update` or `intake rm`: UUID writes do not require a preliminary intake GET.
189
- A readable reference still works for entries visible in the queue.
190
-
191
- `intake rm <ID> --project KB --yes` removes the intake
192
- entry; it deletes the underlying work item only if it has not been accepted.
48
+ Keep the file private with `chmod 600 ~/.config/plane/credentials`.
49
+ `i-plane config` shows the active settings with the token masked.
50
+ Flags override environment variables, which override the credentials file.
193
51
 
194
- ## Verify changes
52
+ ## Find your workflow
195
53
 
196
- From a repository checkout:
54
+ The CLI carries its own guide. Start here:
197
55
 
198
56
  ```bash
199
- bun test
200
- bun run check
201
- bun run lint
202
- bun run build
203
- node scripts/acceptance.mjs --live
204
- node scripts/planning-acceptance.mjs --live
57
+ i-plane guide # Command map and suggested workflow
58
+ i-plane create --help # Required flags and working examples
59
+ i-plane module --help # Commands for a feature area
60
+ i-plane intake update --help # Triage decisions and what to do next
205
61
  ```
206
62
 
207
- The live acceptance script uses the normal credentials and the built CLI. It
208
- creates a temporary project containing an epic and nine children, checks labels,
209
- assignment, dates, comments, states and archive, then deletes the project in a
210
- `finally` block. It spaces commands to respect the API request budget and takes
211
- several minutes. A forced process termination can interrupt cleanup; the script
212
- reports the project ID if normal cleanup fails.
63
+ Help includes usage notes, examples and **USUALLY NEXT** commands, so you can
64
+ follow a workflow without memorizing the API. Running `i-plane` with no arguments
65
+ also opens the guide.
213
66
 
214
- The planning acceptance script creates another temporary project and verifies
215
- cycle membership and unfinished-work transfer, module membership, and the intake
216
- lifecycle including deletion behavior. Both scripts use only CLI commands and
217
- clean up their own projects.
218
-
219
- The registry tests compare registered commands with executable handlers, parse every
220
- declared option, exercise each command through the CLI, and verify request payloads
221
- and output. The supported API surface and remaining gaps are in
222
- [docs/api-coverage.md](docs/api-coverage.md).
223
-
224
- ## Descriptions are Markdown
225
-
226
- Write them as Markdown; read them back as Markdown. Plane stores HTML, and the
227
- translation happens here.
228
-
229
- ````bash
230
- i-plane create --project CLOUD "Fix the resolver" --description '## Steps
67
+ A typical task session:
231
68
 
232
69
  ```bash
233
- dig +short example.com @127.0.0.1
70
+ i-plane summary
71
+ i-plane list APP --state unstarted
72
+ i-plane show APP-8 --comments
73
+ i-plane update APP-8 --state started
74
+ i-plane done APP-8
234
75
  ```
235
76
 
236
- | Node | Role | Status |
237
- | ---- | ---- | ------ |
238
- | cache | DNS | broken |
239
-
240
- 1. check the cache
241
- 2. check the routes'
242
- ````
243
-
244
- Code fences keep their language, tables stay tables, ordered lists stay numbered.
245
- Raw HTML in a description is escaped rather than passed through, so nothing you
246
- write can execute in someone else's browser.
247
-
248
- ## Good to know
249
-
250
- **A list is complete unless it says so.** `list` returns every work item in the
251
- project. `--limit` exists, but when it cuts the list the last line tells you how
252
- many rows it hid.
253
-
254
- **Exit codes mean something.** `2` — the command was wrong. `1` — Plane refused or
255
- could not be reached. Useful in scripts.
256
-
257
- **Proxies work without configuration.** If `HTTPS_PROXY` applies to your Plane
258
- address, it is used; `NO_PROXY` is honoured the way curl honours it, including
259
- CIDR ranges. On a network without a proxy none of this runs.
260
-
261
- If a call reports `EPERM` or `EACCES`, the operating system denied the connection
262
- before an HTTP response arrived. The diagnostic shows whether the CLI selected a
263
- proxy. Check the execution sandbox's network permission and local firewall rules;
264
- changing the API token does not resolve a socket permission error.
265
-
266
- ## Contributing
77
+ Replace `APP` and `APP-8` with your project and work item references. Add `--json`
78
+ to any command for its structured result. Exit code `2` means an invalid call;
79
+ `1` means an API or connection failure.
267
80
 
268
- `AGENTS.md` has the working rules: the invariants, the checks to run, and the
269
- bugs that already shipped once.
81
+ For supported fields, compatibility details and development checks, see the
82
+ [capability reference](docs/api-coverage.md).
270
83
 
271
84
  ## License
272
85