i-plane 1.1.1 → 1.2.0

package/AGENTS.md

@@ -1,94 +1,173 @@
 # Working on this repository
 
-Read this before changing anything here. It is not documentation of what the tool
-does — that is `README.md` — it is what breaks when the rules below are ignored.
+Read this before changing the CLI. README.md is the short package introduction;
+`i-plane guide` and command help explain usage. `docs/api-coverage.md` records the
+supported API surface, compatibility details and development checks.
 
-## What this is
+## Purpose
 
-A CLI for [Plane](https://plane.so) whose caller is a coding agent, not a person
-at a terminal. Plane's REST answer for seven work items is ~6,500 tokens of JSON;
-this prints ~145 tokens of lines. Every rule below follows from that one fact.
-
-## Authorship
-
-Written by Claude (Anthropic) with the repository owner. The owner decides what
-gets built and what ships; the model writes the code, runs the checks, and
-reports what it finds — including when the finding is its own bug.
+A Plane CLI for coding agents and automation. Compact, predictable output is a
+product requirement: callers should not need large REST responses or an
+interactive terminal to understand and update their work.
 
 ## Invariants
 
-Breaking one of these is a bug even when tests pass.
-
-**Nothing prompts, ever.** A CLI that waits for input hangs an agent forever. A
-missing argument is a `UsageError` naming what was expected; `src/commands/guide.ts`
-turns it into a hint with that command's real examples.
-
-**Exit codes are a contract.** `2` the call was wrong, `1` Plane refused or was
-unreachable. Callers branch on the code instead of parsing text, so a
-misclassified error is worse than a vague message.
-
-**`--json` is never optional.** Commands build a model and hand it to a formatter;
-`printValue` in `src/output.ts` decides between them. Print directly and you have
-silently dropped `--json` for that command.
-
-**`src/registry.ts` is the single source for commands.** It feeds the guide, every
-`<command> --help`, and the hint on a failed call — and it is what rejects unknown
-flags. Add a flag to a command without adding it there and the CLI will refuse it.
-
-**Never trust a server-side filter.** The list endpoint honours `fields` and
-`expand` (11 KB → 737 bytes on the wire) but accepts `state_group`, `priority` and
-`order_by` with a 200 and ignores them. Narrowing happens in `src/commands/issues.ts`.
-
-**Never let the token reach text.** `redact` in `src/client.ts` guards every error
-path; `maskToken` guards `config`. Node puts an offending header value into its
-own error message, and a server can echo a key back in an error body.
-
-**Pin versions exactly.** A range once meant the tree tested here and the tree a
-user installs were different — undici, `^7.16.0` against 8.10.2 installed.
-
-## Ground already lost once
-
-Twenty-one findings came out of one review. These are the ones worth remembering:
-
-| What happened | Why |
-|---|---|
-| ` ```c++ ` hung the process forever | a fence pattern that refused a line without consuming it |
-| `--yes=false` deleted a work item | a switch tested for presence, not value |
-| a misspelled `--priority` returned an unfiltered list, exit 0 | no flag validation |
-| the API token appeared in an error message | masking guarded one command, not the error paths |
-| a description lost `<div>` inside inline code | entity decoding followed by tag stripping |
-
-The Markdown conversion was hand-written and lost five ways at once. It now uses
-`markdown-it` and `turndown`. `markdown-it` rather than `marked` for one reason:
-with `html:false` it escapes raw HTML instead of passing `<img src=x onerror=…>`
-into other people's browsers.
+**Nothing prompts.** Missing arguments and invalid values raise `UsageError`
+with an actionable hint. Never wait for interactive input.
+
+**Exit codes are a contract.** Use `2` for an invalid call and `1` for an API or
+connection failure. Do not classify a transport failure as invalid user input.
+
+**Every command supports JSON.** Build an output model and pass it through
+`printValue` in `src/output.ts`. Text and JSON must describe the same result.
+Guide/help models include global options and usage notes as well as commands.
+
+**The registry owns the CLI contract.** `src/registry.ts` declares command names,
+aliases, arguments, options, required markers, examples, usage notes and next
+steps. The parser derives value flags from it. Online handlers live in
+`src/dispatch.ts`; the registry and handler table must agree in both directions.
+Required markers document the contract; handlers still validate the arguments.
+
+**Help is part of the implementation.** A new command needs a purpose, supported
+fields, requirements, realistic examples and follow-up calls. Keep summaries
+short; put decisions and limitations in usage notes. All example flags must be
+accepted by that command. Do not advertise API/UI fields that the CLI cannot set.
+Keep README concise and point readers to `guide` and `--help` for workflows.
+
+**Never trust a server-side filter without checking it.** Use `fields`, `expand`
+and pagination to limit wire size while collecting all pages. The work item
+endpoint can accept state, priority and ordering filters without applying them;
+those filters are handled in the client. Check behavior, not only HTTP status.
+
+**Never let a token escape.** Register `guardSecret` before diagnostics. All
+output goes through the guards in `src/output.ts`; client errors are redacted,
+and config output uses `maskToken`. Redact before truncating or formatting.
+A server response or a native error can echo credentials back.
+
+**A successful write stays successful.** Resolve and validate inputs before
+writing. Do not report a successful mutation as failed because an optional
+follow-up read or setup step failed. Return the created identifier and a clear
+warning with a recovery command. Do not automatically retry uncertain writes.
+
+**Markdown has a defined scope.** Work item and intake descriptions, and comment
+bodies, use Markdown converted at the API boundary. Project, label, state, cycle
+and module descriptions are plain text. Keep the established `markdown-it` and
+`turndown` conversion; raw HTML must remain escaped in Markdown input.
+
+**Runtime and dependency claims must agree.** Support Node 22.21+ on the 22.x
+line or Node 24+. Keep README and `package.json` engines consistent. Undici 8.x
+requires Node 22.19+; the native proxy fallback requires Node 22.21 or Node 24.
+Pin dependencies exactly and keep optional `undici` external to the bundle.
+Do not infer minimum-version compatibility from a build on a newer runtime.
+
+## API behavior that must survive changes
+
+- Project names reject special characters, including hyphens. Validate before
+  the creation request. API routes and defaults must be checked on the target
+  server; newer UI documentation can describe different behavior.
+- `--label` merges with existing labels; `--labels` replaces them. Plane replaces
+  the whole labels array. Read-modify-write can still race with another editor.
+- Resolve readable work item references and names before writes. Reject ambiguous
+  matches, and validate project membership for bulk cycle/module assignment.
+- `project create --intake` must initialize the queue with a project PATCH.
+  Setting the creation flag alone can leave a missing queue and cause HTTP 500.
+- Cycle updates preserve the existing owner when `--owner` is absent. Some
+  servers otherwise default ownership to the requesting user.
+- Cycle dates must be supplied or cleared together, including `none`. Format
+  their timestamps in the project timezone; retain raw timestamps in JSON.
+- A work item has one cycle but can belong to several modules. Cycle transfer
+  moves unfinished work and leaves completed/cancelled work in the source.
+- Expired snoozes may disappear from intake GET and normal triage lookup.
+  Intake update/delete by work item UUID must not require a preliminary GET.
+  If a readable reference cannot resolve, explain how to use saved `issueId`.
+- Intake status is separate from work item state. Acceptance moves triage work
+  to the project default state on the supported API path. Removing an accepted
+  intake entry keeps the work item; removing an unaccepted entry deletes it too.
+
+Regression history also includes infinite Markdown fence parsing, lost inline
+HTML inside code, ignored unknown flags, and `--yes=false` confirming deletion.
+Preserve coverage for these cases when refactoring.
 
 ## Checks
 
 ```bash
-bun test                              # every case is a bug that shipped once
-./node_modules/.bin/tsc --noEmit      # src and types; tests are checked by bun
+bun test
+./node_modules/.bin/tsc --noEmit
 ./node_modules/.bin/biome check .
-node scripts/release.mjs              # the full gate, without publishing
+node scripts/release.mjs
 ```
 
-Tests are deliberately not in `tsc`'s `include`: pulling `bun-types` in collides
-with `@types/node` inside the library's own declarations, and a type error in
-someone else's file says nothing about this code.
+Tests cover regressions, registry/handler agreement, executable help examples,
+request payloads, output and errors. A test that only accepts any exception or
+checks that a function was called does not establish correct behavior.
+
+TypeScript checks `src` and `types`; tests run under Bun. Do not add `bun-types`
+to the project's TypeScript compilation just to include tests: its declarations
+can conflict with `@types/node`. Exercise the built Node entry point too.
 
-## Testing against a live instance
+## Live checks
 
-Credentials are at `~/.config/plane/credentials` and the CLI reads them itself, so
-`node dist/cli.js list CLOUD` works with no arguments. Delete anything you create:
+The CLI reads `~/.config/plane/credentials` itself. Keep secrets out of command
+arguments and logs where possible. Use the local build when checking new code:
 
 ```bash
-node dist/cli.js delete CLOUD-42 --yes
+bun run build
+node dist/cli.js list CLOUD
 ```
 
-## Releasing
-
-Publishing is irreversible — a version cannot be reused, and a tarball that
-shipped too much stays in every mirror. `node scripts/release.mjs` does
-everything except publish; `--publish` is the only path to `npm publish`. The gate
-empties `dist`, runs the checks, smoke-tests the built command, enforces package
-contents and size, and refuses when the registry cannot be reached.
+Prefer a short, targeted scenario for the behavior changed. Use a temporary
+project for writes and remove it afterwards. Do not change working project data
+as test fixtures. Preserve a created project's identifier if cleanup fails.
+
+The full scripts `scripts/acceptance.mjs --live` and
+`scripts/planning-acceptance.mjs --live` use real CLI commands and clean up their
+projects in `finally`. They take several minutes because they space requests.
+Do not repeat both scripts for a documentation edit or a narrow fix that can be
+verified with a focused check. Respect the API request budget and use bounded,
+observable waits. A forced termination can interrupt cleanup.
+
+`EPERM`/`EACCES` before an HTTP response indicates an operating-system permission
+failure. Check the selected proxy route and sandbox network access before
+changing credentials or application code. An installed CLI can also differ from
+the local build: check its version before diagnosing missing commands.
+
+## Releases and tracking
+
+Keep `package.json` and `src/cli.ts` versions in sync. The release gate empties
+`dist`, runs checks, builds, smoke-tests the command, validates the exact package
+contents and size, and checks registry availability. Changes to shipped files
+must update both `package.json` files and the gate's allowlist.
+
+Publishing is irreversible. `node scripts/release.mjs` does not publish;
+`--publish` is the publishing path. Obtain authorization for publication and
+reuse it within the authorized release rather than asking repeatedly.
+
+A successful npm upload can return HTTP 202 while registry processing continues.
+Do not republish the same version or treat a transient post-upload 404 as a
+failed upload. Distinguish submission from public availability, use short bounded
+checks, and verify the published version and `latest` tag before claiming both
+are available.
+
+Keep project task statuses aligned with the work. Move a task into progress when
+starting, close it after its checks, and reopen it when a confirmed review finding
+invalidates completion. Report whether a change is local, installed or published;
+these are separate states. Keep commits and public metadata provider-agnostic.
+
+## Page command invariants
+
+Page commands use SessionClient, never the API-key client. Load Yjs, the live
+provider and WebSocket dependencies lazily; keep their exact versions external
+in both build paths. Session cookies and passwords join the API token in the
+secret guard, including old cookies after a refresh.
+
+Live success means acknowledged delivery, not a database commit. Never replay a
+mutation automatically. Complete asynchronous conversion before resolving a
+block anchor and checking its content fingerprint inside one transaction. Read
+commands never stamp. Only page stamp assigns missing top-level anchors.
+
+--yes confirms deletion; --force bypasses a stale fingerprint; --allow-loss
+accepts reported conversion losses. These decisions must stay separate. Empty
+--block must fail before a whole-page mutation can be selected.
+
+Page fixtures and wire tests live under tests/page*. Unsupported rich content
+must remain visible or produce an explicit loss warning.

package/README.md

@@ -1,281 +1,91 @@
 # i-plane
 
-A command-line client for [Plane](https://plane.so) that prints lines instead of
-JSON dumps.
+**Plane project management from the command line.**
 
-Ask Plane's API for seven work items and it answers with twenty-nine fields
-each — about 6,500 tokens. The same seven through `i-plane` are 145. If you are
-piping work items into a coding agent, that difference is the entire point.
+Find the next task, read the discussion, update the work and keep moving.
+`i-plane` brings your [Plane](https://plane.so) workspace into the terminal,
+with compact output for coding agents and scripts.
 
-```
-$ i-plane list CLOUD --state started
-CLOUD-4  Create and assign work items [high] (In Progress)
-CLOUD-5  Visualize your work (In Progress)
+```console
+$ i-plane list APP --state started
+APP-9  Fix search indexing [urgent] (In Progress)
+APP-8  Refresh the onboarding guide [high] (In Progress)
 ```
 
-## Install
+Readable references like `APP-8`, Markdown for work item descriptions and
+comments, and `--json` whenever you need structured data. Nothing prompts for input.
 
-```bash
-npm install -g i-plane
-```
+## What you can do
 
-Node 20 or newer.
+- **Manage tasks:** search, create, update and complete work; set parents,
+  assignees, labels and dates; read and write comments.
+- **Set up projects:** create projects, configure workflow states and labels,
+  enable planning features, and archive finished projects.
+- **Plan delivery:** schedule work in cycles, carry unfinished tasks forward,
+  and group related work in modules that can span multiple cycles.
+- **Triage requests:** collect reports in intake, then accept, reject, snooze
+  or mark them as duplicates before committing to the work.
+- **Maintain project knowledge:** read pages, inspect live blocks and edit only
+  the section you need, with fingerprints to detect concurrent changes.
+- **Automate:** use concise lists, JSON output and distinct exit codes in
+  agent workflows and shell scripts.
 
-## Set it up
+## Install and connect
 
-You need three things: the address of your Plane, an API key, and a workspace.
-The key comes from **Workspace settings → API tokens**.
-
-Supply them however suits you — flags win over environment, environment wins over
-the file:
+Requires **Node 22.21+ on the 22.x line, or Node 24+**.
 
 ```bash
-# once, in a file
-mkdir -p ~/.config/plane && chmod 700 ~/.config/plane
-cat > ~/.config/plane/credentials <<'EOF'
-PLANE_URL=https://plane.example.com
-PLANE_API_KEY=plane_api_…
-PLANE_WORKSPACE=my-workspace
-EOF
-chmod 600 ~/.config/plane/credentials
-
-# or per call
-i-plane list CLOUD --url https://plane.example.com --token … --workspace my-workspace
-```
-
-Not sure what is in effect:
-
-```
-$ i-plane config
-url        https://plane.example.com  (file)
-workspace  my-workspace  (env)
-token      plane_…856f  (file)
-file       /home/you/.config/plane/credentials
-```
-
-## Use it
-
-Run `i-plane` with no arguments and it shows the command map, the usual order of
-work, and how it behaves. `i-plane <command> --help` gives one command's flags
-and real examples.
-
-```
-summary               projects and how much is in each
-list [project]        work items, one line each    --state --priority --limit
-show <ID>             one work item, description included
-search <text>         across the whole workspace
-create <title>        --project --priority --state --description --label --parent --assignee --due --start
-update <ID>           --state --priority --name --description --label --labels --parent --assignee --due --start
-done <ID>             move to the first completed state
-comment <ID> <text>   add a comment
-comments <ID>         read comments; show <ID> --comments includes them too
-delete <ID> --yes     delete; refuses without --yes
-project create|update|archive|rm
-label create|rm       --project
-state create|update|rm --project
-cycles  cycle create|update|add|issues|transfer
-modules module create|add|issues
-intake list|create|show|update|rm
-projects  states  labels  members  whoami  config  guide
-```
-
-Short forms for what fingers type: `ls`, `new`, `set`, `rm`, `find`.
-
-Work items go by the name people say — `CLOUD-8`. Projects take an identifier
-(`CLOUD`), a full name, or a unique prefix of one.
-
-Every command accepts `--json` and then prints the whole model, for when you need
-ids and timestamps rather than a readable line.
-
-## Set up a project
-
-```bash
-i-plane project create "Knowledge Base" --identifier KB --description "Team notes"
-i-plane label create epic --project KB --color '#8ED1FC'
-i-plane label create task --project KB --color '#3B82F6'
-i-plane create "Build the knowledge base" --project KB --label epic --priority high
-# Use the identifier returned by create as the parent of each child:
-i-plane create "Define the structure" --project KB --parent KB-1 --label task --priority urgent
-i-plane update KB-2 --assignee "Reader" --start 2026-10-01 --due 2026-10-08
-i-plane state create Review --project KB --group started --color '#336699'
-i-plane update KB-2 --state Review
-i-plane comments KB-2
-i-plane show KB-2 --comments
+npm install -g i-plane
 ```
 
-`project update` changes the name, identifier or description. Project names cannot
-contain special characters, including hyphens; the CLI checks before sending a
-request. Identifiers contain 1–12 letters or digits, start with a letter, and are
-normalized to uppercase. `project archive` hides a project from active lists.
-`project rm <project> --yes` permanently deletes it and its contents.
-
-`--label task,review` adds labels and preserves the current ones. `--labels task`
-replaces the entire list; `--labels none` clears it. Both flags accept names, unique
-name prefixes or IDs and cannot be combined. Repeating a flag keeps its last
-value, so use one comma-separated list for multiple labels. Addition reads the
-current labels before writing the merged list; concurrent label edits can still
-race because the API replaces the array.
+Create a [Plane API token](https://developers.plane.so/api-reference/introduction#authentication)
+and save these settings in `~/.config/plane/credentials`:
 
-`--parent` accepts a readable work item identifier, or a UUID in the same project.
-`--assignee` replaces the list with comma-separated display names, emails or UUIDs.
-Ambiguous names fail instead of selecting a match. `--parent none`, `--assignee none`,
-`--due none` and `--start none` clear their fields. Dates use `YYYY-MM-DD`.
-
-`label rm <label> --project KB --yes` removes a label. `state update` changes a
-state's name, color, group or description; `state rm` requires `--yes`. State and
-label names accept an exact match, unique prefix or ID. Descriptions of projects,
-labels and states are plain text; work item descriptions and comments are Markdown.
-
-## Plan work and triage incoming requests
-
-Use intake for a bug report, support request or idea that still needs a decision.
-Use a module for a feature, milestone or workstream with a shared goal; its work
-may span several cycles and belong to other modules too. Cycles define the time
-window for planned work.
-
-Command help includes required options, usage notes, examples and follow-up
-calls. For the field-by-field distinction between Plane and CLI capabilities,
-see [API coverage and concepts](docs/api-coverage.md#what-modules-and-intake-are-for).
-
-```bash
-i-plane project update KB --cycles --modules --intake
-i-plane cycle create "Sprint 1" --project KB --start 2026-10-01 --end 2026-10-14
-i-plane cycle create "Sprint 2" --project KB --start 2026-10-15 --end 2026-10-28
-i-plane cycles KB
-i-plane cycle add KB-2 KB-3 --project KB --cycle "Sprint 1"
-i-plane cycle issues "Sprint 1" --project KB
-# After Sprint 1 has ended:
-i-plane cycle transfer "Sprint 1" "Sprint 2" --project KB
-
-i-plane module create Documentation --project KB --status planned
-i-plane modules KB
-i-plane module add KB-2 KB-3 --project KB --module Documentation
-i-plane module issues Documentation --project KB
-
-i-plane intake create "Investigate a reported problem" --project KB --priority high
-i-plane intake list KB --status pending
-# Use the work item reference returned by intake create:
-i-plane intake show KB-4 --project KB
-i-plane intake update KB-4 --project KB --status accepted
+```ini
+PLANE_URL=https://plane.example.com
+PLANE_API_KEY=your-api-token
+PLANE_WORKSPACE=your-workspace-slug
 ```
 
-A cycle groups work by time; a module groups related work independently of sprint
-dates. Names and unique prefixes resolve within `--project`; UUIDs also work.
-Adding work items resolves all references and checks project membership before
-writing. A work item belongs to one cycle, so adding it to another cycle moves it.
-`cycle transfer` uses the API's unfinished-work transfer: completed and cancelled
-work stays in the source cycle. Plane rejects transfers from a dated cycle that
-has not ended yet.
-
-Cycle creation accepts both `--start` and `--end`, or neither for a draft. The owner
-defaults to the token's user; `--owner` accepts a name, email or UUID. `cycle update`
-changes the name, description, owner or both dates. Passing `--start none --end none`
-clears the dates; either flag alone is rejected even when its value is `none`.
-Updating other fields preserves the existing cycle owner. Cycle dates are shown
-in the project timezone; JSON retains the original timestamps and includes that
-timezone. Module creation accepts `--start`, `--due`, `--description` and
-`--status backlog|planned|in-progress|paused|completed|cancelled`.
-
-The project switches `--cycles`, `--modules` and `--intake` enable these features;
-`--intake=false` (and likewise for the others) disables a feature. They work during
-both project creation and update. On creation, `--intake` also initializes the
-queue through a project update: setting the creation flag alone leaves the queue
-missing on some servers. If this follow-up step fails, the project remains created
-and a warning gives the `project update --intake` command to retry.
-
-Intake statuses are `pending`, `rejected`, `snoozed`, `accepted` and `duplicate`.
-`--status snoozed` requires `--snooze-until YYYY-MM-DD` (midnight UTC);
-`--status duplicate` requires `--duplicate-of KB-2`. Other status changes clear
-stale snooze and duplicate metadata. `intake update` also accepts `--name`,
-`--priority` and a Markdown `--description`. Accepting a request moves its work item
-from triage into the project's default state.
-
-Intake commands accept readable work item references or the underlying work item
-UUID, exposed as `issueId` in JSON. The intake entry's own `id` is different and is
-not the detail endpoint's key. Some servers hide expired snoozes from both intake
-GET and the normal work item lookup. In that case, use the saved `issueId` for
-`intake update` or `intake rm`: UUID writes do not require a preliminary intake GET.
-A readable reference still works for entries visible in the queue.
+Keep the file private with `chmod 600 ~/.config/plane/credentials`.
+`i-plane config` shows the active settings with the token masked.
+Flags override environment variables, which override the credentials file.
 
-`intake rm <ID> --project KB --yes` removes the intake
-entry; it deletes the underlying work item only if it has not been accepted.
+## Find your workflow
 
-## Verify changes
-
-From a repository checkout:
+The CLI carries its own guide. Start here:
 
 ```bash
-bun test
-bun run check
-bun run lint
-bun run build
-node scripts/acceptance.mjs --live
-node scripts/planning-acceptance.mjs --live
+i-plane guide                 # Command map and suggested workflow
+i-plane create --help         # Required flags and working examples
+i-plane module --help         # Commands for a feature area
+i-plane intake update --help  # Triage decisions and what to do next
 ```
 
-The live acceptance script uses the normal credentials and the built CLI. It
-creates a temporary project containing an epic and nine children, checks labels,
-assignment, dates, comments, states and archive, then deletes the project in a
-`finally` block. It spaces commands to respect the API request budget and takes
-several minutes. A forced process termination can interrupt cleanup; the script
-reports the project ID if normal cleanup fails.
-
-The planning acceptance script creates another temporary project and verifies
-cycle membership and unfinished-work transfer, module membership, and the intake
-lifecycle including deletion behavior. Both scripts use only CLI commands and
-clean up their own projects.
-
-The registry tests compare registered commands with executable handlers, parse every
-declared option, exercise each command through the CLI, and verify request payloads
-and output. The supported API surface and remaining gaps are in
-[docs/api-coverage.md](docs/api-coverage.md).
+Help includes usage notes, examples and **USUALLY NEXT** commands, so you can
+follow a workflow without memorizing the API. Running `i-plane` with no arguments
+also opens the guide.
 
-## Descriptions are Markdown
-
-Write them as Markdown; read them back as Markdown. Plane stores HTML, and the
-translation happens here.
-
-````bash
-i-plane create --project CLOUD "Fix the resolver" --description '## Steps
+A typical task session:
 
 ```bash
-dig +short example.com @127.0.0.1
+i-plane summary
+i-plane list APP --state unstarted
+i-plane show APP-8 --comments
+i-plane update APP-8 --state started
+i-plane done APP-8
 ```
 
-| Node | Role | Status |
-| ---- | ---- | ------ |
-| cache | DNS | broken |
-
-1. check the cache
-2. check the routes'
-````
-
-Code fences keep their language, tables stay tables, ordered lists stay numbered.
-Raw HTML in a description is escaped rather than passed through, so nothing you
-write can execute in someone else's browser.
-
-## Good to know
-
-**A list is complete unless it says so.** `list` returns every work item in the
-project. `--limit` exists, but when it cuts the list the last line tells you how
-many rows it hid.
-
-**Exit codes mean something.** `2` — the command was wrong. `1` — Plane refused or
-could not be reached. Useful in scripts.
-
-**Proxies work without configuration.** If `HTTPS_PROXY` applies to your Plane
-address, it is used; `NO_PROXY` is honoured the way curl honours it, including
-CIDR ranges. On a network without a proxy none of this runs.
-
-If a call reports `EPERM` or `EACCES`, the operating system denied the connection
-before an HTTP response arrived. The diagnostic shows whether the CLI selected a
-proxy. Check the execution sandbox's network permission and local firewall rules;
-changing the API token does not resolve a socket permission error.
+Replace `APP` and `APP-8` with your project and work item references. Add `--json`
+to any command for its structured result. Exit code `2` means an invalid call;
+`1` means an API or connection failure.
 
-## Contributing
+For supported fields, compatibility details and development checks, see the
+[capability reference](docs/api-coverage.md).
 
-`AGENTS.md` has the working rules: the invariants, the checks to run, and the
-bugs that already shipped once.
+Pages use a Plane login and password instead of an API token. See the
+[page workflow](docs/pages.md) for session setup, block edits and delivery semantics.
+`i-plane page --help` carries the same command examples into your terminal.
 
 ## License