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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.3.0-preview.3",
+  "version": "0.4.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

@@ -22,9 +22,10 @@ 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.
-- 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.
+- Prefer `az8 login` browser authorization for the current operating-system user. Externally
+  provisioned inherited-environment and env-file credentials remain higher-priority automation
+  inputs. Never type, read, copy, print, or return a token through a shell tool call, argv, stdio
+  frame, prompt, log, or output.
 
 ## Concepts
 
@@ -57,23 +58,45 @@ capabilities instead of guessing operation names or input shapes.
   name is always `<authenticated display name> (<client suffix>)`; the default suffix is `cli`.
   CLI awareness does not publish selection bounds. Awareness never grants authority, changes
   persisted authorship, or proves a business result.
-- **Actor** is the authenticated account from `AZ8_TOKEN`. A client or awareness name cannot
-  impersonate another author.
+- **Actor** is the account selected by the active credential source. A client or awareness name
+  cannot impersonate another author.
 
 ## Bootstrap
 
-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:
+1. Report the canonical working directory and intended environment. Then verify the installed
+   client without credentials:
 
    ```bash
    az8 --version
    ```
 
-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. Check the active identity without inspecting credential material:
+
+   ```bash
+   az8 whoami --environment test
+   ```
+
+   If no credential is available, invoke browser authorization and ask the user to approve the
+   request in the opened AZ8 Studio page:
+
+   ```bash
+   az8 login --environment test
+   ```
+
+   `login` emits the verification URL and User Code as structured progress while it waits. Do not
+   create a polling loop around it. If the browser cannot be opened on the agent host, use
+   `az8 login --environment test --no-open`, give the emitted URL to the user, and keep that one
+   command running until it succeeds or fails. Authorization delivery is at-most-once: a lost
+   response, cancelled CLI, or failed local save requires a completely new `az8 login`; never retry
+   the consumed exchange yourself.
+
+   The CLI stores browser-authorized credentials privately by operating-system user and environment.
+   `az8 logout` removes only that local credential and closes daemon Sessions that depend on it; it
+   is not online revocation. Do not log out automatically at task completion.
+
+   The CLI also accepts `AZ8_TOKEN` from its inherited process environment or an env file for
+   externally managed automation. A provisioned env file has this shape, but the agent must not fill
+   the placeholder with a real token in a recorded interaction:
 
    ```dotenv
    AZ8_TOKEN=<operator-provisioned-secret>
@@ -88,15 +111,16 @@ capabilities instead of guessing operation names or input shapes.
      --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.
+   Use `az8 whoami` 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.
+   The inherited process environment overrides env-file values, and env-file values override the
+   locally saved login; `--environment` overrides `AZ8_ENVIRONMENT`. `az8 login` can save a local
+   credential while an external credential remains active, so check the returned `credential.active`
+   field and use `az8 whoami` to confirm the effective Actor. Always pass or provision the intended
+   environment explicitly. Never ask the user to paste a secret into chat.
 
 3. Select an existing Project or create a bounded workspace:
 
@@ -114,7 +138,7 @@ capabilities instead of guessing operation names or input shapes.
    ```bash
    az8 session open <project-id> --environment test
    az8 session query capabilities.summary
-   az8 session query capabilities.detail
+   az8 session query capabilities.detail --operation-name <operation-name>
    az8 session query canvas.summary
    ```
 
@@ -126,9 +150,11 @@ capabilities instead of guessing operation names or input shapes.
    az8 canvas query <project-id> canvas.summary --environment test
    ```
 
-   `capabilities.summary` is the short menu. `capabilities.detail` is authoritative for exact JSON
-   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.
+   `capabilities.summary` is the short menu. Select one Operation with `--operation-name` when
+   querying `capabilities.detail`; that focused response is authoritative for exact JSON Schema,
+   `effect`, `history`, `completion`, and `retry`. Availability is filtered by the current account,
+   Project role, upstream services, and CLI version. Do not load the full detail catalog or rely on
+   remembered schemas.
 
 5. Use `canvas.detail` only when exact node geometry, Draft, status, or bindings are needed:
 
@@ -244,10 +270,12 @@ one-shot processes.
 ## Canvas SOP
 
 1. Query `canvas.summary`; query selected details only as needed.
-2. Query `capabilities.detail` and validate the planned Operation input against its schema.
+2. Query `capabilities.detail --operation-name <operation-name>` 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.
@@ -274,9 +302,14 @@ entries. Never use compensating low-level mutations to imitate undo.
 
 Generation is an explicit sequence, never one transaction:
 
+`getCoreNode` requires a non-empty unique `coreNodeIds` batch and returns `coreNodes` in request
+order. Treat any missing requested Core Node as a failed read.
+
 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
@@ -293,6 +326,9 @@ 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.
+   `addVisualReference` requires a non-empty unique `referenceViewNodeIds` batch, and
+   `removeVisualReference` requires a non-empty unique `referenceIds` batch. The runtime validates
+   the whole batch and writes the Draft once.
    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:
@@ -316,9 +352,11 @@ Generation is an explicit sequence, never one transaction:
    acknowledged. This completes the start interaction; it does not mean generation finished.
 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.
+   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
@@ -340,9 +378,24 @@ delivers each unchanged terminal fact once. User Workflow Interests are additive
 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
+Workflow Definitions change over time. Start with a bounded catalog page:
+
+```bash
+az8 session query workflowDefinitions.summary --page-size 10
+az8 session query workflowDefinitions.summary --workflow-target image --page-size 10
+```
+
+The compact response reports `catalog.targetCounts`, filtered `pagination.total`, and an opaque
+`pagination.nextCursor`. Continue only when more Definition identities are needed. Then query
 `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