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

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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
+
+- The built-in Skill now treats credentials as an operator or agent-host provisioning precondition
+  and explains inherited environment, default `.env.local`, and explicit `--env-file` resolution.
+- Authentication is verified with a bounded Project read without inspecting, printing, copying, or
+  editing the token source.
+- The shell example that could encourage an agent to type a real token into a recorded interaction
+  has been removed, and missing or invalid credentials now direct the agent back to secure external
+  provisioning.
+
 ## 0.2.0-preview.2 - 2026-07-21
 
 ### Added

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.2.tgz
+npm install --global ./everfir-az8-cli-0.2.0-preview.4.tgz
 az8 --version
 ```
 
@@ -46,15 +46,20 @@ generation inputs.
 
 ## Credentials and environment
 
-Use an ignored `.env.local` or process environment:
+Credentials must be provisioned outside the agent's recorded interaction. Use an ignored
+`.env.local`, an explicit env-file path, or an inherited process environment:
 
 ```dotenv
-AZ8_TOKEN=...
+AZ8_TOKEN=<operator-provisioned-secret>
 AZ8_ENVIRONMENT=test
 ```
 
 `AZ8_ENVIRONMENT` accepts `test` or `production`. Command-line `--environment` overrides the env
-value. Tokens must not be passed through argv or stdio protocol payloads.
+value. Without `--env-file`, the CLI searches from the working directory upward for `.env.local`.
+An explicit file is selected by path, for example
+`--environment test --env-file /secure/path/.env.local`. Agents must not read, print, edit, or ask
+users to paste credential contents; verify authentication with a bounded `projects list` read.
+Tokens must not be passed through argv or stdio protocol payloads.
 
 ## Project Management
 
@@ -103,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>
@@ -202,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.2.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.2",
+  "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

@@ -21,8 +21,9 @@ capabilities instead of guessing operation names or input shapes.
   indeterminate result; do not execute later steps.
 - Never automatically retry a write. Retry only bounded reads when the returned error says doing so
   is safe. An idempotency key does not authorize blind replay.
-- Keep tokens in the process environment or an ignored env file. Never put a token in argv, an
-  stdio frame, a prompt, a log, or output.
+- Require the operator or agent host to provision credentials outside the recorded interaction.
+  Keep tokens in the inherited process environment or an ignored env file. Never type, read, copy,
+  print, or return a token through a shell tool call, argv, stdio frame, prompt, log, or output.
 
 ## Concepts
 
@@ -52,18 +53,41 @@ capabilities instead of guessing operation names or input shapes.
 
 ## Bootstrap
 
-1. Verify the installed client and explicitly choose an environment:
+1. Verify the installed client without credentials:
 
    ```bash
    az8 --version
-   export AZ8_ENVIRONMENT=test
-   export AZ8_TOKEN=...
    ```
 
-   Prefer an ignored `.env.local` when the shell environment is not appropriate. Never print the
-   token to confirm it.
+2. Require credentials to be provisioned by the operator or agent host before authenticating. The
+   CLI accepts `AZ8_TOKEN` from its inherited process environment or an env file. A provisioned env
+   file has this shape, but the agent must not fill the placeholder with a real token in a recorded
+   interaction:
 
-2. Select an existing Project or create a bounded workspace:
+   ```dotenv
+   AZ8_TOKEN=<operator-provisioned-secret>
+   AZ8_ENVIRONMENT=test
+   ```
+
+   With no `--env-file`, the CLI searches for `.env.local` from the working directory upward. An
+   explicit file may live elsewhere and is selected only by path:
+
+   ```bash
+   az8 projects list --scope owned --page-size 1 \
+     --environment test --env-file /secure/path/.env.local
+   ```
+
+   Use the authenticated read as the credential check. Never verify a token with `cat`, `sed`,
+   `grep`, `env`, `printenv`, `echo`, shell tracing, or by reading the env file through another
+   tool. Do not create, edit, move, or delete a credential file unless the operator explicitly asks
+   through a secure provisioning workflow. Keep it outside version control with owner-only access.
+
+   The inherited process environment overrides env-file values; `--environment` overrides
+   `AZ8_ENVIRONMENT`. Always pass or provision the intended environment explicitly. If the CLI
+   reports a missing token or authentication failure, stop and ask the operator to provision or
+   replace it outside the conversation. Never ask them to paste the secret into chat.
+
+3. Select an existing Project or create a bounded workspace:
 
    ```bash
    az8 projects list --scope owned
@@ -73,7 +97,7 @@ capabilities instead of guessing operation names or input shapes.
 
    Retain the returned Project ID. Confirm the authenticated role before assuming write access.
 
-3. Discover the effective surface for that Project:
+4. Discover the effective surface for that Project:
 
    ```bash
    az8 canvas query <project-id> capabilities.summary
@@ -85,32 +109,23 @@ capabilities instead of guessing operation names or input shapes.
    Schema, `effect`, `history`, `completion`, and `retry`. Availability is filtered by the current
    account, Project role, upstream services, and CLI version. Do not rely on remembered schemas.
 
-4. Use `canvas.detail` only when exact node geometry, Draft, status, or bindings are needed:
+5. Use `canvas.detail` only when exact node geometry, Draft, status, or bindings are needed:
 
    ```bash
    az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
    ```
 
-5. 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
@@ -129,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.
@@ -178,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> \
@@ -248,6 +283,8 @@ Never:
   conclude that an Awareness event persisted data;
 - expose a token, presigned URL, permanent media URL, env-file contents, or private output in logs
   or protocol payloads;
+- inspect, print, or edit an operator-provisioned credential source merely to check whether it
+  exists; authenticate with a bounded read instead;
 - use awareness client names to impersonate persisted authors or treat Attention Cursor position as
   authority;
 - use one-shot as if it retained History, Receipts, replay state, observations, or presence;