@everfir/az8-cli 0.3.0 → 0.5.0

package/README.md

@@ -18,7 +18,7 @@ az8 guide
 For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.3.0.tgz
+npm install --global ./everfir-az8-cli-0.5.0.tgz
 az8 --version
 ```
 
@@ -40,27 +40,41 @@ az8 guide --format json
 ```
 
 The guide teaches discovery; it does not freeze dynamic product schemas. After selecting a Project,
-the agent must query `capabilities.summary` and `capabilities.detail` for the effective Operations,
-permissions, input schema, History, completion, and retry semantics of the installed version and
-current account. Workflow Definition queries and `planGeneration` remain authoritative for current
-generation inputs.
+the agent must query `capabilities.summary`, then focused `capabilities.detail --operation-name`
+responses for the effective Operations, permissions, input schema, History, completion, and retry
+semantics of the installed version and current account. Workflow Definition queries and
+`planGeneration` remain authoritative for current generation inputs.
 
-## Credentials and environment
+## Credentials
 
-Credentials must be provisioned outside the agent's recorded interaction. Use an ignored
-`.env.local`, an explicit env-file path, or an inherited process environment:
+Use browser authorization for the default local account:
+
+```bash
+az8 login
+az8 whoami
+az8 logout
+```
+
+`login` opens AZ8 Studio, waits for explicit approval, validates the issued account, and stores the
+credential in the current operating-system user's private AZ8 CLI
+state directory. `whoami` reports the active account and credential source without exposing the
+token. `logout` closes daemon Sessions that depend on that local credential and removes it locally;
+it does not revoke copies on other machines. Use `login --no-open` when the browser must be opened
+manually; the verification URL is emitted as structured progress on stderr.
+
+Externally provisioned credentials remain supported for automation. Use an ignored `.env.local`,
+an explicit env-file path, or an inherited process environment:
 
 ```dotenv
 AZ8_TOKEN=<operator-provisioned-secret>
-AZ8_ENVIRONMENT=test
 ```
 
-`AZ8_ENVIRONMENT` accepts `test` or `production`. Command-line `--environment` overrides the env
-value. Without `--env-file`, the CLI searches from the working directory upward for `.env.local`.
+Without `--env-file`, the CLI searches from the working directory upward for `.env.local`.
 An explicit file is selected by path, for example
-`--environment test --env-file /secure/path/.env.local`. Agents must not read, print, edit, or ask
-users to paste credential contents; verify authentication with a bounded `projects list` read.
-Tokens must not be passed through argv or stdio protocol payloads.
+`--env-file /secure/path/.env.local`. Process-environment credentials take
+precedence over env files, which take precedence over the locally saved login. The CLI never
+rewrites an env file or inherited environment. Agents must not read, print, edit, or ask users to
+paste credential contents. Tokens must not be passed through argv or stdio protocol payloads.
 
 ## CLI architecture
 
@@ -69,7 +83,8 @@ validation boundary. CLI-specific code is organized by responsibility:
 
 - `src/cli/` owns program assembly, runtime config, persistent stdio transport, output framing, and
   package version resolution.
-- `src/commands/` declares Project, Canvas, and guide commands.
+- `src/auth/` owns browser authorization, account-service exchange, and private local credentials.
+- `src/commands/` declares account, Project, Canvas, and guide commands.
 - `src/agent-session/` owns isolated daemon lifecycles, local Session discovery, the private RPC
   carrier, Watch delivery, and current-context selection.
 - `src/canvas/` owns collaboration sessions, one-shot execution, awareness, and the NDJSON
@@ -100,12 +115,13 @@ indeterminate.
 
 ## First agent loop
 
-A new agent needs only the installed package, a token, and this document. Start by creating its own
-Project, then open one daemon-backed Agent Collaboration Session:
+A new agent needs only the installed package, an authorized account, and this document. Confirm the
+active identity, then create its own Project and open one daemon-backed Agent Collaboration Session:
 
 ```bash
+az8 whoami
 az8 projects create --name "Agent preview workspace"
-az8 session open <project-id> --environment test
+az8 session open <project-id>
 az8 session query capabilities.summary
 az8 session operation createNote --request-id preview-note-1 \
   --input-json '{"text":"Release smoke note","position":{"x":160,"y":160}}'
@@ -294,7 +310,7 @@ az8 canvas open <project-id> --write --format ndjson [--client-name codex]
 The process writes one `hello` frame, then waits for an `initialize` request on stdin:
 
 ```json
-{"protocolVersion":"1.0","requestId":"init-1","type":"initialize","payload":{"projectId":"<project-id>","client":{"name":"my-agent"},"observationPreset":"compact"}}
+{"protocolVersion":"1.1","requestId":"init-1","type":"initialize","payload":{"projectId":"<project-id>","client":{"name":"my-agent"},"observationPreset":"compact"}}
 ```
 
 Before readiness the client hydrates the current authenticated account profile. Canvas Operations use
@@ -315,17 +331,25 @@ Node hierarchy operations, and the Stage 3 Core Node creative loop. Note operati
 `createGenerationTarget`, the compatible non-text `createMediaTarget`, `planGeneration`,
 `importExternalMedia`, `uploadMedia`, `editGenerationDraft`,
 `addVisualReference`, `removeVisualReference`, `startGeneration`, `getWorkflowRun`, and
-`waitWorkflowRun`. Capability detail is discoverable through `capabilities.detail`; callers should
-use it instead of hard-coding input schemas. Workflow Definitions are available through
-`workflowDefinitions.summary` and `workflowDefinition.detail` queries. Summary discovery, default
-Drafts, planning, and generation start use only Definitions available to the authenticated account.
-Detail may retain an unavailable historical Definition for diagnosis with
-`availableForAccount: false` and an `accessReason`.
+`waitWorkflowRun`. Capability detail is discoverable through
+`capabilities.detail --operation-name <operation-name>`; callers should select only the Operation
+they plan to invoke instead of loading every schema or hard-coding inputs. Workflow Definitions are
+available through `workflowDefinitions.summary` and `workflowDefinition.detail` queries.
+`workflowDefinitions.summary` always returns a compact paginated catalog with a default page size of
+10, target counts, and an opaque next cursor; use `--workflow-target`, `--page-size`, and `--cursor`
+to narrow or continue it. Summary discovery, default Drafts, planning, and generation start use only
+Definitions available to the authenticated account. Detail may retain an unavailable historical
+Definition for diagnosis with `availableForAccount: false` and an `accessReason`.
 
 Workflow tags describe classification, compatibility, access, and rollout rather than price.
 `available:free` means a free-tier account may select the Workflow; it does not mean zero-credit
 generation. Credit claims must come from planning/start estimates or terminal usage records.
 
+`getCoreNode` requires a non-empty unique `coreNodeIds` batch and returns `coreNodes` in the same
+order. If any requested Core Node does not exist, the whole read fails instead of returning an
+ambiguous partial result. The CLI adapter uses the backend's batch endpoint and transparently chunks
+large requests.
+
 Before editing a Draft, an agent can call the read-only `planGeneration` Operation for an existing
 generation target. It recommends a Definition from the target and resolved generation-reference modalities,
 constructs configuration defaults, validates required inputs, and returns compact alternatives plus
@@ -334,15 +358,18 @@ field metadata, including dynamic enum options. Planning never creates a Core No
 Canvas; returned Operations still execute independently and stop at the first failure.
 
 Generation references always identify visible Canvas placements. Public planning and
-`addVisualReference` accept only a View Node ID. If desired content exists only as a Core Node, call
+`addVisualReference` accept only View Node IDs. `addVisualReference` requires a non-empty unique
+`referenceViewNodeIds` batch; `removeVisualReference` requires a non-empty unique `referenceIds`
+batch. Both Operations validate the complete batch before one atomic Draft write, so a failure never
+leaves a partial batch. If desired content exists only as a Core Node, call
 `placeCoreNode` first, wait for its successful Receipt, and reference the returned View Node. This
 preserves the same visible inferred connection as Web and avoids guessing when one Core Node has
 multiple Canvas placements. Manual Text Resources are valid prompt references even though they do
 not have a Core Node before generation starts. Their View Node binding remains in the launch history
 for Web lineage and inferred-edge rendering; estimation uses the current text and materialization
 creates the Text Core Node only after the estimate succeeds. The published operation names
-`addVisualReference` and `removeVisualReference` are retained for compatibility and also carry these
-planned Text bindings.
+`addVisualReference` and `removeVisualReference` cover these planned Text bindings as well as image
+and video bindings.
 
 `insertPromptReference` additionally places the platform-owned At token at `start`, `end`, or
 before/after an exact text anchor such as
@@ -351,7 +378,7 @@ only for a unique anchor. Missing or ambiguous anchors fail without writing. Cal
 At syntax, binding IDs, or slot indexes.
 
 ```json
-{"protocolVersion":"1.0","requestId":"plan-1","type":"operation","payload":{"name":"planGeneration","input":{"targetViewNodeId":"<target-id>","prompt":"A quiet observatory","references":[{"viewNodeId":"<reference-id>"}],"detail":"detail"}}}
+{"protocolVersion":"1.1","requestId":"plan-1","type":"operation","payload":{"name":"planGeneration","input":{"targetViewNodeId":"<target-id>","prompt":"A quiet observatory","references":[{"viewNodeId":"<reference-id>"}],"detail":"detail"}}}
 ```
 
 `editNoteContent`, `setNoteColor`, `editTextContent`, `renameViewNode`, and `resizeViewNodes` match
@@ -370,41 +397,41 @@ is scoped to siblings with the same parent. Decoration, Asset, and all World tar
 Example write:
 
 ```json
-{"protocolVersion":"1.0","requestId":"create-1","type":"operation","payload":{"name":"createNote","input":{"text":"idea","position":{"x":160,"y":160}}}}
+{"protocolVersion":"1.1","requestId":"create-1","type":"operation","payload":{"name":"createNote","input":{"text":"idea","position":{"x":160,"y":160}}}}
 ```
 
 Example Stage 2 edits:
 
 ```json
-{"protocolVersion":"1.0","requestId":"edit-1","type":"operation","payload":{"name":"editNoteContent","input":{"viewNodeId":"view_node_1","text":"revised idea"}}}
-{"protocolVersion":"1.0","requestId":"color-1","type":"operation","payload":{"name":"setNoteColor","input":{"viewNodeId":"view_node_1","color":"purple"}}}
-{"protocolVersion":"1.0","requestId":"text-1","type":"operation","payload":{"name":"createTextNode","input":{"text":"A manual Text Resource","name":"Draft copy","position":{"x":520,"y":160}}}}}
-{"protocolVersion":"1.0","requestId":"resize-1","type":"operation","payload":{"name":"resizeViewNodes","input":{"resizes":[{"viewNodeId":"view_node_1","size":{"width":420,"height":360}}]}}}
-{"protocolVersion":"1.0","requestId":"duplicate-1","type":"operation","payload":{"name":"duplicateViewNodes","input":{"viewNodeIds":["view_node_1"]}}}
+{"protocolVersion":"1.1","requestId":"edit-1","type":"operation","payload":{"name":"editNoteContent","input":{"viewNodeId":"view_node_1","text":"revised idea"}}}
+{"protocolVersion":"1.1","requestId":"color-1","type":"operation","payload":{"name":"setNoteColor","input":{"viewNodeId":"view_node_1","color":"purple"}}}
+{"protocolVersion":"1.1","requestId":"text-1","type":"operation","payload":{"name":"createTextNode","input":{"text":"A manual Text Resource","name":"Draft copy","position":{"x":520,"y":160}}}}}
+{"protocolVersion":"1.1","requestId":"resize-1","type":"operation","payload":{"name":"resizeViewNodes","input":{"resizes":[{"viewNodeId":"view_node_1","size":{"width":420,"height":360}}]}}}
+{"protocolVersion":"1.1","requestId":"duplicate-1","type":"operation","payload":{"name":"duplicateViewNodes","input":{"viewNodeIds":["view_node_1"]}}}
 ```
 
 Example hierarchy sequence (each successful write is one independent undoable interaction):
 
 ```json
-{"protocolVersion":"1.0","requestId":"group-1","type":"operation","payload":{"name":"groupViewNodes","input":{"viewNodeIds":["view_node_1","view_node_2"],"name":"References"}}}
-{"protocolVersion":"1.0","requestId":"reparent-1","type":"operation","payload":{"name":"moveViewNodes","input":{"moves":[{"id":"view_node_3","position":{"x":640,"y":360},"targetParentId":"<group-id>"}]}}}
-{"protocolVersion":"1.0","requestId":"front-1","type":"operation","payload":{"name":"updateViewNodeStacking","input":{"viewNodeId":"view_node_3","direction":"front"}}}
-{"protocolVersion":"1.0","requestId":"ungroup-1","type":"operation","payload":{"name":"ungroupViewNode","input":{"groupViewNodeId":"<group-id>"}}}
+{"protocolVersion":"1.1","requestId":"group-1","type":"operation","payload":{"name":"groupViewNodes","input":{"viewNodeIds":["view_node_1","view_node_2"],"name":"References"}}}
+{"protocolVersion":"1.1","requestId":"reparent-1","type":"operation","payload":{"name":"moveViewNodes","input":{"moves":[{"id":"view_node_3","position":{"x":640,"y":360},"targetParentId":"<group-id>"}]}}}
+{"protocolVersion":"1.1","requestId":"front-1","type":"operation","payload":{"name":"updateViewNodeStacking","input":{"viewNodeId":"view_node_3","direction":"front"}}}
+{"protocolVersion":"1.1","requestId":"ungroup-1","type":"operation","payload":{"name":"ungroupViewNode","input":{"groupViewNodeId":"<group-id>"}}}
 ```
 
 Example Stage 3 generation sequence (each line is a separate ordered interaction):
 
 ```json
-{"protocolVersion":"1.0","requestId":"target-1","type":"operation","payload":{"name":"createGenerationTarget","input":{"contentType":"image"}}}
-{"protocolVersion":"1.0","requestId":"draft-1","type":"operation","payload":{"name":"editGenerationDraft","input":{"viewNodeId":"<target-id>","definitionId":"<definition-id>","prompt":"A quiet observatory","config":{"aspect_ratio":"16:9"}}}}
-{"protocolVersion":"1.0","requestId":"start-1","type":"operation","payload":{"name":"startGeneration","input":{"viewNodeId":"<target-id>"}}}
-{"protocolVersion":"1.0","requestId":"wait-1","type":"operation","payload":{"name":"waitWorkflowRun","input":{"workflowRunId":"<run-id>"},"timeoutMs":120000}}
+{"protocolVersion":"1.1","requestId":"target-1","type":"operation","payload":{"name":"createGenerationTarget","input":{"contentType":"image"}}}
+{"protocolVersion":"1.1","requestId":"draft-1","type":"operation","payload":{"name":"editGenerationDraft","input":{"viewNodeId":"<target-id>","definitionId":"<definition-id>","prompt":"A quiet observatory","config":{"aspect_ratio":"16:9"}}}}
+{"protocolVersion":"1.1","requestId":"start-1","type":"operation","payload":{"name":"startGeneration","input":{"viewNodeId":"<target-id>"}}}
+{"protocolVersion":"1.1","requestId":"wait-1","type":"operation","payload":{"name":"waitWorkflowRun","input":{"workflowRunId":"<run-id>"},"timeoutMs":120000}}
 ```
 
 Example public media URL import:
 
 ```json
-{"protocolVersion":"1.0","requestId":"import-1","type":"operation","payload":{"name":"importExternalMedia","input":{"contentType":"image","idempotencyKey":"reference-image-1","url":"https://example.com/reference.png","name":"Reference image","position":{"x":640,"y":160}}}}
+{"protocolVersion":"1.1","requestId":"import-1","type":"operation","payload":{"name":"importExternalMedia","input":{"contentType":"image","idempotencyKey":"reference-image-1","url":"https://example.com/reference.png","name":"Reference image","position":{"x":640,"y":160}}}}
 ```
 
 `idempotencyKey` is required. Repeating the same normalized input returns the existing View Node and
@@ -459,7 +486,7 @@ from TypeScript source:
    Project, Session, persistent Canvas, one-shot, upload, and download entry points; and `az8 guide`
    plus its JSON form work without credentials or network access.
 2. With no credential, an authenticated command fails without connecting and without printing a
-   token. With the test token, `projects create` returns a new Project owned by the authenticated
+   token. With the acceptance credential, `projects create` returns a new Project owned by the authenticated
    account.
 3. A daemon-backed Session opens, becomes current, accepts a summary query and one semantic write,
    reports healthy status, delivers an interested external change through `watch`, returns `idle`
@@ -472,7 +499,7 @@ from TypeScript source:
 6. Upload one small local media file, confirm immediate detail resolution to its Core Node, replay
    the same idempotency key without another transfer, and download the resolved media to a fresh
    destination whose SHA-256 is reported.
-7. Run repository `pnpm verify`, retain the tarball SHA-512, and record the tested environment. Never
-   perform these acceptance writes against production.
+7. Run repository `pnpm verify`, retain the tarball SHA-512, and record the internal acceptance
+   target. Follow the repository-only release instructions for that target.
 
 Release and rollback commands are in `RELEASE.md`; package changes are in `CHANGELOG.md`.