@everfir/az8-cli 0.2.0 → 0.3.0-preview.1

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 All notable AZ8 CLI changes are recorded here. The CLI package has its own linear version sequence;
 it does not inherit the Web application or monorepo root version.
 
+## Unreleased
+
+## 0.3.0-preview.1 - 2026-07-23
+
+### Added
+
+- Manual Text Resources through `createTextNode` and `editTextContent`, generated Text targets
+  through `createGenerationTarget`, and Web-compatible Note accents through `setNoteColor`.
+- Daemon-backed Agent Collaboration Sessions through `az8 session`, with one isolated local daemon
+  per Session, current-context discovery, retained authenticated Canvas lifecycle, semantic
+  Operations and queries, Interests, bounded Watch delivery, and explicit close.
+- A single semantic collaboration Watch for Canvas, Workflow, and Session facts, with bounded recent
+  history, pending continuity inspection, at-least-once stdout delivery, and explicit
+  resynchronization after journal loss.
+
+### Changed
+
+- New generation references accept only visible Canvas View Node identities. Content available only
+  as a Core Node must first be placed with `placeCoreNode`, preserving Web's inferred connection
+  lines and preventing ambiguous placement selection.
+- Agent authoring now defaults to daemon-backed Sessions. Persistent stdio remains the lower-level
+  carrier, while one-shot remains limited to isolated reads, standalone transfers, explicit caller
+  choice, or hosts that cannot retain a collaborative client.
+- Numeric Workflow configuration enums normalize transport string values back to their declared
+  numeric domain before planning validation, matching Web behavior.
+
+### Safety and compatibility
+
+- Tokens remain outside command arguments, daemon descriptors, and the private daemon protocol.
+- Session writes remain serialized and never retry automatically. Queries wait behind executing
+  writes; Watch collection remains independent.
+- The initial local daemon transport supports macOS and Linux. Windows remains explicitly
+  unsupported until the same private Session carrier is hosted through a named pipe.
+
 ## 0.2.0 - 2026-07-22
 
 First stable semantic Project Canvas client for agents.
@@ -14,6 +48,15 @@ First stable semantic Project Canvas client for agents.
   media upload/download.
 - A runtime-discoverable built-in agent Skill covering platform concepts, capability discovery,
   persistent request/process lifecycle, generation sequencing, recovery, and prohibited bypasses.
+- Commander 15 command routing and generated help, with Zod 4 schemas for typed option and
+  cross-option validation.
+
+### Changed
+
+- Source is grouped into `src/cli`, `src/commands`, `src/canvas`, `src/media`, `src/integrations`,
+  `src/guide`, `src/schemas`, `src/errors`, and `src/utils`; tests remain colocated and domain
+  modules remain framework-independent.
+- The CLI and repository development contract now require Node.js 22.12 or newer.
 
 ### Stability contract
 

package/README.md

@@ -5,7 +5,8 @@ and does not expose raw backend, Yjs, or document mutation commands.
 
 ## Install
 
-AZ8 CLI requires Node.js 20 or newer. Install the stable channel from the configured npm registry:
+AZ8 CLI requires Node.js 22.12 or newer. Install the stable channel from the configured npm
+registry:
 
 ```bash
 npm install --global @everfir/az8-cli
@@ -14,10 +15,10 @@ az8 help
 az8 guide
 ```
 
-For a supplied release artifact, install the exact immutable tarball instead:
+For a supplied preview artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.2.0.tgz
+npm install --global ./everfir-az8-cli-0.3.0-preview.1.tgz
 az8 --version
 ```
 
@@ -61,6 +62,29 @@ An explicit file is selected by path, for example
 users to paste credential contents; verify authentication with a bounded `projects list` read.
 Tokens must not be passed through argv or stdio protocol payloads.
 
+## CLI architecture
+
+The executable uses Commander for the command tree and generated help, and Zod as the typed option
+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/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
+  protocol.
+- `src/media/` owns safe local upload and download behavior.
+- `src/integrations/` adapts AZ8 backend APIs to the account, Project, Project Content, Foundation
+  Data, Workflow, and snapshot ports.
+- `src/guide/` loads and renders the packaged agent Skill.
+- `src/schemas/` owns parsed option contracts and cross-option validation.
+- `src/errors/` maps validation failures to stable CLI and Canvas error codes.
+- `src/utils/` contains shared output and Commander option adapters.
+- `src/index.ts` and `src/main.ts` remain the programmatic and executable entry points.
+
+Canvas, media, guide, and integration modules do not depend on Commander or Zod.
+
 ## Project Management
 
 ```bash
@@ -77,23 +101,52 @@ indeterminate.
 ## First agent loop
 
 A new agent needs only the installed package, a token, and this document. Start by creating its own
-Project and retaining the returned `project.id`:
+Project, then open one daemon-backed Agent Collaboration Session:
 
 ```bash
 az8 projects create --name "Agent preview workspace"
-az8 canvas query <project-id> capabilities.summary
-printf '%s\n' '{"text":"Release smoke note","position":{"x":160,"y":160}}' \
-  | az8 canvas operation <project-id> createNote \
-      --input-stdin --request-id preview-note-1
+az8 session open <project-id> --environment test
+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}}'
+az8 session query canvas.summary
+```
+
+The Session remains selected for the current canonical working directory, so subsequent commands do
+not repeat its ID. Use `session current`, `list`, and `status` rather than guessing which Project or
+daemon is active. Configure semantic Interests and block on one Watch call when collaboration
+updates matter:
+
+```bash
+az8 session interests patch \
+  --input-json '{"upsert":[{"key":"canvas-ambient","patch":{"kind":"canvas"}},{"key":"workflow-terminal","patch":{"kind":"workflow"}}]}'
+az8 session watch --timeout-ms 30000
+az8 session close
 ```
 
-For a long-lived collaborative context, start `az8 canvas open <project-id> --write --format ndjson`,
-read its `hello` frame, send the documented `initialize` request, and wait for `ready` before sending
-queries or Operations. Keep the process and stdin/stdout pipes alive to preserve awareness, local
-History, Receipts, observations, and request replay.
+`watch` returning `idle` is a successful empty observation window, not a connection error. Exactly
+one caller may wait on a Session. The daemon retains the authenticated connection and collaboration
+state between short CLI invocations, but it does not wake or restart an Agent that has exited.
+
+For a manual human–Agent interaction latency check, have the Agent report that it is ready, start
+one 60-second Watch, and only then make one recognizable Canvas change from Web:
 
-For generation, create an image target and call `planGeneration` with the returned View Node and a
-prompt. Execute its returned `plan.operations` in order, stopping after the first failure. A
+```bash
+az8 session interests patch \
+  --input-json '{"upsert":[{"key":"latency-check","patch":{"kind":"canvas","filter":{"includeOwn":false}}}]}'
+az8 session watch --timeout-ms 60000
+```
+
+The Agent should acknowledge the returned semantic change immediately and then wait again. Record
+the human-observed time from completing the Web interaction to seeing the Agent response.
+`result.timing.waitedMs` is how long the blocking call waited, while each change's `quietForMs` is
+the CLI's local observation-to-delivery delay; neither includes speech recognition or the Agent
+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
+`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.
@@ -108,9 +161,9 @@ the agent can verify identities, byte count, MIME, and SHA-256.
 One-shot commands open a real Canvas client, complete synchronization and hydration, invoke the same
 query or Operation used by the persistent client, and close after the result is authoritative:
 
-Persistent stdio is the default for any Canvas authoring task, including a plan with only one write.
-Use this wrapper only for an isolated read, standalone transfer, explicit one-shot request, or a host
-that cannot retain a child process and write later NDJSON to stdin.
+Daemon-backed Sessions are the default for any Canvas authoring task, including a plan with only one
+write. Use this wrapper only for an isolated read, standalone transfer, explicit one-shot request,
+or a host that cannot run a Session daemon or retain a child process.
 
 ```bash
 az8 canvas query <project-id> canvas.summary
@@ -212,11 +265,13 @@ source, HTTP 4xx, or local-path failure; exit `2` is a retryable connection, HTT
 integrity, or timeout failure; exit `130` is caller cancellation. Downloads are never automatically
 retried. After any non-success, the agent must decide whether a new invocation is safe.
 
-## Persistent Canvas client
+## Lower-level persistent stdio client
 
-This is the default mode whenever a task may perform any Canvas write. Open it before the first
-Canvas query, keep capability discovery and all ordered Operations in the same lifecycle, and shut
-it down only after the authoring task is complete.
+This is the lower-level carrier for a host that deliberately owns and continuously drains one child
+process. Ordinary Agents should use `az8 session`, whose private daemon retains the same Canvas
+lifecycle across short commands. When using stdio directly, open it before the first Canvas query,
+keep capability discovery and all ordered Operations in the same lifecycle, and shut it down only
+after the authoring task is complete.
 
 ```bash
 az8 canvas open <project-id> --write --format ndjson [--client-name codex]
@@ -237,28 +292,45 @@ rename the persisted author. The CLI publishes its Attention Cursor but delibera
 bounds. Project owner metadata is likewise never treated as the current actor on shared Projects.
 
 After `ready`, requests use `query`, `configureObservations`, `operation`, `reconnect`, or `shutdown`.
-The public authoring surface includes the note lifecycle, non-World View Node hierarchy operations,
-and the Stage 3 Core Node creative loop. Hierarchy operations are `groupViewNodes`,
+The public authoring surface includes distinct Note and Text Resource lifecycles, non-World View
+Node hierarchy operations, and the Stage 3 Core Node creative loop. Note operations include
+`createNote`, `editNoteContent`, and `setNoteColor`; manual Text Resource operations are
+`createTextNode` and `editTextContent`. Hierarchy operations are `groupViewNodes`,
 `ungroupViewNode`, `moveViewNodes` with an optional `targetParentId`, and
 `updateViewNodeStacking`. Core Node operations are `getCoreNode`, `placeCoreNode`,
-`createMediaTarget`, `planGeneration`, `importExternalMedia`, `uploadMedia`, `editGenerationDraft`,
+`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.
 
 Before editing a Draft, an agent can call the read-only `planGeneration` Operation for an existing
-media target. It recommends a Definition from the target and resolved Visual Reference modalities,
+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
 an ordered semantic Operation sequence. Use `detail: "detail"` to include slot and configuration
 field metadata, including dynamic enum options. Planning never creates a Core Node or changes the
 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
+`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.
+
 ```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"}}}
 ```
 
-`editNoteContent`, `renameViewNode`, and `resizeViewNodes` match Web's silent History policy.
+`editNoteContent`, `setNoteColor`, `editTextContent`, `renameViewNode`, and `resizeViewNodes` match
+Web's silent History policy. Note colors are limited to `blue`, `orange`, `red`, `gold`, `purple`,
+and `green`. A manual Text Resource is `type: "resource"`, `contentType: "text"`; it must not be
+approximated with a Note.
 `duplicateViewNodes` and `removeViewNodes` are undoable. Removal atomically cleans Draft references
 from surviving nodes. Duplication supports notes and non-World resource nodes; resource copies retain
 the currently displayed Project Content output without cloning a Core Node or creating Project
@@ -278,6 +350,8 @@ 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"]}}}
 ```
@@ -294,7 +368,7 @@ Example hierarchy sequence (each successful write is one independent undoable in
 Example Stage 3 generation sequence (each line is a separate ordered interaction):
 
 ```json
-{"protocolVersion":"1.0","requestId":"target-1","type":"operation","payload":{"name":"createMediaTarget","input":{"contentType":"image"}}}
+{"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}}
@@ -355,20 +429,23 @@ Before distributing a release tarball, verify all of the following from its clea
 from TypeScript source:
 
 1. `az8 --version` matches the immutable package version; `az8 help` lists the built-in guide,
-   Project, persistent Canvas, one-shot, upload, and download entry points; and `az8 guide` plus its
-   JSON form work without credentials or network access.
+   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
    account.
-3. Persistent stdio reaches `ready`, accepts a summary query, creates a note whose Receipt records
+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`
+   for an empty bounded wait, and closes without leaving a live daemon or current binding.
+4. Persistent stdio reaches `ready`, accepts a summary query, creates a note whose Receipt records
    the authenticated Actor, and completes an ordered shutdown.
-4. One-shot `createMediaTarget` plus `planGeneration` returns a ready semantic sequence; executing
-   that sequence starts one Workflow Run, and `waitWorkflowRun` or later `getWorkflowRun` observes
-   its authoritative state.
-5. Upload one small local media file, confirm immediate detail resolution to its Core Node, replay
+5. One-shot `createGenerationTarget` plus `planGeneration` returns a ready semantic sequence with
+   only visible View Node references; executing that sequence starts one Workflow Run, and
+   `waitWorkflowRun` or later `getWorkflowRun` observes its authoritative state.
+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.
-6. Run repository `pnpm verify`, retain the tarball SHA-512, and record the tested environment. Never
+7. Run repository `pnpm verify`, retain the tarball SHA-512, and record the tested environment. Never
    perform these acceptance writes against production.
 
 Release and rollback commands are in `RELEASE.md`; package changes are in `CHANGELOG.md`.

package/RELEASE.md

@@ -19,7 +19,8 @@ preserves the verified tarball and clean installation under `tmp/az8-cli-release
 acceptance. Never bundle against pre-existing workspace `dist/` output.
 
 Run the live smoke only against the test environment. It creates one Project unless `--project-id`
-reuses an explicit test Project, starts one image generation, and uploads one tiny PNG:
+reuses an explicit test Project, starts one visible-reference image generation, and uploads one
+generated 512×512 PNG:
 
 ```bash
 node apps/az8-cli/scripts/smoke-test.js \
@@ -41,18 +42,32 @@ node apps/az8-cli/scripts/smoke-test.js \
   --require-generation-estimate
 ```
 
+When a release changes Text generation, add one bounded Text Workflow to the smoke with a known
+test Definition. This is additive to the image acceptance unless the image path is being diagnosed
+separately:
+
+```bash
+node apps/az8-cli/scripts/smoke-test.js \
+  --bin ./tmp/az8-cli-release/install/node_modules/.bin/az8 \
+  --env-file ./.env.local \
+  --text-generation-definition-id <test-text-definition-id>
+```
+
 Before publishing, also run the test-environment acceptance checklist in the packaged README and the
 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:
+
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0.tgz --tag latest
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.3.0-preview.1.tgz --tag preview
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 
-Publish only the exact retained tarball whose SHA-512 appears in the stable release verification
-record. Do not publish from an unverified source directory. If the obsolete misspelled `prewview`
-tag still exists after stable publication, remove that tag without unpublishing its immutable
+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:
 
 ```bash