@everfir/az8-cli 0.2.0-preview.3 → 0.2.0-preview.4

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable AZ8 CLI changes are recorded here. The CLI package has its own linear version sequence;
 it does not inherit the Web application or monorepo root version.
 
+## 0.2.0-preview.4 - 2026-07-22
+
+### Changed
+
+- Persistent NDJSON stdio is now the default interaction mode for every Canvas authoring task,
+  including a plan containing only one write.
+- One-shot is limited to isolated reads, standalone transfers, explicit caller choice, or hosts that
+  genuinely cannot retain a child process; fewer tool calls alone is not a valid reason to use it.
+- The outer repository Skill now requires preview.4 so a newly triggered agent receives this mode
+  selection policy.
+
 ## 0.2.0-preview.3 - 2026-07-21
 
 ### Changed

package/README.md

@@ -17,7 +17,7 @@ az8 guide
 For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.2.0-preview.3.tgz
+npm install --global ./everfir-az8-cli-0.2.0-preview.4.tgz
 az8 --version
 ```
 
@@ -108,6 +108,10 @@ the agent can verify identities, byte count, MIME, and SHA-256.
 One-shot commands open a real Canvas client, complete synchronization and hydration, invoke the same
 query or Operation used by the persistent client, and close after the result is authoritative:
 
+Persistent stdio is the default for any Canvas authoring task, including a plan with only one write.
+Use this wrapper only for an isolated read, standalone transfer, explicit one-shot request, or a host
+that cannot retain a child process and write later NDJSON to stdin.
+
 ```bash
 az8 canvas query <project-id> canvas.summary
 az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
@@ -207,6 +211,10 @@ retried. After any non-success, the agent must decide whether a new invocation i
 
 ## Persistent Canvas client
 
+This is the default mode whenever a task may perform any Canvas write. Open it before the first
+Canvas query, keep capability discovery and all ordered Operations in the same lifecycle, and shut
+it down only after the authoring task is complete.
+
 ```bash
 az8 canvas open <project-id> --write --format ndjson
 ```

package/RELEASE.md

@@ -35,7 +35,7 @@ repository-wide `pnpm verify`. Publishing is an external action and requires exp
 authorization:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.3.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.4.tgz --tag preview
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.2.0-preview.3",
+  "version": "0.2.0-preview.4",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",

package/skills/az8-cli/SKILL.md

@@ -115,26 +115,17 @@ capabilities instead of guessing operation names or input shapes.
    az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
    ```
 
-6. Choose one-shot for independent tasks and persistent stdio for a collaborative session. Finish
-   by inspecting the affected View Nodes or Workflow Run rather than trusting visual assumptions.
+6. If the task may perform any Canvas write, open one persistent stdio client before the first
+   Canvas read or write and retain it through the authoring session. Use one-shot only under the
+   explicit exceptions below. Finish by inspecting the affected View Nodes or Workflow Run rather
+   than trusting visual assumptions.
 
 ## Interaction modes
 
-Use one-shot commands for a self-contained query, write, upload, or download:
-
-```bash
-printf '%s\n' '{"text":"Idea","position":{"x":160,"y":160}}' |
-  az8 canvas operation <project-id> createNote --input-stdin --request-id create-note-1
-```
-
-- Supply Operation input through exactly one of `--input-stdin`, `--input-file`, or `--input-json`.
-- Give every write attempt a meaningful unique `--request-id` and retain its returned Receipt.
-- Each invocation opens, hydrates, executes, and closes a real Canvas client.
-- One-shot processes do not preserve local History, Receipt Log, Awareness, or request replay.
-  Therefore `undo`, `redo`, `receipts.summary`, and `receipt.detail` require persistent stdio.
-
-Use persistent stdio when multiple ordered interactions, live synchronization, History, Receipt
-lookup, observations, or human collaboration matter:
+Default to persistent stdio for Canvas authoring. A one-write plan still uses persistent stdio. This
+is the normal mode whenever a task may create, edit, move, organize, remove, undo, generate, import,
+or upload Canvas content. Open the client once, use it for capability discovery and subsequent reads
+and Operations, observe concurrent changes, and shut it down only after the Canvas task is complete:
 
 ```bash
 az8 canvas open <project-id> --write --format ndjson
@@ -153,6 +144,24 @@ az8 canvas open <project-id> --write --format ndjson
 Protocol truth is written to stdout. stderr contains diagnostics only. Unknown optional fields are
 additive; ignore them. Do not treat a process exit code as the result of the last persistent request.
 
+Use one-shot only for:
+
+- an isolated read when no Canvas write is planned;
+- a standalone media download;
+- an explicitly standalone upload/import whose caller does not want an ongoing authoring session;
+- an explicit user request for one-shot behavior; or
+- a host that genuinely cannot retain a child process and write later NDJSON to its stdin.
+
+Do not choose one-shot merely because the current plan has one write or because it requires fewer
+tool calls. Codex and other hosts with retained process sessions can use persistent stdio. If a host
+limitation forces fallback, disclose that the client will not preserve local History, Receipt Log,
+Awareness, observations, or request replay across invocations.
+
+For a permitted one-shot call, supply Operation input through exactly one of `--input-stdin`,
+`--input-file`, or `--input-json`, give every write a meaningful unique `--request-id`, and retain its
+returned Receipt. `undo`, `redo`, `receipts.summary`, and `receipt.detail` are never available across
+one-shot processes.
+
 ## Canvas SOP
 
 1. Query `canvas.summary`; query selected details only as needed.
@@ -202,7 +211,9 @@ claim actual credit consumption from an estimate.
 
 ## Media
 
-For a local image, video, or audio file, use the semantic upload wrapper:
+Within an active persistent authoring session, invoke the discovered `uploadMedia` Operation so the
+write shares that client lifecycle. For an explicitly standalone local image, video, or audio
+transfer, use the semantic one-shot upload wrapper:
 
 ```bash
 az8 canvas upload <project-id> \