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

package/package.json

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

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.
@@ -279,15 +294,31 @@ 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 contains the Run, target View Node, and output Core Node
+   identities supplied by Workflow Runtime. 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,10 +335,10 @@ 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,
@@ -337,6 +368,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 +385,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