@everfir/az8-cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ it does not inherit the Web application or monorepo root version.
 
 ## Unreleased
 
+## 0.4.0 - 2026-07-24
+
+### Added
+
+- Browser-assisted local authentication through `az8 login`, account inspection through
+  `az8 whoami`, and local sign-out through `az8 logout`.
+- Environment-isolated local credential storage with atomic writes, restrictive filesystem
+  permissions, authenticated account metadata, and automatic persistence of rotated tokens.
+- A standalone Studio authorization page that requires an explicit approve or deny decision and
+  never exposes the delivered credential to browser JavaScript.
+
+### Changed
+
+- Capability discovery can select one exact Operation schema with `--operation-name`; Workflow
+  Definition discovery always uses compact target counts, target filtering, and opaque cursor
+  pagination.
+- The built-in Skill uses focused capability detail and bounded Workflow catalog pages instead of
+  loading full catalogs into agent context.
+- Persistent Canvas protocol `1.1` removes selector-free capability detail and full Workflow
+  catalog responses. Callers must select one Operation detail and page Workflow summaries.
+- Credential resolution now prefers explicit process and env-file tokens before the local login
+  credential, while reporting which non-secret source is active.
+- Daemon Session descriptors retain only the credential source and account identity so logout can
+  close affected local-token Sessions without recording a secret.
+- Agent onboarding recommends browser login by default and explains the at-most-once exchange
+  failure boundary: an ambiguous exchange must begin a new authorization rather than retry.
+
+### Safety and compatibility
+
+- Browser authorization uses PKCE, a short-lived user code, explicit CSRF intent, and at-most-once
+  token delivery. A consumed exchange is never replayed after a lost response or local save
+  failure.
+- `logout` clears only local CLI state; it does not promise server-side revocation. Existing
+  environment and env-file provisioning remains supported and is never rewritten by the CLI.
+
 ## 0.3.0 - 2026-07-23
 
 ### Added

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.4.0.tgz
 az8 --version
 ```
 
@@ -40,15 +40,30 @@ 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 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 --environment test
+az8 whoami --environment test
+az8 logout --environment test
+```
+
+`login` opens `studio.az8.studio` or `studio.az8.art`, 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>
@@ -58,9 +73,10 @@ 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`.
 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.
+`--environment test --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 +85,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,10 +117,11 @@ 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 --environment test
 az8 projects create --name "Agent preview workspace"
 az8 session open <project-id> --environment test
 az8 session query capabilities.summary
@@ -294,7 +312,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 +333,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 +360,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 +380,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 +399,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

package/RELEASE.md

@@ -57,11 +57,11 @@ Before publishing, also run the test-environment acceptance checklist in the pac
 repository-wide `pnpm verify`. Publishing is an external action and requires explicit operator
 authorization:
 
-For the `0.3.0` stable candidate, publish the exact retained artifact to the stable channel only
+For the `0.4.0` stable candidate, publish the exact retained artifact to the stable channel only
 after its test-environment acceptance succeeds:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.3.0.tgz --tag latest
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.4.0.tgz --tag latest
 npm view @everfir/az8-cli dist-tags versions --json
 ```