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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.3.0-preview.1",
+  "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.
@@ -230,12 +245,20 @@ one-shot processes.
 
 1. Query `canvas.summary`; query selected details only as needed.
 2. Query `capabilities.detail` and validate the planned Operation input against its schema.
-3. Pick explicit absolute Canvas coordinates. Public move positions remain absolute even for group
+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 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.
+   Do not create a placeholder while its type or placement is still ambiguous. Watch and the
+   Session daemon never create placeholders automatically.
+4. Pick explicit absolute Canvas coordinates. Public move positions remain absolute even for group
    children.
-4. Submit one Operation with a new request ID and wait for its terminal Receipt.
-5. Confirm the Receipt outcome and affected IDs, then query the changed View Node when subsequent
+5. Submit one Operation with a new request ID and wait for its terminal Receipt.
+6. Confirm the Receipt outcome and affected IDs, then query the changed View Node when subsequent
    work depends on its exact state.
-6. Only then plan the next interaction.
+7. Only then plan the next interaction.
 
 Common capabilities include notes, manual Text Resources, move/resize/rename, duplicate/remove,
 groups and stacking, Core Node placement, and generation targets. The runtime catalog is
@@ -270,11 +293,32 @@ Generation is an explicit sequence, never one transaction:
    plan.
 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 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
@@ -283,6 +327,19 @@ Generation is an explicit sequence, never one transaction:
 8. On terminal success, query the target detail and resolve its current output Core Node through
    Project Content before downloading or placing it elsewhere.
 
+If `startGeneration` returns an indeterminate Receipt after the Workflow was accepted, retain
+`receipt.result.workflowRunId` and `receipt.result.viewNodeId`, reconnect the Session, and invoke
+`reconcileGenerationStart` with those two identities. Never call `startGeneration` again for that
+intent. `running-insufficient` means the Run is still authoritative but does not yet expose enough
+target evidence: wait and reconcile later. `repaired` means the CLI restored the missing Canvas
+launch facts through the semantic Command path. `conflict` or `insufficient` requires inspection;
+neither authorizes a retry.
+
+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.
@@ -311,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.
 
@@ -325,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