@everfir/az8-cli 0.3.0 → 0.4.0

package/package.json

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

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,7 +270,8 @@ 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 generation target first, inspect whether its eligible default Draft was
@@ -275,6 +302,9 @@ 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. The same creation interaction initializes an account-eligible default
@@ -296,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:
@@ -345,7 +378,15 @@ 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