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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.3.0-preview.2",
+  "version": "0.3.0",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",
@@ -16,7 +16,7 @@
   "main": "./dist/main.js",
   "publishConfig": {
     "access": "public",
-    "tag": "preview"
+    "tag": "latest"
   },
   "scripts": {
     "build": "pnpm build:dependencies && rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node22.12 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",

package/skills/az8-cli/SKILL.md

@@ -62,7 +62,9 @@ capabilities instead of guessing operation names or input shapes.
 
 ## Bootstrap
 
-1. Verify the installed client without credentials:
+1. Report the canonical working directory and intended environment before asking the operator to
+   provision an env file. This tells them where automatic `.env.local` discovery begins without
+   inspecting the file or secret. Then verify the installed client without credentials:
 
    ```bash
    az8 --version
@@ -162,15 +164,28 @@ Session resolution is explicit and discoverable. A command-level `--session <id>
 parallel Agents intentionally sharing one working directory. `session list`, `current`, `status`,
 and `use` must be used whenever the binding is uncertain; never guess a Session or Project.
 
-Configure named semantic Interests once, then use the singular blocking Watch instead of polling:
+The Session always installs the visible, read-only `system.workflow-terminal` Interest. It retains
+every terminal Workflow fact discoverable during this Project Session, including locally started
+Runs and pending Runs introduced by Web or another client. Do not add or maintain Run ID filters
+merely to receive completions. Configure only additional semantic Interests, then use the singular
+blocking Watch:
 
 ```bash
-az8 session interests patch --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}},{"key":"workflow-terminal","patch":{"kind":"workflow"}}]}'
+az8 session interests patch \
+  --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}}]}'
 az8 session watch --timeout-ms 30000
 ```
 
+- Whenever waiting is the next useful action, invoke exactly one `az8 session watch` immediately in
+  the foreground. Process its result, act if needed, then invoke one new foreground Watch if waiting
+  is still useful. This is the fastest Agent response path because the daemon journals facts between
+  calls.
+- Never wrap Watch in a `while`, `for`, recursive, timer, or repeated shell loop. Never launch it
+  with `&`, `nohup`, a detached terminal, or a background task. Such a process can consume the
+  readiness event before the Agent can reason about it.
 - Canvas Interests exclude the Session's own changes unless `includeOwn: true` is explicit.
-- Workflow Interests are terminal-only unless progress status is explicitly requested.
+- The system Workflow Interest is terminal-only. Add a user Workflow Interest only when
+  pending/running progress affects a concrete decision.
 - `idle` ends one observation window normally. It does not indicate a failed connection or Run.
 - `resync-required` means bounded continuity was lost. Query authoritative summary/detail, then run
   `az8 session resynchronize`; never pretend the missing interval was observed.
@@ -232,7 +247,8 @@ one-shot processes.
 2. Query `capabilities.detail` and validate the planned Operation input against its schema.
 3. When artifact type and placement are already clear, make the first meaningful Canvas state
    visible before doing lengthy prompt refinement or generation planning:
-   - create the empty generation target first, then plan and edit its Draft;
+   - create the generation target first, inspect whether its eligible default Draft was
+     initialized, then plan and edit;
    - create an empty manual Text Resource with `text: ""`, then fill it with
      `editTextContent`;
    - create a Note with its useful content directly rather than creating an empty sticky.
@@ -261,7 +277,9 @@ Generation is an explicit sequence, never one transaction:
 
 1. Create a target with `createGenerationTarget` and retain its View Node ID. It accepts `audio`,
    `image`, `text`, or `video`; `createMediaTarget` remains a compatibility capability for non-text
-   targets when advertised.
+   targets when advertised. The same creation interaction initializes an account-eligible default
+   Draft when one exists; inspect `draftInitialized`, `definitionId`, and `selectionSource`. This is
+   convenience state only: it does not start or estimate generation.
 2. Call the read-only `planGeneration` Operation with the target, prompt, and any references. Use
    `detail: "detail"` when configuration fields or dynamic enum options are needed.
    Every reference must be `{ "viewNodeId": "..." }`. If the desired Core Node is not currently
@@ -279,15 +297,33 @@ Generation is an explicit sequence, never one transaction:
 4. Execute `plan.operations` exactly in order, one Operation at a time. Each step revalidates
    current facts. Stop after the first non-success.
    When a reference must also appear at a meaningful Prompt position, use
-   `insertPromptReference` with the target View Node, visible reference View Node, and
-   `placement: "start"` or `"end"`. The CLI creates and validates the binding and At token
+   `insertPromptReference` with the target View Node and visible reference View Node. Use
+   `placement: "start"` or `"end"` for boundary placement, or anchor a named concept precisely:
+
+   ```json
+   {
+     "viewNodeId": "target_view_node",
+     "referenceViewNodeId": "character_view_node",
+     "placement": {
+       "kind": "after",
+       "anchor": { "text": "豆豆", "occurrence": 2 }
+     }
+   }
+   ```
+
+   `occurrence` is one-based and may be omitted only when the text occurs once. A missing or
+   ambiguous anchor fails without writing. The CLI creates and validates the binding and At token
    atomically. Do not write `{{@...}}`, choose an input slot/index, or allocate a binding ID
    yourself. `addVisualReference` remains the connection-only operation.
 5. `startGeneration` succeeds when the Workflow Run is accepted and immediate Canvas effects are
    acknowledged. This completes the start interaction; it does not mean generation finished.
-6. Retain the Workflow Run ID. After the successful start Receipt, continue any work that does not
-   require the generated output. Prefer `workflowChanged` observations while the persistent client
-   is active, and use `getWorkflowRun` at a meaningful later checkpoint.
+6. Retain the Workflow Run ID. The Session automatically covers its terminal state through
+   `system.workflow-terminal`; call one foreground `az8 session watch` whenever completion is the
+   next useful event. The terminal summary includes the target View Node only when the Session can
+   map it uniquely from authoritative launch or Canvas History facts. If `targetResolution` is
+   `unresolved` or `ambiguous`, query the Run and Canvas rather than guessing. Continue other work
+   first when it does not require the output, and use `getWorkflowRun` at a meaningful
+   authoritative checkpoint.
 7. Use `waitWorkflowRun` only when the next step actually requires terminal output and the current
    request lane can remain dedicated to waiting. Choose one intentional observation window; do not
    emulate polling with repeated short waits. An observation-window timeout while the authoritative
@@ -304,14 +340,21 @@ target evidence: wait and reconcile later. `repaired` means the CLI restored the
 launch facts through the semantic Command path. `conflict` or `insufficient` requires inspection;
 neither authorizes a retry.
 
-A Workflow Interest performs an authoritative status catch-up for Run IDs already known to the
-Session; explicit `filter.runIds` narrows or restores that set when needed. This closes
-missed-live-event races and delivers each unchanged terminal fact once. Keep explicit Run ID filters
-current across handoffs; the daemon does not scan unrelated Workflow Runs.
+The system Workflow Interest performs authoritative catch-up for Run IDs known to the Session and
+delivers each unchanged terminal fact once. User Workflow Interests are additive and may narrow
+progress observations, but cannot remove or narrow the system terminal stream. This is Session
+discovery, not an account-wide or historical Workflow event log.
 
 Workflow Definitions change over time. Query `workflowDefinitions.summary`, then
 `workflowDefinition.detail` only when planning detail is insufficient. Never guess a Definition,
 configuration option, modality, cost, or media compatibility from its display name.
+Summary discovery, defaults, planning, and start are filtered to Definitions available to the
+authenticated account. Detail may retain an unavailable historical Definition for diagnosis and
+marks it with `availableForAccount` and `accessReason`.
+
+Workflow tags classify compatibility, access, and rollout; they are not pricing evidence.
+`available:free` means a free-tier account may select that Workflow. It does not mean generation
+costs zero credits. Use planning/start estimates and terminal usage records for credit information.
 
 The start Receipt may report `usage.credits.status` as `estimated`, `not-consumed`, or `unknown`.
 Estimated cost is informational, not final charged usage. There is no second confirmation. Never
@@ -337,6 +380,9 @@ az8 canvas upload <project-id> \
   error. Replay only after inspecting and reconciling the prior attempt.
 - Let the CLI inspect bytes, MIME, size, and checksum and let the server create the Core Node and
   binding. Do not supply a claimed media type, upload URL, Core Node ID, or Project Content record.
+- Treat `az8.operation-progress.v1` lines on stderr as provisional feedback. The stages are
+  `inspecting`, `requesting-upload`, `uploading`, `creating-content`, and `updating-canvas`; only the
+  terminal Receipt proves the Operation outcome. Progress never authorizes a retry.
 - A known failure may leave one inspectable `failed` View Node. An unknown response leaves it
   `pending` and isolates the context; do not create a replacement until reconciliation.
 
@@ -351,7 +397,10 @@ az8 canvas download <project-id> --view-node-id <view-node-id> --output ./result
 
 The destination must be explicit. Existing files are preserved unless `--overwrite` is explicitly
 chosen. Verify the returned absolute path, byte count, detected MIME, Core Node ID, and SHA-256.
-Never extract or reuse hidden media URLs as a general downloader.
+The CLI may automatically retry only retryable read/transfer phases, at most three total attempts
+under the original deadline. It re-resolves the source and removes every partial temporary file
+before retrying. Inspect `error.phase`, `retryable`, `attempts`, sanitized `cause`, `localState`, and
+`remoteState` after failure. Never extract or reuse hidden media URLs as a general downloader.
 
 ## Recovery