@everfir/az8-cli 0.3.0-preview.2 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ it does not inherit the Web application or monorepo root version.
 
 ## Unreleased
 
+## 0.3.0 - 2026-07-23
+
+### Added
+
+- Account-aware Workflow discovery and selection, using the same free-account eligibility rule as
+  Web while keeping unavailable historical Definitions inspectable in detail.
+- Web-equivalent default generation Drafts and private local Workflow preferences scoped by
+  environment, authenticated account, and output content type.
+- Truthful terminal Workflow target identity derived from retained launch facts or unique Canvas
+  History, with explicit unresolved and ambiguous states when evidence is insufficient.
+- Daemon-backed collaboration Sessions, manual and generated Text Resources, semantic Prompt
+  reference insertion, structured transfer progress, and bounded download recovery.
+
+### Changed
+
+- `createGenerationTarget` initializes an eligible default Draft in the same undoable interaction;
+  prompt-only `editGenerationDraft` uses the same resolver when a historical target has no Draft.
+- Generation plans preserve their effective prompt and configuration when input modality switches
+  to another Workflow Definition and rebuilds the target Draft.
+- Workflow summary, defaults, planning, reference edits, and generation start reject Definitions
+  unavailable to the authenticated account. `available:free` is treated only as free-tier access,
+  never as pricing evidence.
+- Agent guidance prioritizes one foreground `session watch`, early visible targets, authoritative
+  planning, and explicit reconciliation instead of polling, guessed At syntax, or write retries.
+
+### Safety and compatibility
+
+- Public writes remain semantic Operations backed by internal Commands. No Workflow preference,
+  access rule, or Watch enrichment grants a raw Canvas mutation path.
+- Local preferences contain only a Definition id and sanitized scalar config values; they never
+  contain credentials, prompts, media URLs, or Project data.
+- Stable protocol `1.0`, sequential write blocking, no automatic write retry, and explicit
+  generation acceptance/completion boundaries remain unchanged from `0.2.0`.
+
+## 0.3.0-preview.3 - 2026-07-23
+
+### Added
+
+- Every collaborative Session receives discoverable Workflow terminal events by default, including
+  the Workflow Run, target View Node, and output Core Node identities.
+- Prompt references can be inserted before or after an exact text occurrence without exposing raw
+  Canvas data.
+- Media uploads report structured stage, byte, and percentage progress across one-shot, persistent
+  stdio, and daemon-backed Session transports.
+
+### Changed
+
+- Media downloads use bounded read-only retries under one caller deadline, clean partial files, and
+  return structured, credential-safe transport diagnostics when recovery fails.
+- The built-in agent Skill prioritizes a single foreground `session watch` call, warns against
+  background polling loops, and documents terminal reconciliation and exact Prompt placement.
+
+### Safety and compatibility
+
+- User Workflow Interests remain additive and cannot disable the system terminal stream.
+- Download retries never extend the caller deadline or apply to definitive verification failures.
+- Upload progress is provisional observability and cannot change the semantic Operation result.
+
 ## 0.3.0-preview.2 - 2026-07-23
 
 ### Added

package/README.md

@@ -15,10 +15,10 @@ az8 help
 az8 guide
 ```
 
-For a supplied preview artifact, install the exact immutable tarball instead:
+For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.3.0-preview.2.tgz
+npm install --global ./everfir-az8-cli-0.3.0.tgz
 az8 --version
 ```
 
@@ -114,12 +114,13 @@ az8 session query canvas.summary
 
 The Session remains selected for the current canonical working directory, so subsequent commands do
 not repeat its ID. Use `session current`, `list`, and `status` rather than guessing which Project or
-daemon is active. Configure semantic Interests and block on one Watch call when collaboration
-updates matter:
+daemon is active. The visible, read-only `system.workflow-terminal` Interest automatically retains
+terminal facts for locally started and remotely discovered pending Runs. Configure only additional
+semantic Interests and block on one Watch call when collaboration updates matter:
 
 ```bash
 az8 session interests patch \
-  --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}},{"key":"workflow-terminal","patch":{"kind":"workflow"}}]}'
+  --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}}]}'
 az8 session watch --timeout-ms 30000
 az8 session close
 ```
@@ -127,6 +128,9 @@ az8 session close
 `watch` returning `idle` is a successful empty observation window, not a connection error. Exactly
 one caller may wait on a Session. The daemon retains the authenticated connection and collaboration
 state between short CLI invocations, but it does not wake or restart an Agent that has exited.
+Agents should call exactly one Watch in the foreground whenever waiting is useful, process the
+result, then call it once again if needed. Do not build a shell loop, background Watch, or polling
+substitute; those add scheduling delay and can consume an event before the Agent reasons about it.
 
 For a manual human–Agent interaction latency check, have the Agent report that it is ready, start
 one 60-second Watch, and only then make one recognizable Canvas change from Web:
@@ -144,12 +148,16 @@ the CLI's local observation-to-delivery delay; neither includes speech recogniti
 host's scheduling time. Repeat only a small bounded sample, keep the Session open between trials,
 and remove the temporary Interest or close the Session afterward.
 
-For generation, create a target with `createGenerationTarget` (including `contentType: "text"`) and
-call `planGeneration` with the returned View Node and a prompt. Execute its returned
+For generation, create a target with `createGenerationTarget` (including `contentType: "text"`).
+Creation initializes an account-eligible default Draft when available and reports
+`draftInitialized`, `definitionId`, and `selectionSource`; it never starts generation. Call
+`planGeneration` with the returned View Node and a prompt. Execute its returned
 `plan.operations` in order, stopping after the first failure. A
 successful `startGeneration` Receipt contains the Workflow Run identity; call `waitWorkflowRun`
 separately when a terminal output is required. Planning and starting are intentionally not one
-transaction.
+transaction. In an active Session, prefer one foreground `session watch`: the system terminal event
+includes the target View Node only when it can be mapped uniquely from authoritative launch or
+Canvas History facts; unresolved or ambiguous mappings are reported rather than guessed.
 
 For media transfer, `canvas upload` places a verified local image/video/audio file through the
 server-owned Core Node path. After detail query resolves the target's `resolvedCoreNodeId`, `canvas
@@ -232,8 +240,10 @@ Project Content through a deterministic, opaque intent fingerprint in its source
 existing binding returns without another upload, while conflicting key reuse fails. Results include
 View Node/Core Node identities and reproducible file metadata but never the presigned or permanent
 file URL. The wrapper uses the standard `az8.canvas.one-shot.v1` output and exit codes and defaults
-to a 300-second deadline. Batch upload, replacement, text-file import, and a durable local upload
-cache are outside the initial slice.
+to a 300-second deadline. Uploads emit rate-limited `az8.operation-progress.v1` lines to stderr for
+`inspecting`, `requesting-upload`, `uploading`, `creating-content`, and `updating-canvas`; final
+stdout remains one structured result and only its Receipt is authoritative. Batch upload,
+replacement, text-file import, and a durable local upload cache are outside the initial slice.
 
 ## Local media download
 
@@ -262,8 +272,12 @@ Success writes one `az8.canvas.media-download.v1` document with the absolute pat
 SHA-256, detected MIME/extension, response metadata, resolved Core Node identity, and whether a file
 was replaced. It deliberately omits the media URL. Exit `0` is success; exit `1` is a definitive
 source, HTTP 4xx, or local-path failure; exit `2` is a retryable connection, HTTP 429/5xx, transfer,
-integrity, or timeout failure; exit `130` is caller cancellation. Downloads are never automatically
-retried. After any non-success, the agent must decide whether a new invocation is safe.
+or timeout failure; exit `130` is caller cancellation. Retryable read/transfer phases are
+automatically attempted at most three times under the original deadline; every attempt re-resolves
+the source and leaves no partial destination. Definitive failures, verification mismatch, timeout,
+and cancellation are not retried. Failure output includes attempts, phase, retryability, sanitized
+cause when available, local commit state, and remote-state certainty. After non-success, the agent
+must use those facts to decide whether a new invocation is safe.
 
 ## Lower-level persistent stdio client
 
@@ -303,7 +317,14 @@ Node hierarchy operations, and the Stage 3 Core Node creative loop. Note operati
 `addVisualReference`, `removeVisualReference`, `startGeneration`, `getWorkflowRun`, and
 `waitWorkflowRun`. Capability detail is discoverable through `capabilities.detail`; callers should
 use it instead of hard-coding input schemas. Workflow Definitions are available through
-`workflowDefinitions.summary` and `workflowDefinition.detail` queries.
+`workflowDefinitions.summary` and `workflowDefinition.detail` queries. Summary discovery, default
+Drafts, planning, and generation start use only Definitions available to the authenticated account.
+Detail may retain an unavailable historical Definition for diagnosis with
+`availableForAccount: false` and an `accessReason`.
+
+Workflow tags describe classification, compatibility, access, and rollout rather than price.
+`available:free` means a free-tier account may select the Workflow; it does not mean zero-credit
+generation. Credit claims must come from planning/start estimates or terminal usage records.
 
 Before editing a Draft, an agent can call the read-only `planGeneration` Operation for an existing
 generation target. It recommends a Definition from the target and resolved generation-reference modalities,
@@ -323,6 +344,12 @@ creates the Text Core Node only after the estimate succeeds. The published opera
 `addVisualReference` and `removeVisualReference` are retained for compatibility and also carry these
 planned Text bindings.
 
+`insertPromptReference` additionally places the platform-owned At token at `start`, `end`, or
+before/after an exact text anchor such as
+`{"kind":"after","anchor":{"text":"豆豆","occurrence":2}}`. Occurrence is one-based and is optional
+only for a unique anchor. Missing or ambiguous anchors fail without writing. Callers never construct
+At syntax, binding IDs, or slot indexes.
+
 ```json
 {"protocolVersion":"1.0","requestId":"plan-1","type":"operation","payload":{"name":"planGeneration","input":{"targetViewNodeId":"<target-id>","prompt":"A quiet observatory","references":[{"viewNodeId":"<reference-id>"}],"detail":"detail"}}}
 ```

package/RELEASE.md

@@ -57,18 +57,18 @@ Before publishing, also run the test-environment acceptance checklist in the pac
 repository-wide `pnpm verify`. Publishing is an external action and requires explicit operator
 authorization:
 
-For a preview candidate, publish the exact retained artifact to the preview channel:
+For the `0.3.0` stable candidate, publish the exact retained artifact to the stable channel only
+after its test-environment acceptance succeeds:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.3.0-preview.2.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.3.0.tgz --tag latest
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 
 Publish only the exact retained tarball whose SHA-512 appears in its release verification record.
-Do not publish from an unverified source directory. A later stable promotion uses a new stable
-version and `--tag latest`; it never retags or republishes this immutable preview artifact. If the
-obsolete misspelled `prewview` tag still exists, remove that tag without unpublishing its immutable
-version:
+Do not publish from an unverified source directory, retag a preview artifact as stable, or rebuild
+after acceptance. If the obsolete misspelled `prewview` tag still exists, remove that tag without
+unpublishing its immutable version:
 
 ```bash
 npm dist-tag rm @everfir/az8-cli prewview