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

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 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-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.

package/README.md

@@ -11,29 +11,55 @@ AZ8 CLI requires Node.js 20 or newer. Install the preview channel from the confi
 npm install --global @everfir/az8-cli@preview
 az8 --version
 az8 help
+az8 guide
 ```
 
 For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.2.0-preview.1.tgz
+npm install --global ./everfir-az8-cli-0.2.0-preview.3.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.
 
+## Built-in agent Skill
+
+Run `az8 guide` before the first AZ8 action in a new agent environment. It requires no token or
+network access and prints the versioned Skill shipped in the installed package. The guide defines
+the platform concepts, safe operating contract, first-session and authoring SOPs, generation and
+media workflows, failure recovery, prohibited actions, and completion checklist:
+
+```bash
+az8 guide
+az8 guide --section bootstrap
+az8 guide --section safety
+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.
+
 ## Credentials and environment
 
-Use an ignored `.env.local` or process 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:
 
 ```dotenv
-AZ8_TOKEN=...
+AZ8_TOKEN=<operator-provisioned-secret>
 AZ8_ENVIRONMENT=test
 ```
 
 `AZ8_ENVIRONMENT` accepts `test` or `production`. Command-line `--environment` overrides the env
-value. Tokens must not be passed through argv or stdio protocol payloads.
+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.
 
 ## Project Management
 
@@ -311,8 +337,9 @@ moves the Canvas context offline, and requires explicit reconnect and inspection
 Before distributing a preview tarball, verify all of the following from its clean installation, not
 from TypeScript source:
 
-1. `az8 --version` matches the immutable package version and `az8 help` lists Project, persistent
-   Canvas, one-shot, upload, and download entry points.
+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.
 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.

package/RELEASE.md

@@ -35,7 +35,7 @@ repository-wide `pnpm verify`. Publishing is an external action and requires exp
 authorization:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.1.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.3.tgz --tag preview
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 

package/dist/main.js

@@ -23860,8 +23860,73 @@ var OrderedFrameWriter = class {
 import { randomUUID } from "node:crypto";
 import path5 from "node:path";
 
-// src/canvas-one-shot.ts
+// src/agent-guide.ts
 import { readFile as readFile2 } from "node:fs/promises";
+var AGENT_GUIDE_URL = new URL("../skills/az8-cli/SKILL.md", import.meta.url);
+async function renderAgentGuide(options) {
+  const guide = parseAgentGuide(await readFile2(AGENT_GUIDE_URL, "utf8"));
+  const selected = options.section ? guide.sections.find((section) => section.id === options.section) : void 0;
+  if (options.section && !selected) {
+    throw new Error(
+      `Unknown guide section: ${options.section}. Available sections: ${guide.sections.map((section) => section.id).join(", ")}.`
+    );
+  }
+  if (options.format === "markdown") {
+    return `${selected ? selected.markdown : guide.markdown.trimEnd()}
+`;
+  }
+  return `${JSON.stringify(
+    {
+      format: "az8.agent-guide.v1",
+      packageVersion: options.packageVersion,
+      skill: { description: guide.description, name: guide.name },
+      ...selected ? { selectedSection: selected.id } : {},
+      sections: selected ? [selected] : guide.sections
+    },
+    null,
+    2
+  )}
+`;
+}
+function parseAgentGuideFormat(value) {
+  if (value === void 0 || value === "markdown") return "markdown";
+  if (value === "json") return "json";
+  throw new Error(`Unknown guide format: ${value}. Expected markdown or json.`);
+}
+function parseAgentGuide(source) {
+  const normalized = source.replaceAll("\r\n", "\n");
+  const frontmatter = normalized.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!frontmatter) throw new Error("Packaged AZ8 agent guide has invalid frontmatter.");
+  const name = readFrontmatterValue(frontmatter[1] ?? "", "name");
+  const description = readFrontmatterValue(frontmatter[1] ?? "", "description");
+  const body = normalized.slice(frontmatter[0].length);
+  const headings = [...body.matchAll(/^## (.+)$/gm)];
+  if (headings.length === 0) throw new Error("Packaged AZ8 agent guide has no sections.");
+  const sections = headings.map((heading, index) => {
+    const title = heading[1]?.trim() ?? "";
+    const start = heading.index ?? 0;
+    const end = headings[index + 1]?.index ?? body.length;
+    return {
+      id: slugify(title),
+      markdown: body.slice(start, end).trimEnd(),
+      title
+    };
+  });
+  return { description, markdown: normalized, name, sections };
+}
+function readFrontmatterValue(frontmatter, key) {
+  const prefix = `${key}:`;
+  const line = frontmatter.split("\n").find((candidate) => candidate.startsWith(prefix));
+  const value = line?.slice(prefix.length).trim();
+  if (!value) throw new Error(`Packaged AZ8 agent guide is missing ${key}.`);
+  return value.replace(/^(?:"(.*)"|'(.*)')$/, "$1$2");
+}
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+// src/canvas-one-shot.ts
+import { readFile as readFile3 } from "node:fs/promises";
 import path3 from "node:path";
 var MAX_INPUT_BYTES = 1024 * 1024;
 var PROCESS_SCOPED_OPERATIONS = /* @__PURE__ */ new Set(["redo", "undo"]);
@@ -23913,7 +23978,7 @@ async function readCanvasOneShotInput(argv2, dependencies = {}) {
   if (file !== void 0) {
     const filePath = path3.resolve(dependencies.cwd ?? process.cwd(), file);
     try {
-      source = dependencies.readFile ? await dependencies.readFile(filePath) : await readFile2(filePath, "utf8");
+      source = dependencies.readFile ? await dependencies.readFile(filePath) : await readFile3(filePath, "utf8");
     } catch {
       throw canvasClientFailure(
         "invalid-operation-input",
@@ -24667,6 +24732,26 @@ async function runAz8Cli(argv2, dependencies = {}) {
   }
   const [scope, command, resourceId, capability] = readPositionals(argv2);
   if (!scope || scope === "help" || scope === "-h") return helpResult();
+  if (scope === "guide") {
+    if (command && command !== "help" && command !== "-h") {
+      return errorResult(`Unknown guide command: ${command}`);
+    }
+    if (command === "help" || command === "-h") return guideHelpResult();
+    try {
+      const format = readGuideOption(argv2, "--format");
+      const section = readGuideOption(argv2, "--section");
+      return {
+        exitCode: 0,
+        stdout: await renderAgentGuide({
+          format: parseAgentGuideFormat(format),
+          packageVersion: readAz8CliVersion(),
+          ...section ? { section } : {}
+        })
+      };
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : "Unable to read agent guide.");
+    }
+  }
   if (scope !== "projects" && scope !== "canvas") return errorResult(`Unknown scope: ${scope}`);
   if (!command || command === "help" || command === "-h") {
     return scope === "projects" ? projectHelpResult() : canvasHelpResult();
@@ -24892,9 +24977,11 @@ function readPositionals(args2) {
     "--position-y",
     "--request-id",
     "--scope",
+    "--section",
     "--service-url",
     "--timeout-ms",
-    "--view-node-id"
+    "--view-node-id",
+    "--format"
   ]);
   const positionals = [];
   for (let index = 0; index < args2.length; index += 1) {
@@ -24910,7 +24997,9 @@ function readPositionals(args2) {
 function helpResult() {
   return {
     exitCode: 0,
-    stdout: `${projectHelpOutput()}
+    stdout: `${guideHelpOutput()}
+
+${projectHelpOutput()}
 
 ${canvasHelpOutput()}
 
@@ -24918,6 +25007,16 @@ ${commonHelpOutput()}
 `
   };
 }
+function guideHelpOutput() {
+  return [
+    "Agent onboarding:",
+    "  az8 guide                              Read the complete built-in agent Skill",
+    "  az8 guide --section <section>          Read one Skill section",
+    "  az8 guide --format markdown|json       Select output (default: markdown)",
+    "  Sections: contract, concepts, bootstrap, interaction-modes, canvas-sop, generation,",
+    "            media, recovery, safety, completion"
+  ].join("\n");
+}
 function projectHelpOutput() {
   return [
     "Project management:",
@@ -24966,6 +25065,7 @@ function commonHelpOutput() {
   return [
     `AZ8 CLI ${readAz8CliVersion()}`,
     "  az8 --version                   Print the installed package version",
+    "  az8 guide                       Read the built-in agent onboarding Skill",
     "",
     "Common options:",
     "  --environment <test|production>  Select the API environment (default: production)",
@@ -24980,6 +25080,18 @@ function canvasHelpResult() {
 ${commonHelpOutput()}
 ` };
 }
+function guideHelpResult() {
+  return { exitCode: 0, stdout: `${guideHelpOutput()}
+
+${commonHelpOutput()}
+` };
+}
+function readGuideOption(argv2, name) {
+  if (!argv2.includes(name)) return void 0;
+  const value = readOption(argv2, name);
+  if (!value) throw new Error(`${name} requires a value.`);
+  return value;
+}
 function projectHelpResult() {
   return { exitCode: 0, stdout: `${projectHelpOutput()}
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.2.0-preview.1",
+  "version": "0.2.0-preview.3",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",
   "files": [
     "dist",
+    "skills",
     "CHANGELOG.md",
     "RELEASE.md"
   ],

package/skills/az8-cli/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: az8-cli
+description: Use AZ8 CLI to safely select or create Projects, inspect and author Project Canvases, run generation workflows, transfer media, and participate as a persistent collaborative agent. Use whenever a task asks an agent to read, create, edit, organize, generate, upload, or download content in AZ8 Studio.
+---
+
+# 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
+capabilities instead of guessing operation names or input shapes.
+
+## Contract
+
+- Use only public `az8 projects` 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.
+- 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.
+- A sequence is ordered but not transactional. Stop immediately after the first failure or
+  indeterminate result; do not execute later steps.
+- 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.
+- Require the operator or agent host to provision credentials outside the recorded interaction.
+  Keep tokens in the inherited process environment or an ignored env file. Never type, read, copy,
+  print, or return a token through a shell tool call, argv, stdio frame, prompt, log, or output.
+
+## Concepts
+
+- **Project** is the collaboration and permission boundary. Create, list, get, and rename Projects
+  through `az8 projects`.
+- **Project Canvas** is the synchronized creative surface inside one Project. A persistent client
+  has its own connection, lifecycle, projection, History, Receipt Log, and Awareness identity.
+- **View Node** is a Canvas placement: note, group, or resource target with position, size, parent,
+  stacking, Draft, and presentation state.
+- **Core Node** is immutable or server-owned creative content such as an image, video, or audio.
+  Resource View Nodes resolve Core Nodes through Project Content. Do not manufacture Core Nodes or
+  bindings.
+- **Project Content** is the authority that associates a View Node target with its effective Core
+  Node output. Assets are a separate organization of Core Nodes and are not implemented here.
+- **Workflow Definition** describes a generation capability and its current input contract.
+  **Workflow Run** is one server-side generation execution.
+- **Operation** is one validated business interaction. **Command** is its internal mutation
+  boundary and is never caller-accessible.
+- **Receipt** is the append-only record of one attempted Operation. It reports identity, ordering,
+  outcome, revisions, and optional usage. It is not Canvas History.
+- **History** contains reversible local interactions. Only Operations advertised as `undoable`
+  participate. A generation start is a History barrier and is not undone by `undo`.
+- **Awareness** is ephemeral presence, client name, and Attention Cursor information. It never
+  grants authority, changes persisted authorship, or proves a business result.
+- **Actor** is the authenticated account from `AZ8_TOKEN`. A client or awareness name cannot
+  impersonate another author.
+
+## Bootstrap
+
+1. Verify the installed client without credentials:
+
+   ```bash
+   az8 --version
+   ```
+
+2. Require credentials to be provisioned by the operator or agent host before authenticating. The
+   CLI accepts `AZ8_TOKEN` from its inherited process environment or an env file. A provisioned env
+   file has this shape, but the agent must not fill the placeholder with a real token in a recorded
+   interaction:
+
+   ```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
+   explicit file may live elsewhere and is selected only by path:
+
+   ```bash
+   az8 projects list --scope owned --page-size 1 \
+     --environment test --env-file /secure/path/.env.local
+   ```
+
+   Use the authenticated read as the credential check. Never verify a token with `cat`, `sed`,
+   `grep`, `env`, `printenv`, `echo`, shell tracing, or by reading the env file through another
+   tool. Do not create, edit, move, or delete a credential file unless the operator explicitly asks
+   through a secure provisioning workflow. Keep it outside version control with owner-only access.
+
+   The inherited process environment overrides env-file values; `--environment` overrides
+   `AZ8_ENVIRONMENT`. Always pass or provision the intended environment explicitly. If the CLI
+   reports a missing token or authentication failure, stop and ask the operator to provision or
+   replace it outside the conversation. Never ask them to paste the secret into chat.
+
+3. Select an existing Project or create a bounded workspace:
+
+   ```bash
+   az8 projects list --scope owned
+   az8 projects get <project-id>
+   az8 projects create --name "Agent workspace"
+   ```
+
+   Retain the returned Project ID. Confirm the authenticated role before assuming write access.
+
+4. Discover the effective surface for that Project:
+
+   ```bash
+   az8 canvas query <project-id> capabilities.summary
+   az8 canvas query <project-id> capabilities.detail
+   az8 canvas query <project-id> canvas.summary
+   ```
+
+   `capabilities.summary` is the short menu. `capabilities.detail` is authoritative for exact JSON
+   Schema, `effect`, `history`, `completion`, and `retry`. Availability is filtered by the current
+   account, Project role, upstream services, and CLI version. Do not rely on remembered schemas.
+
+5. Use `canvas.detail` only when exact node geometry, Draft, status, or bindings are needed:
+
+   ```bash
+   az8 canvas query <project-id> canvas.detail --view-node-id <view-node-id>
+   ```
+
+6. Choose one-shot for independent tasks and persistent stdio for a collaborative session. Finish
+   by inspecting the affected View Nodes or Workflow Run rather than trusting visual assumptions.
+
+## Interaction modes
+
+Use one-shot commands for a self-contained query, write, upload, or download:
+
+```bash
+printf '%s\n' '{"text":"Idea","position":{"x":160,"y":160}}' |
+  az8 canvas operation <project-id> createNote --input-stdin --request-id create-note-1
+```
+
+- Supply Operation input through exactly one of `--input-stdin`, `--input-file`, or `--input-json`.
+- Give every write attempt a meaningful unique `--request-id` and retain its returned Receipt.
+- Each invocation opens, hydrates, executes, and closes a real Canvas client.
+- One-shot processes do not preserve local History, Receipt Log, Awareness, or request replay.
+  Therefore `undo`, `redo`, `receipts.summary`, and `receipt.detail` require persistent stdio.
+
+Use persistent stdio when multiple ordered interactions, live synchronization, History, Receipt
+lookup, observations, or human collaboration matter:
+
+```bash
+az8 canvas open <project-id> --write --format ndjson
+```
+
+1. Continuously drain stdout; it is an ordered NDJSON protocol stream and may apply backpressure.
+2. Read `hello`, select protocol `1.0`, then send `initialize` for the same Project ID.
+3. Wait for `ready` before any query or Operation.
+4. Keep exactly one reader for stdout. Parse each frame by `type`, `requestId`, and `streamSeq`.
+5. Use `compact` observations by default. Query `awareness.detail` when cursor context is needed;
+   cursor coordinates are intentionally not streamed.
+6. On an observation gap, query summary/detail and rebuild the local view.
+7. Send `shutdown` and wait for ordered completion. EOF or a signal is emergency cleanup, not a
+   cancellation or rollback mechanism.
+
+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.
+
+## Canvas SOP
+
+1. Query `canvas.summary`; query selected details only as needed.
+2. Query `capabilities.detail` and validate the planned Operation input against its schema.
+3. Pick explicit absolute Canvas coordinates. Public move positions remain absolute even for group
+   children.
+4. Submit one Operation with a new request ID and wait for its terminal Receipt.
+5. Confirm the Receipt outcome and affected IDs, then query the changed View Node when subsequent
+   work depends on its exact state.
+6. Only then plan the next interaction.
+
+Common capabilities include notes, move/resize/rename, duplicate/remove, groups and stacking, Core
+Node placement, and media targets. The runtime catalog is authoritative. Group nodes cannot nest;
+stacking applies only among siblings. Unsupported World, Decoration, Asset, alignment, and automatic
+layout behavior must not be simulated through lower-level writes.
+
+Use `undo` or `redo` only in the same persistent session and only after checking History semantics
+in capability detail. Silent edits are valid Web-equivalent interactions but do not create History
+entries. Never use compensating low-level mutations to imitate undo.
+
+## Generation
+
+Generation is an explicit sequence, never one transaction:
+
+1. Create a target with `createMediaTarget` and retain its View Node ID.
+2. Call the read-only `planGeneration` Operation with the target, prompt, and any references. Use
+   `detail: "detail"` when configuration fields or dynamic enum options are needed.
+3. If the plan reports blocking issues, resolve them and plan again. Do not execute a non-ready
+   plan.
+4. Execute `plan.operations` exactly in order, one Operation at a time. Each step revalidates
+   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
+   Project Content before downloading or placing it elsewhere.
+
+Workflow Definitions change over time. Query `workflowDefinitions.summary`, then
+`workflowDefinition.detail` only when planning detail is insufficient. Never guess a Definition,
+configuration option, modality, cost, or media compatibility from its display name.
+
+The start Receipt may report `usage.credits.status` as `estimated`, `not-consumed`, or `unknown`.
+Estimated cost is informational, not final charged usage. There is no second confirmation. Never
+claim actual credit consumption from an estimate.
+
+## Media
+
+For a local image, video, or audio file, use the semantic upload wrapper:
+
+```bash
+az8 canvas upload <project-id> \
+  --file ./reference.png \
+  --idempotency-key reference-image-1 \
+  --name "Reference image" \
+  --position-x 640 --position-y 160
+```
+
+- Use a stable logical idempotency key for that exact file intent. Conflicting key reuse is an
+  error. Replay only after inspecting and reconciling the prior attempt.
+- Let the CLI inspect bytes, MIME, size, and checksum and let the server create the Core Node and
+  binding. Do not supply a claimed media type, upload URL, Core Node ID, or Project Content record.
+- A known failure may leave one inspectable `failed` View Node. An unknown response leaves it
+  `pending` and isolates the context; do not create a replacement until reconciliation.
+
+Use `importExternalMedia` only for a deliberate public HTTP(S) media URL. It references that URL; it
+does not upload bytes or add content to an Asset.
+
+Download only an effective View Node output or an explicit Core Node within the Project context:
+
+```bash
+az8 canvas download <project-id> --view-node-id <view-node-id> --output ./result.png
+```
+
+The destination must be explicit. Existing files are preserved unless `--overwrite` is explicitly
+chosen. Verify the returned absolute path, byte count, detected MIME, Core Node ID, and SHA-256.
+Never extract or reuse hidden media URLs as a general downloader.
+
+## Recovery
+
+Classify the outcome before deciding what to do:
+
+- **Succeeded:** accept only a terminal success result/Receipt, retain returned identities, and
+  inspect facts required by the next step.
+- **Definitive failure:** the Operation did not take its promised effect. Fix input, permissions, or
+  business state before making a new explicitly identified attempt.
+- **Indeterminate write:** acknowledgement, transport, backend response, or deadline was lost after
+  the write might have started. Assume neither success nor failure. Stop the sequence, take the
+  context offline, reconnect manually, inspect Canvas/Project Content/Workflow facts and Receipts,
+  then decide whether a new attempt is safe. Never automatically retry.
+- **Read failure:** retry only if capability/error metadata marks the read retryable, and keep the
+  retry bounded. A reconnect failure cancels queued unfinished work; it does not replay it.
+- **Workflow wait timeout:** if the Run is authoritatively still pending or running, treat this as
+  the end of one observation window. Continue other work or query later; do not cancel or restart.
+- **Caller cancellation:** cancellation is safe only before an Operation begins. Once a write has
+  attempted to start, interruption waits for its deadline and cannot roll it back. After uncertainty,
+  reconcile facts before acting.
+
+For one-shot Canvas commands, exit `0` means success, `1` means a definitive caller/business
+failure, and `2` means an indeterminate lifecycle or transport outcome. Media download may return
+`130` for caller cancellation. Always read the structured result; do not generalize these codes to
+Project commands or the lifetime of a persistent stdio process.
+
+## Safety
+
+Never:
+
+- write raw backend endpoints, Yjs maps, Collaborative Document paths, generic patches, Core Node
+  payloads, or Project Content bindings;
+- invent an Operation or input field absent from `capabilities.detail`;
+- execute writes concurrently, continue a planned sequence after a failure, or wrap multiple
+  Operations in assumed transaction semantics;
+- automatically retry a write, reuse a request ID for an unrelated attempt, or treat an idempotency
+  key as proof that blind replay is safe;
+- conclude that a timed-out write failed, conclude that an accepted Workflow Run completed, or
+  conclude that an Awareness event persisted data;
+- expose a token, presigned URL, permanent media URL, env-file contents, or private output in logs
+  or protocol payloads;
+- inspect, print, or edit an operator-provisioned credential source merely to check whether it
+  exists; authenticate with a bounded read instead;
+- use awareness client names to impersonate persisted authors or treat Attention Cursor position as
+  authority;
+- 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.
+
+## Completion
+
+Before reporting a task complete, verify all applicable facts:
+
+- The intended environment, 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.
+- The first failure stopped the remaining sequence, and every indeterminate effect was reconciled
+  after explicit reconnect/inspection.
+- Created or edited View Nodes were checked at the detail level needed by downstream work.
+- Generation start and generation completion were reported as separate interactions; the target's
+  effective Core Node was resolved after completion.
+- Media transfers were verified by identities and checksums without exposing URLs or credentials.
+- Persistent stdio was shut down in order, or any abnormal termination and uncertain active write
+  was disclosed.
+- Deferred scopes were not approximated by bypassing the public semantic surface.
+
+When any item cannot be proven, report the uncertainty and the next safe read or reconciliation
+step instead of claiming completion.

package/skills/az8-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AZ8 CLI"
+  short_description: "Safely create and collaborate in AZ8 Project Canvases"
+  default_prompt: "Use $az8-cli to create or edit an AZ8 Project Canvas safely."