i-plane 1.0.2 → 1.1.1

package/README.md

@@ -64,11 +64,18 @@ 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
-update <ID>           --state --priority --name --description
+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
 ```
 
@@ -80,6 +87,149 @@ Work items go by the name people say — `CLOUD-8`. Projects take an identifier
 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
+```
+
+`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.
+
+`--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
+```
+
+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.
+
+`intake rm <ID> --project KB --yes` removes the intake
+entry; it deletes the underlying work item only if it has not been accepted.
+
+## Verify changes
+
+From a repository checkout:
+
+```bash
+bun test
+bun run check
+bun run lint
+bun run build
+node scripts/acceptance.mjs --live
+node scripts/planning-acceptance.mjs --live
+```
+
+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).
+
 ## Descriptions are Markdown
 
 Write them as Markdown; read them back as Markdown. Plane stores HTML, and the
@@ -94,7 +244,7 @@ dig +short example.com @127.0.0.1
 
 | Node | Role | Status |
 | ---- | ---- | ------ |
-| pi5  | DNS  | broken |
+| cache | DNS | broken |
 
 1. check the cache
 2. check the routes'
@@ -117,6 +267,11 @@ could not be reached. Useful in scripts.
 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.
+
 ## Contributing
 
 `AGENTS.md` has the working rules: the invariants, the checks to run, and the