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

package/CHANGELOG.md

@@ -5,6 +5,75 @@ 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
+
+- Account-aware Workflow discovery and selection, using the same free-account eligibility rule as
+  Web while keeping unavailable historical Definitions inspectable in detail.
+- Web-equivalent default generation Drafts and private local Workflow preferences scoped by
+  environment, authenticated account, and output content type.
+- Truthful terminal Workflow target identity derived from retained launch facts or unique Canvas
+  History, with explicit unresolved and ambiguous states when evidence is insufficient.
+- Daemon-backed collaboration Sessions, manual and generated Text Resources, semantic Prompt
+  reference insertion, structured transfer progress, and bounded download recovery.
+
+### Changed
+
+- `createGenerationTarget` initializes an eligible default Draft in the same undoable interaction;
+  prompt-only `editGenerationDraft` uses the same resolver when a historical target has no Draft.
+- Generation plans preserve their effective prompt and configuration when input modality switches
+  to another Workflow Definition and rebuilds the target Draft.
+- Workflow summary, defaults, planning, reference edits, and generation start reject Definitions
+  unavailable to the authenticated account. `available:free` is treated only as free-tier access,
+  never as pricing evidence.
+- Agent guidance prioritizes one foreground `session watch`, early visible targets, authoritative
+  planning, and explicit reconciliation instead of polling, guessed At syntax, or write retries.
+
+### Safety and compatibility
+
+- Public writes remain semantic Operations backed by internal Commands. No Workflow preference,
+  access rule, or Watch enrichment grants a raw Canvas mutation path.
+- Local preferences contain only a Definition id and sanitized scalar config values; they never
+  contain credentials, prompts, media URLs, or Project data.
+- Stable protocol `1.0`, sequential write blocking, no automatic write retry, and explicit
+  generation acceptance/completion boundaries remain unchanged from `0.2.0`.
+
 ## 0.3.0-preview.3 - 2026-07-23
 
 ### Added

package/README.md

@@ -15,10 +15,10 @@ az8 help
 az8 guide
 ```
 
-For a supplied preview artifact, install the exact immutable tarball instead:
+For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.3.0-preview.3.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
@@ -148,14 +166,16 @@ the CLI's local observation-to-delivery delay; neither includes speech recogniti
 host's scheduling time. Repeat only a small bounded sample, keep the Session open between trials,
 and remove the temporary Interest or close the Session afterward.
 
-For generation, create a target with `createGenerationTarget` (including `contentType: "text"`) and
-call `planGeneration` with the returned View Node and a prompt. Execute its returned
+For generation, create a target with `createGenerationTarget` (including `contentType: "text"`).
+Creation initializes an account-eligible default Draft when available and reports
+`draftInitialized`, `definitionId`, and `selectionSource`; it never starts generation. Call
+`planGeneration` with the returned View Node and a prompt. Execute its returned
 `plan.operations` in order, stopping after the first failure. A
 successful `startGeneration` Receipt contains the Workflow Run identity; call `waitWorkflowRun`
 separately when a terminal output is required. Planning and starting are intentionally not one
 transaction. In an active Session, prefer one foreground `session watch`: the system terminal event
-includes Workflow Run, target View Node, and output Core Node identities when supplied by Workflow
-Runtime.
+includes the target View Node only when it can be mapped uniquely from authoritative launch or
+Canvas History facts; unresolved or ambiguous mappings are reported rather than guessed.
 
 For media transfer, `canvas upload` places a verified local image/video/audio file through the
 server-owned Core Node path. After detail query resolves the target's `resolvedCoreNodeId`, `canvas
@@ -292,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
@@ -313,9 +333,24 @@ 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.
+`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,
@@ -325,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
@@ -342,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
@@ -361,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,18 +57,18 @@ 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 a preview candidate, publish the exact retained artifact to the preview channel:
+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-preview.3.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.4.0.tgz --tag latest
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 
 Publish only the exact retained tarball whose SHA-512 appears in its release verification record.
-Do not publish from an unverified source directory. A later stable promotion uses a new stable
-version and `--tag latest`; it never retags or republishes this immutable preview artifact. If the
-obsolete misspelled `prewview` tag still exists, remove that tag without unpublishing its immutable
-version:
+Do not publish from an unverified source directory, retag a preview artifact as stable, or rebuild
+after acceptance. If the obsolete misspelled `prewview` tag still exists, remove that tag without
+unpublishing its immutable version:
 
 ```bash
 npm dist-tag rm @everfir/az8-cli prewview