i-plane 1.2.0 → 2.0.0

package/docs/api-coverage.md

@@ -27,6 +27,30 @@ The compatibility target uses the `issues/` routes. The current public
 documents `work-items/` instead. A route migration must be verified against the
 target server; do not change paths solely to match a newer documentation release.
 
+## Argument, selection and completeness contracts
+
+Commands that address one resource reject extra positional tokens before
+configuration or requests. Quote a multiword reference, such as
+`i-plane project rm "Knowledge Base" --yes`. Create titles, comment/search text
+and bulk cycle/module additions retain their intentional variadic inputs.
+
+`done` preserves the selected completed-state UUID. Case-insensitive name ties
+are errors for explicit state selection; a state group still selects its first
+state. Use a state UUID when names collide.
+
+`list --limit` accepts a nonnegative integer, including zero. `search --limit`
+accepts integers from 1 to 1000 and defaults to 10. Search requests one additional
+match from the supported endpoint to detect truncation, then returns
+`{ rows, limit, hasMore }` in JSON. Text output explains when more matches exist;
+raise the bound or narrow the query. No exact total is inferred. This replaces
+the earlier bare search-results array and undocumented server-default cap.
+
+Paged collections require a valid results array and a nonempty continuation
+cursor when another page is advertised. Repeated cursors fail instead of
+repeating requests or returning duplicated rows. A final bare array remains
+supported. Calendar date fields accept valid dates in years 0001–9999; year zero
+is rejected before mutations, as it is outside the backend's date range.
+
 ## What modules and intake are for
 
 A module groups work toward a feature, milestone or other goal and may span
@@ -102,9 +126,9 @@ API endpoints; the diagnostic points to `issueId` from an earlier JSON response.
 
 ## Project pages
 
-`pages` and `page show` use the internal session API. `page outline`, `page read`,
+`pages` and `page show` automatically select API-key or native session page access. `page outline`, `page read`,
 `page stamp`, `page create`, `page set`, `page insert` and block removal use the
-live document protocol. Whole-page deletion uses the session API. See the
+live document protocol. Whole-page deletion uses the selected page endpoint. See the
 [page workflow](pages.md) for credentials, fingerprints, formatting losses and
 asynchronous persistence. This internal API can change independently of Plane's
 public API; compatibility is covered by converter fixtures and live acceptance.
@@ -113,7 +137,7 @@ public API; compatibility is covered by converter fixtures and live acceptance.
 
 1. Add the command and all options to `src/registry.ts`. The parser gets value
    flags from the registry, including those of multiword commands.
-2. Add an online handler to `src/dispatch.ts` or a session handler to `src/page-dispatch.ts`. Both missing handlers and handlers
+2. Add an online handler to `src/dispatch.ts` or a page handler to `src/page-dispatch.ts`. Both missing handlers and handlers
    absent from the registry fail the command-set test.
 3. Add a fixture invocation and valid option values to the registry suite. Test
    the requested method, path and body, and assert observable output. Merely
@@ -165,3 +189,60 @@ The page acceptance script creates and removes one page in the selected existing
 project. It exercises all nine commands and observes saved HTML within a bounded
 window; that window is a test limit, not a persistence guarantee. Run
 `node scripts/page-mutations.mjs` for isolated mutation checks.
+
+### Automatic page transport
+
+`AutoPageClient` probes the public project-page list, prefers API-key access and
+selects the native session API only when the route is absent and runtime
+configuration does not advertise API-key pages. Permission failures and individual
+page `404` responses never cause fallback. Capabilities are cached per instance
+for five minutes, with `--refresh-pages` for immediate redetection. Config output
+explains the cached selection without network access or loading session settings.
+
+The session implementation and credentials load lazily. Session-only page access
+remains supported; ordinary commands still require the public API key. A definite
+HTTP `401` may refresh session authentication once; live may refresh once only
+before synchronization. Live mutations are never replayed. API-key access never
+refreshes through password sign-in. Both paths keep conversion on their selected
+HTTP transport and reject redirects to avoid forwarding credentials.
+
+Tests cover both identities, cache isolation/expiry/reset, installation transitions,
+missing credentials, permission failures, redaction, session refresh and live
+handshakes. See [pages.md](pages.md) for configuration and cache paths.
+
+Run `node scripts/page-mutations.mjs` to check that the page tests detect intentional
+regressions. `scripts/page-key-acceptance.mjs` exercises a built CLI against an
+isolated deployment using a private test fixture and a browser. It creates a page,
+checks both writers, stale fingerprints and deletion, then removes the test page.
+The package ships command help and user documentation; repository-only contributor
+instructions are excluded from the release archive.
+
+### Automatic transport verification
+
+The built Node CLI passed all nine page commands against isolated Plane 1.4.2
+instances both with API-key pages enabled and with the official, unmodified
+backend/live images. Each run verified live editing, stale fingerprints, language
+preservation, saved HTML and cleanup. The stock instance also passed session-only
+access without an API key. No production rollout or npm publication was performed.
+
+The release dry run passed 1,318 tests, TypeScript, formatting, Node smoke checks,
+lazy dependency loading and package inventory checks. Nine deliberate mutations
+were detected, including permission-triggered fallback and non-expiring capability
+selection. These checks cover IPL-24; they do not resolve the separate PLX-11 review
+findings in the extension layer and whole-page review conversion.
+
+### Review follow-up verification
+
+Saved page reads preserve semantic review fences and can restore older sanitized
+HTML from canonical JSON by block ID. Invalid or unmatched metadata, unsupported
+wrappers, stale review order and malformed tables produce explicit losses.
+A real built-CLI `page show` to file to `page set` round trip passed with exact
+review date/source retained after browser reload. Unsupported underline content
+reported a read loss and refused replacement without `--allow-loss`.
+
+Late capability removal now repeats reference resolution before any mutation;
+HTTP and live mutation markers prevent replay once a write has started. Targeted
+independent reviews of formatting and command targeting found no remaining
+confirmed issues. The complete release dry run passed 1,338 tests and twelve
+intentional mutation checks. The aggregate extension review remains separately
+tracked in PLX-12; these results do not claim production deployment or publication.

package/docs/pages.md

@@ -1,27 +1,76 @@
 # Project pages
 
 Read project knowledge as Markdown, then change a section without rewriting the
-rest of the document. Pages use Plane's internal session API and live editor;
-they are available on instances exposing project pages and the live service.
+rest of the document. Page metadata uses an automatically selected API-key or session endpoint; content
+changes use the collaborative live editor.
 
 ## Connect
 
-Add these to your private credentials file alongside `PLANE_URL` and
-`PLANE_WORKSPACE`:
+Configure the same settings used for work items:
 
 ```ini
-PLANE_LOGIN=you@example.com
+PLANE_URL=https://plane.example.com
+PLANE_WORKSPACE=workspace
+PLANE_API_KEY=your-api-key
+```
+
+The CLI first tries the public project-page list with the API key. With the
+for-plane API-key pages extension enabled, HTTP and live use that key. Login,
+password and session-cache settings are not resolved or loaded on this path.
+The server derives identity and checks page permissions; read commands request
+read-only live access. Both transports honor `HTTPS_PROXY`, `HTTP_PROXY` and
+`NO_PROXY`.
+
+On stock Plane, a missing public list route selects the native session API.
+Configure these additional values in the credentials file or environment:
+
+```ini
+PLANE_LOGIN=reader@example.com
 PLANE_PASSWORD=your-password
 ```
 
-An API token is optional for page commands and still required for work items.
-`i-plane config` reports whether credentials are configured and where they came
-from, without printing the login password or cookies. Sessions persist under
-`$XDG_CACHE_HOME/i-plane/sessions` or `~/.cache/i-plane/sessions`; the directory
-has mode 700 and files have mode 600. A restricted environment can select a
-private writable directory with `PLANE_SESSION_CACHE` or `--session-cache`.
-An expired session receives one refresh. HTTP and WebSocket connections honor
-`HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY`.
+Password sign-in must be enabled on the server. Session-only page access also
+works without an API key; other commands still require one. The CLI reports
+missing session settings before attempting sign-in. Session cookies are cached
+privately (directory mode 700, file mode 600), keyed by instance URL and login.
+`PLANE_SESSION_CACHE` or `--session-cache <directory>` changes their location;
+the default is `$XDG_CACHE_HOME/i-plane/sessions` or `~/.cache/i-plane/sessions`.
+Passwords are never stored in the cookie cache.
+
+### Detection and diagnostics
+
+`i-plane config` is offline: it reports settings, masks the API key and shows the
+cached page access path, its reason and expiry. Before the first page command,
+or after expiry, it reports `unknown` rather than claiming a network check.
+
+Capability detection is cached per instance URL for **five minutes**, independently
+of the cookie cache. The cache contains no credentials. It defaults to
+`$XDG_CACHE_HOME/i-plane/page-transports` or `~/.cache/i-plane/page-transports`;
+`PLANE_PAGE_CACHE` can override the directory. Missing, expired, invalid or
+unwritable cache files do not prevent detection. After installing extensions,
+force immediate discovery with `i-plane pages APP --refresh-pages`, or clear the
+selection with `i-plane config --refresh-pages`. No manual transport switch is needed.
+A newly configured key rechecks a selection previously made without a key.
+
+A `401`, `403`, network failure or server error never selects session fallback.
+Only a page **list** `404` triggers a capability check; a missing individual page
+stays a missing page. If the runtime reports API-key pages enabled, even a list
+`404` remains an access/project error. An absent runtime route or explicitly
+unavailable API-key feature permits the session path. Cached choices can remain
+stale within the five-minute window; use `--refresh-pages` after server changes.
+
+The session path refreshes authentication once on an HTTP `401` or a definite
+live authentication refusal **before synchronization**. Other errors do not retry.
+Live content changes and uncertain writes are never replayed automatically.
+Stock Plane determines the permissions of session live connections; the CLI's
+read commands do not mutate documents. API-key connections require the current
+runtime release; session live connections negotiate it too when present. An adapter
+with no installed runtime package retains stock session live access. When detection
+changes the identity to a session user, project references are resolved again under
+that user before reading or writing pages, so cold and cached commands target the
+same project. If a cached API-key route disappears during a list read, the command
+resolves its original references again before any mutation. An HTTP or live
+mutation that has started is never replayed.
 
 ## Read, inspect, edit
 
@@ -74,12 +123,13 @@ clears a whole page, but empty block replacement or insertion is refused. Use
 `page rm --block` for a block deletion. Page deletion always requires `--yes`. Plane requires archiving first; the CLI
 archives and then deletes the page. If deletion fails, the error reports the
 archived page UUID so you can inspect and recover it.
-Nested pages and `--parent` are unsupported by the project-page API.
+Nested pages can be read and edited by UUID. Listing returns root pages; name
+resolution uses that list. The CLI does not expose a `--parent` option.
 
 ## Delivery and formatting
 
 Successful editing means **the live server acknowledged delivery**. It does not
-confirm a database commit. `page show` reads saved HTML and can immediately show
+confirm a database commit. `page show` reads saved HTML, preserves semantic review fences and reports unsupported rich content in JSON `losses` and stderr warnings. It can immediately show
 the previous content: persistence usually takes about ten seconds, with no
 guaranteed upper bound. Use `page outline` and `page read` to check the immediate
 live result. An interrupted write without an acknowledgement reports uncertain
@@ -96,3 +146,33 @@ Replacement checks the affected document and converted input. Reported losses
 require `--allow-loss`; `--force` does not approve them. A block edit leaves other
 blocks intact. None of these commands prompts for input, and every command
 supports `--json`. Run `i-plane page set --help` for flags and examples.
+
+## Knowledge review marks
+
+Saved detail responses from the matching extension include canonical JSON for
+review restoration. If older HTML lost review attributes, `page show` can recover
+them by the retained block ID. Missing or ambiguous IDs, invalid canonical fields,
+stale review order and unsupported wrappers produce explicit losses. Canonical
+JSON is used internally and omitted from the CLI output.
+
+With the knowledge-review extension installed, a `knowledgeReview` block reads as
+an ordinary fenced code block containing JSON:
+
+````markdown
+```knowledge-review
+{
+  "date": "2026-09-11",
+  "source": "Release notes and a manual check"
+}
+```
+````
+
+`page read --block` returns this representation with no losses. Include it in a
+Markdown file passed to `page set --file`, or use it for a block replacement, to
+restore the same date and source as a semantic review node. `page outline` shows
+`knowledgeReview` and a preview of both fields. Review dates use `YYYY-MM-DD` and
+must be valid calendar dates; sources are nonempty strings. JSON escaping preserves
+quotes and newlines. Unknown fields are rejected instead of silently discarded.
+
+The fence language is reserved for review metadata. Raw HTML remains escaped.
+Other unknown editor nodes still produce loss warnings and readable XML output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i-plane",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Compact Plane CLI for coding agents: tasks, projects, live pages, cycles, modules and intake.",
   "type": "module",
   "license": "MIT",
@@ -15,9 +15,7 @@
   "files": [
     "dist",
     "docs/api-coverage.md",
-    "docs/pages.md",
-    "AGENTS.md",
-    "CLAUDE.md"
+    "docs/pages.md"
   ],
   "engines": {
     "node": "^22.21.0 || >=24.0.0"

package/AGENTS.md

@@ -1,173 +0,0 @@
-# Working on this repository
-
-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.
-
-## Purpose
-
-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
-
-**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
-./node_modules/.bin/tsc --noEmit
-./node_modules/.bin/biome check .
-node scripts/release.mjs
-```
-
-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.
-
-## Live checks
-
-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
-bun run build
-node dist/cli.js list CLOUD
-```
-
-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/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md