@everfir/az8-cli 0.2.0-preview.5 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 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.
 
+## 0.2.0 - 2026-07-22
+
+First stable semantic Project Canvas client for agents.
+
+### Added
+
+- Project management, persistent NDJSON Canvas collaboration, one-shot compatibility wrappers,
+  semantic note and hierarchy authoring, Core Node generation, Workflow observation, and safe local
+  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.
+
+### Stability contract
+
+- Public Canvas writes remain available only through semantic Operations and internal Commands;
+  callers cannot write raw backend, Yjs, Core Node, or Project Content data.
+- Protocol `1.0`, ordered request/Receipt behavior, authenticated presence, no automatic write retry,
+  and explicit deferred scopes form the initial stable compatibility boundary.
+- 3D World, Asset aggregate management, automatic layout, media replacement, and batch upload remain
+  intentionally deferred rather than partially exposed.
+
 ## 0.2.0-preview.5 - 2026-07-22
 
 ### Changed

package/README.md

@@ -3,12 +3,12 @@
 AZ8 CLI is a semantic Project Canvas client for agents. It does not import Web implementation code
 and does not expose raw backend, Yjs, or document mutation commands.
 
-## Install the internal preview
+## Install
 
-AZ8 CLI requires Node.js 20 or newer. Install the preview channel from the configured npm registry:
+AZ8 CLI requires Node.js 20 or newer. Install the stable channel from the configured npm registry:
 
 ```bash
-npm install --global @everfir/az8-cli@preview
+npm install --global @everfir/az8-cli
 az8 --version
 az8 help
 az8 guide
@@ -17,12 +17,12 @@ az8 guide
 For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.2.0-preview.5.tgz
+npm install --global ./everfir-az8-cli-0.2.0.tgz
 az8 --version
 ```
 
-`az8 --version` must report the version selected for the agent environment. Preview releases do not
-replace npm's `latest` channel. Pin an exact version or tarball for reproducible agent runs.
+`az8 --version` must report the version selected for the agent environment. Pin an exact version or
+tarball for reproducible agent runs.
 
 ## Built-in agent Skill
 
@@ -349,9 +349,9 @@ Every output frame has `protocolVersion`, monotonic `streamSeq`, `type`, `payloa
 after collaboration-server acknowledgement. A timeout or lost acknowledgement is indeterminate,
 moves the Canvas context offline, and requires explicit reconnect and inspection before any retry.
 
-## Preview acceptance checklist
+## Release acceptance checklist
 
-Before distributing a preview tarball, verify all of the following from its clean installation, not
+Before distributing a release tarball, verify all of the following from its clean installation, not
 from TypeScript source:
 
 1. `az8 --version` matches the immutable package version; `az8 help` lists the built-in guide,

package/RELEASE.md

@@ -1,7 +1,7 @@
-# AZ8 CLI preview release
+# AZ8 CLI release
 
-This package is an internal preview. `preview` is the release channel; it must not replace npm's
-`latest` tag until a separate stability decision is made.
+`latest` is the stable release channel. Preview versions remain immutable historical artifacts and
+must not be republished or renamed into a stable version.
 
 ## Release gate
 
@@ -12,9 +12,11 @@ pnpm release:az8-cli
 pnpm release:pack:az8-cli
 ```
 
-The first command runs CLI tests, type checking, builds a real npm tarball, installs that tarball in
-a clean temporary directory, and verifies the installed `az8` executable. The second preserves the
-verified tarball and clean installation under `tmp/az8-cli-release/` for live acceptance.
+The first command rebuilds the CLI's classified workspace dependencies, runs CLI tests and type
+checking, builds a real npm tarball, installs that tarball in a clean temporary directory, and
+verifies the installed `az8` executable. The second repeats the dependency-aware prepack and
+preserves the verified tarball and clean installation under `tmp/az8-cli-release/` for live
+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:
@@ -28,28 +30,45 @@ node apps/az8-cli/scripts/smoke-test.js \
 The smoke report must show authenticated persistent stdio, ordered shutdown, a completed Workflow
 Run whose target resolves its output Core Node, upload replay without another transfer, and matching
 download SHA-256. `--skip-generation` is only for diagnosing unrelated media or transport checks;
-it cannot satisfy full release acceptance.
+it cannot satisfy full release acceptance. When the release changes generation-time projection,
+select a timing-enabled test Definition and require its persisted Web estimate:
+
+```bash
+node apps/az8-cli/scripts/smoke-test.js \
+  --bin ./tmp/az8-cli-release/install/node_modules/.bin/az8 \
+  --env-file ./.env.local \
+  --generation-definition-id <timing-enabled-test-definition-id> \
+  --require-generation-estimate
+```
 
 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:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.5.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0.tgz --tag latest
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 
-Do not pass `--tag latest`. Do not publish from an unverified source directory.
+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
+version:
+
+```bash
+npm dist-tag rm @everfir/az8-cli prewview
+npm view @everfir/az8-cli dist-tags --json
+```
 
 ## Rollback
 
-Published versions are immutable. Rollback moves the `preview` tag to a previously verified version
+Published versions are immutable. Rollback moves `latest` to a previously verified stable version
 instead of unpublishing or overwriting a package:
 
 ```bash
-npm dist-tag add @everfir/az8-cli@<previous-version> preview
+npm dist-tag add @everfir/az8-cli@<previous-stable-version> latest
 npm view @everfir/az8-cli dist-tags --json
-npm install --global @everfir/az8-cli@preview
+npm install --global @everfir/az8-cli
 az8 --version
 ```
 

package/dist/main.js

@@ -13600,10 +13600,7 @@ var HocuspocusProjectCanvasDocumentImplementation = class {
     this.setAwarenessFields({
       cursor: input.cursor,
       updatedAt: Date.now(),
-      view: {
-        kind: "canvas",
-        ...input.selection ? { selection: input.selection } : {}
-      }
+      view: { kind: "canvas" }
     });
   }
   getAwareness() {
@@ -15937,6 +15934,7 @@ var CoreNodeCreativeLoop = class {
         prepared,
         timeoutMs
       });
+      const submittedAt = this.context.now();
       const run = await this.systems.workflowRuntime.startRun({
         definitionId: definition.id,
         expectedCost: estimate.estimatedCost,
@@ -15954,11 +15952,13 @@ var CoreNodeCreativeLoop = class {
         runtime: {
           expectedCost: estimate.estimatedCost,
           expectedDefinitionVersion: estimate.definitionVersion,
+          ...createEstimatedCompletionTimes(estimate, submittedAt),
           instanceIds: [run.id],
           materializedInputs: materialized.materializedInputs,
           originClientId: this.context.clientInstanceId,
-          submittedAt: timestamp
-        }
+          submittedAt
+        },
+        updatedAt: timestamp
       };
       const { creationIntent: _creationIntent, ...data } = asRecord3(target.data);
       const after = {
@@ -16245,6 +16245,28 @@ var CoreNodeCreativeLoop = class {
     };
   }
 };
+function createEstimatedCompletionTimes(estimate, submittedAt) {
+  const ranges = estimate.executionTimeRanges;
+  if (!ranges?.length)
+    return {};
+  let medianSeconds = 0;
+  let maxSeconds = 0;
+  let validRangeCount = 0;
+  for (const range of ranges) {
+    if (!Number.isFinite(range.medianSeconds) || range.medianSeconds < 0 || !Number.isFinite(range.maxSeconds) || range.maxSeconds < 0) {
+      continue;
+    }
+    medianSeconds += range.medianSeconds;
+    maxSeconds += range.maxSeconds;
+    validRangeCount += 1;
+  }
+  if (validRangeCount === 0)
+    return {};
+  return {
+    estimatedMaxCompletionAt: submittedAt + maxSeconds * 1e3,
+    estimatedMedianCompletionAt: submittedAt + medianSeconds * 1e3
+  };
+}
 function attention(viewNodeId, result3) {
   return { attention: { kind: "view-nodes", viewNodeIds: [viewNodeId] }, result: result3 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.2.0-preview.5",
+  "version": "0.2.0",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",
@@ -16,20 +16,21 @@
   "main": "./dist/main.js",
   "publishConfig": {
     "access": "public",
-    "tag": "preview"
+    "tag": "latest"
   },
   "scripts": {
-    "build": "rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
+    "build": "pnpm build:dependencies && rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
+    "build:dependencies": "pnpm --filter @everfir/az8-cli^... build",
     "dev": "tsx src/main.ts",
     "start": "node dist/main.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "biome check .",
     "prepack": "pnpm build",
     "prepublishOnly": "pnpm release:check",
-    "release:check": "pnpm test && pnpm typecheck && node scripts/verify-package.js",
+    "release:check": "pnpm build:dependencies && pnpm test && pnpm typecheck && node scripts/verify-package.js",
     "release:pack": "node scripts/verify-package.js --output-dir ../../tmp/az8-cli-release --keep-install",
     "release:smoke": "node scripts/smoke-test.js",
-    "test": "tsx --tsconfig tsconfig.test.json --test src/**/*.test.ts"
+    "test": "tsx --tsconfig tsconfig.test.json --test src/**/*.test.ts && node --test scripts/*.test.js"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/skills/az8-cli/SKILL.md

@@ -150,6 +150,24 @@ the authenticated user display name first.
 Protocol truth is written to stdout. stderr contains diagnostics only. Unknown optional fields are
 additive; ignore them. Do not treat a process exit code as the result of the last persistent request.
 
+Treat the persistent process lifetime and each request lifetime separately:
+
+- Keep the process running between requests. Decide request completion only from the matching
+  `requestId` and its `requestCompleted` or `requestFailed` frame; never wait for process exit.
+- Treat `requestAccepted` as admission only. For a write, wait for its terminal Receipt before
+  issuing the next query or Operation.
+- Continuously drain and parse stdout, but do not repeatedly poll an idle process merely to make it
+  produce output. No new frame is a normal healthy state when no lifecycle, request, Canvas, or
+  Workflow fact changed.
+- Do not interpret a shell/agent-host read window ending with no output (for example, a 30-second
+  terminal yield) as CLI latency, request timeout, or connection failure. Check request terminal
+  frames and lifecycle/health facts instead.
+- Keep one connected client for related work. Reopening one-shot clients repeatedly pays connection,
+  synchronization, and hydration cost each time and loses local History, Receipts, and presence.
+- Remember that the current persistent protocol processes requests serially. A long
+  `waitWorkflowRun` occupies the request lane until the Run becomes terminal or its observation
+  window ends; submit it only when no other request needs that lane.
+
 Use one-shot only for:
 
 - an isolated read when no Canvas write is planned;
@@ -201,10 +219,15 @@ Generation is an explicit sequence, never one transaction:
    current facts. Stop after the first non-success.
 5. `startGeneration` succeeds when the Workflow Run is accepted and immediate Canvas effects are
    acknowledged. This completes the start interaction; it does not mean generation finished.
-6. Retain the Workflow Run ID. Use `waitWorkflowRun` when waiting is useful, or `getWorkflowRun`
-   later. An observation-window timeout while the authoritative Run remains pending/running is an
-   ordinary read outcome and does not cancel the Run or take a healthy context offline.
-7. On terminal success, query the target detail and resolve its current output Core Node through
+6. Retain the Workflow Run ID. After the successful start Receipt, continue any work that does not
+   require the generated output. Prefer `workflowChanged` observations while the persistent client
+   is active, and use `getWorkflowRun` at a meaningful later checkpoint.
+7. Use `waitWorkflowRun` only when the next step actually requires terminal output and the current
+   request lane can remain dedicated to waiting. Choose one intentional observation window; do not
+   emulate polling with repeated short waits. An observation-window timeout while the authoritative
+   Run remains pending/running is an ordinary read outcome and does not cancel the Run or take a
+   healthy context offline.
+8. On terminal success, query the target detail and resolve its current output Core Node through
    Project Content before downloading or placing it elsewhere.
 
 Workflow Definitions change over time. Query `workflowDefinitions.summary`, then