@everfir/az8-cli 0.4.0 → 0.5.0

package/package.json

@@ -1,14 +1,12 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",
   "files": [
     "dist",
-    "skills",
-    "CHANGELOG.md",
-    "RELEASE.md"
+    "skills"
   ],
   "bin": {
     "az8": "dist/main.js"

package/skills/az8-cli/SKILL.md

@@ -6,7 +6,7 @@ description: Use AZ8 CLI to safely select or create Projects, inspect and author
 # Use AZ8 CLI
 
 Treat `az8` as a semantic AZ8 Studio client, not as a document editor or generic backend client.
-Follow this guide before the first Project Canvas action in a new environment. Query runtime
+Follow this guide before the first Project Canvas action in a new agent host. Query runtime
 capabilities instead of guessing operation names or input shapes.
 
 ## Contract
@@ -14,7 +14,7 @@ capabilities instead of guessing operation names or input shapes.
 - Use only public `az8 projects`, `az8 session`, and `az8 canvas` commands. Never mutate backend
   records, Yjs, Collaborative Document fields, Core Node payloads, or Project Content bindings
   directly.
-- Explicitly select `test` or `production`. Never infer authorization to write production data.
+- Never infer authorization to write outside the user-selected Project and concrete task.
 - Read the relevant Canvas facts before planning a write. Submit one semantic Operation at a time.
 - Treat every accepted write as a blocker: wait for its terminal Receipt before issuing any later
   query or Operation.
@@ -23,7 +23,7 @@ capabilities instead of guessing operation names or input shapes.
 - Never automatically retry a write. Retry only bounded reads when the returned error says doing so
   is safe. An idempotency key does not authorize blind replay.
 - Prefer `az8 login` browser authorization for the current operating-system user. Externally
-  provisioned inherited-environment and env-file credentials remain higher-priority automation
+  provisioned process-environment and env-file credentials remain higher-priority automation
   inputs. Never type, read, copy, print, or return a token through a shell tool call, argv, stdio
   frame, prompt, log, or output.
 
@@ -63,7 +63,7 @@ capabilities instead of guessing operation names or input shapes.
 
 ## Bootstrap
 
-1. Report the canonical working directory and intended environment. Then verify the installed
+1. Report the canonical working directory. Then verify the installed
    client without credentials:
 
    ```bash
@@ -73,24 +73,24 @@ capabilities instead of guessing operation names or input shapes.
 2. Check the active identity without inspecting credential material:
 
    ```bash
-   az8 whoami --environment test
+   az8 whoami
    ```
 
    If no credential is available, invoke browser authorization and ask the user to approve the
    request in the opened AZ8 Studio page:
 
    ```bash
-   az8 login --environment test
+   az8 login
    ```
 
    `login` emits the verification URL and User Code as structured progress while it waits. Do not
    create a polling loop around it. If the browser cannot be opened on the agent host, use
-   `az8 login --environment test --no-open`, give the emitted URL to the user, and keep that one
+   `az8 login --no-open`, give the emitted URL to the user, and keep that one
    command running until it succeeds or fails. Authorization delivery is at-most-once: a lost
    response, cancelled CLI, or failed local save requires a completely new `az8 login`; never retry
    the consumed exchange yourself.
 
-   The CLI stores browser-authorized credentials privately by operating-system user and environment.
+   The CLI stores browser-authorized credentials privately by operating-system user and AZ8 service.
    `az8 logout` removes only that local credential and closes daemon Sessions that depend on it; it
    is not online revocation. Do not log out automatically at task completion.
 
@@ -100,7 +100,6 @@ capabilities instead of guessing operation names or input shapes.
 
    ```dotenv
    AZ8_TOKEN=<operator-provisioned-secret>
-   AZ8_ENVIRONMENT=test
    ```
 
    With no `--env-file`, the CLI searches for `.env.local` from the working directory upward. An
@@ -108,7 +107,7 @@ capabilities instead of guessing operation names or input shapes.
 
    ```bash
    az8 projects list --scope owned --page-size 1 \
-     --environment test --env-file /secure/path/.env.local
+     --env-file /secure/path/.env.local
    ```
 
    Use `az8 whoami` as the credential check. Never verify a token with `cat`, `sed`, `grep`, `env`,
@@ -117,10 +116,10 @@ capabilities instead of guessing operation names or input shapes.
    provisioning workflow. Keep it outside version control with owner-only access.
 
    The inherited process environment overrides env-file values, and env-file values override the
-   locally saved login; `--environment` overrides `AZ8_ENVIRONMENT`. `az8 login` can save a local
+   locally saved login. `az8 login` can save a local
    credential while an external credential remains active, so check the returned `credential.active`
-   field and use `az8 whoami` to confirm the effective Actor. Always pass or provision the intended
-   environment explicitly. Never ask the user to paste a secret into chat.
+   field and use `az8 whoami` to confirm the effective Actor.
+   Never ask the user to paste a secret into chat.
 
 3. Select an existing Project or create a bounded workspace:
 
@@ -136,7 +135,7 @@ capabilities instead of guessing operation names or input shapes.
    daemon-backed Agent Collaboration Session now and retain it through the authoring task:
 
    ```bash
-   az8 session open <project-id> --environment test
+   az8 session open <project-id>
    az8 session query capabilities.summary
    az8 session query capabilities.detail --operation-name <operation-name>
    az8 session query canvas.summary
@@ -146,8 +145,8 @@ capabilities instead of guessing operation names or input shapes.
    Session merely to retain unused state:
 
    ```bash
-   az8 canvas query <project-id> capabilities.summary --environment test
-   az8 canvas query <project-id> canvas.summary --environment test
+   az8 canvas query <project-id> capabilities.summary
+   az8 canvas query <project-id> canvas.summary
    ```
 
    `capabilities.summary` is the short menu. Select one Operation with `--operation-name` when
@@ -176,7 +175,7 @@ connection, Awareness, History, Receipts, Interests, and Watch Journal across or
 calls:
 
 ```bash
-az8 session open <project-id> --environment test
+az8 session open <project-id>
 az8 session current
 az8 session status
 ```
@@ -490,14 +489,13 @@ Never:
 - use one-shot as if it retained History, Receipts, replay state, observations, or presence;
 - attempt Asset membership, arbitrary Core Node creation, 3D World editing, unsupported
   Decoration, alignment, or automatic layout through lower-level access;
-- write production unless the user explicitly selected and authorized production for the concrete
-  action.
+- write Project data unless the user explicitly authorized the concrete action.
 
 ## Completion
 
 Before reporting a task complete, verify all applicable facts:
 
-- The intended environment, Project ID, authenticated role, and installed CLI version are known.
+- The configured AZ8 service, Project ID, authenticated role, and installed CLI version are known.
 - Runtime capability discovery—not memory—authorized every Operation and input schema used.
 - Every write has its own request ID, terminal Receipt, and sequential position; no write was
   automatically retried.

package/CHANGELOG.md

@@ -1,260 +0,0 @@
-# Changelog
-
-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.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
-
-- Every collaborative Session receives discoverable Workflow terminal events by default, including
-  the Workflow Run, target View Node, and output Core Node identities.
-- Prompt references can be inserted before or after an exact text occurrence without exposing raw
-  Canvas data.
-- Media uploads report structured stage, byte, and percentage progress across one-shot, persistent
-  stdio, and daemon-backed Session transports.
-
-### Changed
-
-- Media downloads use bounded read-only retries under one caller deadline, clean partial files, and
-  return structured, credential-safe transport diagnostics when recovery fails.
-- The built-in agent Skill prioritizes a single foreground `session watch` call, warns against
-  background polling loops, and documents terminal reconciliation and exact Prompt placement.
-
-### Safety and compatibility
-
-- User Workflow Interests remain additive and cannot disable the system terminal stream.
-- Download retries never extend the caller deadline or apply to definitive verification failures.
-- Upload progress is provisional observability and cannot change the semantic Operation result.
-
-## 0.3.0-preview.2 - 2026-07-23
-
-### Added
-
-- Cursor-only Awareness acknowledgement after a remote Canvas Watch delivery has been flushed and
-  internally acknowledged.
-- Advisory `data.createdByCli` provenance on every View Node created through the CLI.
-
-### Changed
-
-- CLI-created Notes retain the authenticated Actor id and display the current client suffix in
-  their visible creator label.
-- Ordinary Resource View Nodes no longer receive invented generic creator metadata.
-- The built-in agent Skill recommends early visible generation targets and empty Text Resources
-  when artifact type and placement are already unambiguous.
-
-### Safety and compatibility
-
-- Delivery Awareness never responds to the CLI's own changes, never publishes Selection, and does
-  not represent understanding or completion.
-- Editing an existing View Node preserves its creation provenance; duplicating stamps the new node
-  with the current client suffix.
-
-## 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.
-
-### 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.
-- 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
-
-- 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
-
-- Canvas awareness names now preserve the authenticated user's Web-equivalent display name first
-  and append a CLI-owned parenthesized client suffix, defaulting to `(cli)`.
-- `--client-name <suffix>` may override the client suffix for persistent and one-shot lifecycles,
-  but caller-provided parentheses are rejected so presence cannot obscure the name boundary.
-- CLI attention awareness now publishes only the semantic cursor and omits selection bounds.
-- `startGeneration` now carries valid Workflow execution-time estimates into the View Node's
-  generation history as Web-compatible median and maximum completion timestamps.
-
-## 0.2.0-preview.4 - 2026-07-22
-
-### Changed
-
-- Persistent NDJSON stdio is now the default interaction mode for every Canvas authoring task,
-  including a plan containing only one write.
-- One-shot is limited to isolated reads, standalone transfers, explicit caller choice, or hosts that
-  genuinely cannot retain a child process; fewer tool calls alone is not a valid reason to use it.
-- The outer repository Skill now requires preview.4 so a newly triggered agent receives this mode
-  selection policy.
-
-## 0.2.0-preview.3 - 2026-07-21
-
-### Changed
-
-- The built-in Skill now treats credentials as an operator or agent-host provisioning precondition
-  and explains inherited environment, default `.env.local`, and explicit `--env-file` resolution.
-- Authentication is verified with a bounded Project read without inspecting, printing, copying, or
-  editing the token source.
-- The shell example that could encourage an agent to type a real token into a recorded interaction
-  has been removed, and missing or invalid credentials now direct the agent back to secure external
-  provisioning.
-
-## 0.2.0-preview.2 - 2026-07-21
-
-### Added
-
-- A platform-neutral built-in agent Skill available through `az8 guide` without credentials or a
-  network connection.
-- Section-level Markdown and versioned JSON guide output for progressive discovery.
-- Agent onboarding for platform concepts, runtime capability discovery, first-session, Canvas,
-  generation and media SOPs, failure recovery, prohibited actions, and completion checks.
-
-### Safety and compatibility
-
-- The Skill never replaces Project-scoped `capabilities.detail` or Workflow Definition discovery;
-  dynamic schemas, permissions, completion, History, and retry policy remain runtime-authoritative.
-- Existing semantic Operations and protocol version `1.0` are unchanged.
-
-## 0.2.0-preview.1 - 2026-07-21
-
-First installable internal preview.
-
-### Added
-
-- Project list, detail, create, and rename commands.
-- Persistent NDJSON stdio Canvas client with lifecycle, awareness, observations, Receipts,
-  reconnect, explicit shutdown, backpressure, and authenticated actor identity.
-- One-shot wrappers over the same Canvas Client and semantic Operation Registry.
-- Note lifecycle, non-World hierarchy, History, summary/detail inspection, and Core Node placement.
-- Generation Planning, Draft editing, Visual References, Workflow start, status query, and bounded
-  wait semantics with credit-usage information.
-- Public media URL import and safe local image/video/audio upload and download.
-
-### Safety and compatibility
-
-- Canvas writes are available only through semantic Operations and Commands.
-- Writes are serialized, never automatically retried, and isolate the Canvas context after an
-  indeterminate result. Read retry remains bounded.
-- Tokens are accepted only through environment variables or env files and are redacted from
-  program interaction and diagnostics.
-- 3D World, Asset aggregate management, automatic layout, media replacement, and batch upload are
-  intentionally not part of this preview.

package/RELEASE.md

@@ -1,93 +0,0 @@
-# AZ8 CLI release
-
-`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
-
-From the repository root:
-
-```bash
-pnpm release:az8-cli
-pnpm release:pack:az8-cli
-```
-
-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 visible-reference image generation, and uploads one
-generated 512×512 PNG:
-
-```bash
-node apps/az8-cli/scripts/smoke-test.js \
-  --bin ./tmp/az8-cli-release/install/node_modules/.bin/az8 \
-  --env-file ./.env.local
-```
-
-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. 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
-```
-
-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 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.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, 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
-npm view @everfir/az8-cli dist-tags --json
-```
-
-## Rollback
-
-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-stable-version> latest
-npm view @everfir/az8-cli dist-tags --json
-npm install --global @everfir/az8-cli
-az8 --version
-```
-
-For tarball distribution, retain every verified `.tgz`; reinstall the previous tarball and confirm
-`az8 --version`. A rollback changes only the installed client. It never reverses already
-acknowledged Project or Canvas effects; agents must use semantic compensation or Canvas History for
-product data.