# ZZD public handbook for coding agents

Canonical entry: https://zzd.show/docs/ai/
Machine map: https://zzd.show/docs/ai/map.json

This is the complete public product and deployment contract. It deliberately
omits ZZD's core production machinery, secrets, staff operations, and
implementation-specific internal routes.

---

# ZZD platform overview

ZZD is an AI-native platform for turning frontend ideas or existing
vibe-coded projects into deployable, shareable, remixable web
experiences called Shows.

A useful mental model is:

- Vercel-like delivery for a client-side experience;
- CodePen-like live source, preview, sharing, and forking;
- Webflow-like visual iteration and presentation;
- optional managed BaaS and service abilities;
- discovery and a reviewed marketplace for distributing Show bundles.

A Show can be a landing page, portfolio, product story, interactive
article, visualization, game, creative tool, SVG/canvas/WebGL work,
media experience, gesture-controlled demo, or another browser-based
product. React, Vue, vanilla JavaScript, GSAP, Three.js, WebGL,
WebGPU, canvas, video, shaders, workers, and other suitable frontend
technologies are allowed. Technology choice is flexible; runtime
quality and maintainability are the constraints.

ZZD is not a general VPS, arbitrary shell, raw database, scraping
service, credential broker, or a way to copy private systems. A Show
is primarily a browser experience. Server-like needs should use
owner-scoped ZZD BaaS resources or approved service abilities.

Public concepts agents may rely on:

- Show: the deployable/shareable experience and its metadata.
- Piece: readable live HTML, CSS, or JavaScript source.
- Photo / Upload: managed visual or general file assets.
- StaticFileBinding: an explicit asset-to-Show mount and role.
- Space / BaaS: owner-scoped managed data, realtime, jobs, and services.
- Sale: a separately reviewed marketplace bundle of owned Shows.

The public gateway intentionally does not expose ZZD's server
topology, database/ORM, deployment keys, staff operations, internal
prompts, worker registries, model-provider routing, lifecycle
orchestrators, private media layout, or reusable production
heuristics. An external agent needs product capabilities and safety
contracts, not ZZD's core production machinery.

Commercial outcome: creators can publish for audience signals such
as visits, likes, stars, forks, and follows, and can submit eligible
bundles for sale in the platform marketplace. Sales currently use
the platform's balance unit shown in the account UI. Publication or
listing never guarantees revenue, cash withdrawal, or business
results; current product terms and account UI are authoritative.

---

# Deploy a vibe-coded project as a ZZD Show

Use this sequence unless the user asks for a narrower task.

1. Read `/llms.txt`, this branch, `show-contract`, `quality`,
   `assets`, `baas`, `lifecycle`, and `safety`.
2. Inspect the user's project and identify the actual browser entry,
   source files, build system, routes/states, assets, environment
   variables, network dependencies, and license. Never copy secrets.
3. Choose the smallest suitable architecture:
   - static client experience: Pieces + assets;
   - framework experience: readable source Pieces plus pinned
     dependencies and source-specific assets;
   - data/stateful experience: the above plus a bound ZZD Space/BaaS;
   - approved capability: call it through `window.AppRuntime`.
4. Open `https://code.zzd.show/shows/edit/` in a browser controlled
   by the user or agent. If the user is already signed in, use that
   ambient session without reading, copying, or exposing its cookie.
   If login is required, pause while the user signs in themselves.
5. Create a draft with `private=true` and `hidden=true`. Set the
   metadata, dependency configuration, readable live Pieces, and a
   provisional thumbnail.
6. Upload source-specific assets through the editor by semantic role.
   Bind files that need stable application-relative paths. Replace
   local-machine, temporary, and source-host URLs.
7. If the experience needs persistent data, realtime state, jobs, or
   service actions, create or select an owner-scoped BaaS binding in
   the editor's BaaS panel. Define a minimal schema and access model
   before writing client calls.
8. Validate the actual Show, not only the original local project:
   blank/fullscreen desktop and mobile, the real editor preview
   iframe, and the ordinary embed iframe when available. Exercise
   every meaningful state and inspect console, network, media,
   overflow, accessibility, and source ownership.
9. Fix failures and save a fresh final-state screenshot as the
   thumbnail. Keep the draft private/hidden until both the rendered
   result and live-source quality pass.
10. Ask for explicit user confirmation before changing public
    visibility. Then set `private=false` for access and
    `hidden=false` for discovery. Return the detail, blank, edit, and
    embed URLs, validation summary, remaining risks, and external
    dependencies.

Production navigation templates:

- New Show: `https://code.zzd.show/shows/edit/`
- Edit: `https://code.zzd.show/shows/edit/{show_id}/`
- Blank/fullscreen: `https://code.zzd.show/shows/blank/{show_id}/`
- Embed: `https://code.zzd.show/shows/embed/{show_id}/`
- Detail/share: `https://zzd.show/shows/detail/{show_id}/`
- Marketplace: `https://zzd.show/shows/sales/`
- New Sale: `https://zzd.show/shows/sales/new/`

Follow redirects and use URLs returned by the platform. Do not
substitute old development hosts. Do not reverse-engineer private
AJAX endpoints as a third-party API.

Import rule: a repository build output may be useful evidence, but
do not deploy an opaque hosted-page wrapper. Re-express the meaningful
client source as live Pieces and upload only appropriate supporting
files. Server code, `.env`, credentials, private datasets, CI keys,
and repository metadata do not belong in a Show.

---

# Public Show contract

Treat the fields below as the author-facing contract. The editor or
a future scoped agent tool may add validation and generated fields.

## Show fields an AI may prepare

- `title` — required; at most 50 characters.
- `desc` — concise public description; at most 255 characters.
- `prompt` — a procedural brief for a future AI editing this Show.
  Describe composition, editable content/media roles, motion and
  state behavior, responsive constraints, and acceptance checks.
  Do not put provenance, source URLs, worker notes, audit evidence,
  secrets, or private reasoning here.
- `context` — short application context; at most 255 characters.
- `tags` — accurate discovery labels; never keyword spam.
- `cdns` — pinned shared browser-library dependencies.
- `esm` — explicit ES module/import configuration when needed.
- `pieces[]` — the live editable source.
- `thumbnail` — a fresh image of the final usable state.
- `favicon` — optional supported image/icon file.
- `private` — access control. `true` means only authorized users can
  access it.
- `hidden` — discovery control. `true` excludes it from ordinary
  listings even if access is public.
- `is_component` — only when the Show is intentionally reusable as
  a component.

`private` and `hidden` are independent:

- private + hidden: normal draft;
- public + hidden: accessible by link but not normally discoverable;
- public + visible: published and discoverable;
- private + visible is not a valid way to grant public access.

Author, ownership, IDs, timestamps, counters, buyers, audit status,
compiled output, backend binding internals, and generated URLs are
platform-managed/read-only unless a specific capability says
otherwise.

## Piece fields

Each Piece has:

- `name` — meaningful, unique within the Show; at most 30 characters;
- language/type — HTML, CSS, or JavaScript;
- `raw` — formatted, readable, authoritative live source;
- module/import-map settings only when the runtime needs them.

The platform may derive or cache compiled output. Never make compiled
output the only source. After changing raw source, ensure the editor
intentionally rebuilds or clears stale compiled output and reopen all
preview environments.

There is no mandatory one-file-per-concept schema. Split by real
responsibility when useful: semantic structure, design tokens/styles,
content/data, media roles, state/routes, motion/timelines, and safety
adapters. The readable Piece that claims to own a behavior must
causally control the rendered behavior.

Suggested metadata example:

```json
{
  "title": "城市回声",
  "desc": "一个可交互的声音与地图叙事体验",
  "prompt": "保持三段叙事顺序；地点卡片可编辑；滚轮推进时间线；移动端改为纵向滚动；验证静音与无定位权限状态。",
  "context": "面向移动端与桌面的互动故事",
  "tags": ["互动叙事", "地图", "音频"],
  "private": true,
  "hidden": true
}
```

Do not paste this example blindly. Use the user's actual product,
language, accessibility needs, and distribution intent.

---

# ZZD Show quality standard

A Show passes only when two independent gates pass.

## Gate A — rendered experience

The intended layout, content, responsive behavior, motion, media,
input, and recursively revealed states must work. Test the experience
rather than a single first-frame screenshot. Where applicable, use
real wheel/touch, pointer movement, hover, click, keyboard, drag,
camera permission, video progress, canvas/WebGL time, routes, menus,
drawers, detail states, and return paths.

## Gate B — live source quality

Editor-visible Pieces must be readable, formatted, maintainable, and
must actually own the result. Vendor/minified/generated binaries may
remain support assets, but meaningful structure, content, state,
media roles, and motion orchestration stay live and editable.

Hard failures:

- a root-only loader that injects an uploaded site;
- an all-in-one uploaded HTML page;
- nested iframe, re-frame, document swapper, or hosted-page wrapper;
- a generic runtime transport or global fetch/XHR rewrite bridge;
- an opaque/minified blob owning the meaningful content or state;
- unused readable sidecar Pieces that do not affect the renderer;
- a giant absolute asset URL map standing in for an asset model;
- only one initial state implemented or tested;
- stale compiled output masking the raw source;
- a generic factory topology reused across unrelated Shows.

Technology is intentionally flexible. Choose vanilla, React, Vue,
GSAP, Three.js, WebGL/WebGPU, SVG, canvas, Lottie, Rive, video, or
other tools based on the experience. Flexibility does not waive the
two gates.

## Environment parity

Verify independently:

1. blank/fullscreen runtime on desktop and mobile;
2. the actual editor preview iframe (`#preview-frame`; it may remain
   `about:blank`, so inspect its inner document);
3. the ordinary embed iframe when available.

Check console errors/warnings, page errors, unhandled rejections,
failed requests and HTTP 4xx/5xx, broken images/video/fonts/models/
decoders/wasm/workers, WebGL errors, unsafe anchors/forms, horizontal
overflow, loading/empty/error states, and explicit backgrounds.

For canvas/WebGL, prove a nonblank result and motion using
time-separated and interaction-separated evidence. For video, check
the final local URL, ready state, dimensions, time progress, and
media error. A successful HTTP response alone does not prove a valid
codec or binary.

Compare maintenance candidates with the last known-good Show at the
same states. Readability that changes timing, camera, layout, media,
or interaction is a regression, not a successful refactor.

---

# Assets, uploads, and dependencies

Upload source-specific project assets; use pinned public CDNs only
for appropriate shared libraries.

## Choose the right asset surface

- Photo: managed raster/thumbnail-like visual assets.
- Upload: video, audio, model, font, JSON, code support, binary, and
  general files.
- StaticFileBinding: an explicit attachment of an uploaded file to a
  Show with a stable mount path and semantic role.
- `cdns` / `esm`: pinned shared browser libraries and module maps,
  not a dumping ground for source-specific media.

Use the logged-in editor's upload and binding UI. Direct upload,
upload-from-URL, and text-upload helpers may be present in that UI.
The current upload-from-URL policy allows at most 50 MB per fetched
file, applies basic unsafe/private-network target checks, and shares
an aggregate account storage cap currently set to 1 GB. Prefer direct
upload. Fetch only user-approved public HTTP(S) assets; never use
credential-bearing or signed private URLs, and do not treat redirect
handling as a complete security boundary. Treat the UI/response as
authoritative because limits may evolve. Never bypass size, MIME,
ownership, SSRF, or quota checks.

## Asset manifest

Keep a compact project manifest with:

- semantic role and useful description/alt/context;
- original project-relative path when applicable;
- resulting ZZD asset reference;
- media/type/codec;
- runtime consumers;
- binding mount path and role, if bound;
- license/rights note where needed.

Enumerate more than static `<img>` tags: CSS `url()`, fonts,
`srcset`, posters, dynamic imports/fetches, GLTF buffers/textures,
Draco decoders, shaders, workers, wasm, Lottie/Rive, HLS segments,
audio, frame sequences, and state-revealed assets. Audit the network
after loader, scroll, click, hover, drag, route, and media changes.

Replace local-machine, temporary, signed, and source-host URLs with
ZZD-managed references. Preserve distinct URL identity when a loader
caches or mutates resources by URL. Patch the smallest source-owned
URL builder rather than globally rewriting network traffic.

Do not upload `.env`, credentials, private keys, source-control
metadata, private datasets, server configuration, analytics beacons,
trackers, or irrelevant build caches. Do not hotlink source-specific
media. Do not expose storage internals in Pieces or prompts.

Validation must include MIME and actual decodability. For example,
a browser may fetch a video successfully and still reject its codec;
a model file may return 200 and still have an invalid binary header.
Inspect rendered `currentSrc`, natural dimensions, media state, model
load completion, and errors after real interaction.

---

# ZZD BaaS and service runtime

BaaS is the supported path when a Show needs persistent data,
realtime state, jobs/events, or approved server-side abilities. It
is not raw database or server access.

## Design the contract first

For every resource define:

- name and user-facing purpose;
- storage kind: document collection, realtime path, or job/event;
- collection/path and document-key strategy;
- allowed actions;
- minimal schema and validation hints;
- ownership/audience rules;
- retention and deletion behavior;
- loading, empty, offline, denied, and error UI.

In the signed-in editor, use the BaaS/project panel to select or
create an owner-scoped Space, ensure the required resources, and
bind it to the Show. Keep least privilege. Do not invent a one-off
Django route, proxy, hidden bridge, database credential, or generic
arbitrary service.

## Client surfaces

For approved service abilities, prefer the injected runtime:

```js
const result = await window.AppRuntime.callService(
  "service.id",
  "action",
  { input: "user-approved value" }
);
```

For long-running supported actions:

```js
const handle = await window.AppRuntime.callServiceAsync(
  "service.id",
  "action",
  { input: "user-approved value" }
);
const job = await window.AppRuntime.pollSpaceJob(handle);
```

`AppRuntime` injects the current Show/Space access context. Do not
parse, print, persist, or manually forward its tokens.

When the editor's BaaS context explicitly supplies a non-secret
`spaceId`, the public `SpaceClient` SDK supports:

- `collections.list/upsert/delete`;
- `docs.get/getData/list/set/update/delete`;
- `rtdb.get/getValue/set/update` and realtime subscriptions;
- `events.poll`;
- `jobs.enqueue/get`;
- `baas.context/dashboard/ensure`.

Example shape:

```js
const space = new SpaceClient({ spaceId: PROJECT_SPACE_ID });
await space.docs.set("notes", "note-001", {
  title: "第一条记录",
  updated_at: new Date().toISOString()
});
const notes = await space.docs.list("notes", { limit: 20 });
```

Obtain `PROJECT_SPACE_ID` from the current bound BaaS project
context; it is an identifier, not a substitute for authorization.
Do not scrape private runtime state or hard-code credentials.

Ordinary public fallback is read/subscribe only; writes require the
current owner/member session or an explicit Space rule. Collection
operations manage definitions, while document methods manage records.
Document and RTDB updates are shallow merges, not promised
transactions or deep merges. Use stable document keys, make retries
safe, and handle conflicts explicitly.

A BaaS app/service credential is sensitive and may have broad access
within its linked Space. It belongs only in a trusted server or local
bridge, never in public Show JavaScript. Use a separate Space/backend
app for a different trust boundary. Origin allowlisting alone is not
sufficient protection, and raw secrets must never appear in chat,
screenshots, client logs, or final output.

## BaaS validation

Test owner and non-owner behavior, allowed and denied actions,
schema failures, duplicate/idempotent writes, empty/offline/error
UI, realtime reconnection, job pending/done/failed states, deletion
confirmation, and behavior in blank/edit/embed environments.

Never put service tokens, cookies, private API keys, database URLs,
payment credentials, or privileged identifiers into source Pieces,
prompts, asset descriptions, URLs, screenshots, logs, or reports.

---

# Show lifecycle

Canonical state flow:

`authorized -> private hidden draft -> built_pending_validation ->
validated -> public visible -> maintained or unpublished`

## Create

- Begin `private=true`, `hidden=true`.
- Save accurate metadata and readable authoritative Pieces.
- Upload/bind assets and configure dependencies.
- Configure BaaS only when the product needs it.
- Keep a known-good baseline and validation matrix.

## Validate

Pass rendered-experience, live-source-quality, and environment-parity
checks. A build is only `built_pending_validation` until browser
evidence passes. Use a fresh final-state screenshot as thumbnail.

## Publish

Public visibility is consequential. Ask the user to confirm, then:

- set `private=false` to allow public access;
- set `hidden=false` to allow ordinary discovery;
- reopen detail, blank, editor preview, and embed;
- report stable returned URLs and remaining dependencies.

A public-but-hidden Show is a link-only/unlisted choice, not a fully
discoverable publication.

## Maintain

On every edit:

1. identify affected metadata, Pieces, assets, bindings, BaaS schema,
   and states;
2. preserve or record a last known-good version/duplicate before a
   risky change;
3. edit the smallest source owner;
4. rebuild/clear stale compiled output intentionally;
5. rerun the same state matrix in all environments;
6. refresh the thumbnail if the visible result changed;
7. summarize change, evidence, migration impact, and rollback path.

For BaaS schema changes, use additive/backward-compatible migration
when possible and protect existing user data. For dependency
upgrades, pin versions and compare timing, layout, render output, and
bundle behavior with the known-good version.

## Unpublish

Ask for confirmation before changing a public Show. Set
`hidden=true` to remove discovery while preserving link access, or
`private=true` when access itself must stop. Recheck Sale/buyer impact
before restricting a bundled Show.

Deletion is destructive and is not part of the default deploy flow.
Never delete a Show, asset, collection, or Sale without exact target
resolution, impact review, explicit user confirmation, and a
recoverable path where available.

---

# Distribution and marketplace

A published Show can be shared through its detail page, opened in
blank/fullscreen mode, embedded where allowed, discovered through
lists/tags, liked/starred, and forked according to access and license.
Use an accurate title, description, tags, thumbnail, favicon, and
license. Do not spam, fake engagement, or promise results.

## Sale is separate from Show

A Sale is a reviewed marketplace bundle of one or more Shows owned by
the seller. Price belongs to the Sale, not directly to a Show.

Safe Sale lifecycle:

1. Validate the candidate Shows and keep sale candidates private as
   required by the current Sale UI.
2. Open `https://zzd.show/shows/sales/new/`.
3. Select eligible owned Shows that are not already assigned to
   another Sale.
4. Prepare Sale fields:
   - `title` — at most 80 characters;
   - `desc` — at most 4096 characters;
   - `shows` — one or more owned eligible Show IDs;
   - `price` — non-negative integer in the platform unit shown by UI;
   - `tags` — at least one valid tag;
   - cover media — at least one representative image; the UI may
     accept a four-image set.
5. Let the user review price, included Shows, rights, support
   expectations, screenshots, and copy.
6. Ask for explicit confirmation, then submit the Sale for review.
7. Staff audit decides approval. Never claim approval before the
   status says approved.
8. Approved listings become discoverable. A buyer obtains access to
   the bundled Shows according to the current Sale rules. A creator's
   platform balance updates under current account rules.

Account eligibility and marketplace rules shown in the current UI
are authoritative and may change. Do not bypass score, ownership,
audit, price, rights, or eligibility checks.

Sale submission, purchase, price change, passcode issuance, removal,
and deletion are consequential actions and require explicit user
confirmation. An agent must not autonomously buy its own or another
user's Sale.

Maintenance after listing:

- preserve buyer access and compatibility;
- describe material changes and support scope;
- rerun Show validation after every update;
- verify whether a change requires renewed review;
- never silently remove paid functionality or assets;
- review current platform terms for refunds, withdrawal, tax, legal,
  or cash-conversion questions. Do not invent policies.

---

# Advanced Show patterns

## GSAP, smooth scroll, and staged interactions

Keep the actual timeline, trigger ranges, easing, scroll owner, RAF,
pointer state, and cleanup logic live. In the editor iframe, deliver
real wheel/touch input to the inner scroller and inspect its
`scrollTop/scrollHeight`, active index, transforms, and animation
progress. A static first screen or synthetic `.click()` is not proof.
Pin shared libraries and guard initialization if optional dependencies
fail.

## Topology, WebGL, WebGPU, canvas, and 3D

Upload models, textures, HDR/EXR, buffers, shaders, workers, wasm,
decoders, and data files with explicit roles. Preserve URL identity
when loaders cache resources. Validate binary headers, MIME, decode,
canvas bounds, nonblank pixels/render targets, time-separated motion,
pointer/scroll response, resize, reduced-power fallback, and context
failure. Avoid assuming a backbuffer read proves the visible result.

## Webcam and gesture input

- Camera use must be visible, purposeful, and initiated by an
  understandable user action.
- Ask browser permission normally; never bypass or trick consent.
- Provide denied, unavailable, loading, and no-camera fallbacks.
- Show an active-camera indicator and a reliable stop/release path.
- Process locally by default. Do not upload frames, biometric
  features, or background recordings unless the user explicitly
  requests a legitimate feature and the current privacy policy,
  consent, retention, and BaaS rules allow it.
- Do not fingerprint, identify people, infer sensitive traits, or
  keep the camera active after the experience stops.
- Test HTTPS, mobile orientation, mirrored coordinates, performance,
  keyboard/touch fallback, and blank/edit/embed permission behavior.

## GitHub or local repository import

Work only with a repository the user owns or is authorized to use.
Preserve its license and third-party notices where required. Inspect
source, routes, assets, environment variables, server assumptions,
and tests. Never expose a GitHub token, deploy key, `.env`, private
submodule, issue data, CI secret, or commit metadata that the user did
not ask to publish.

Map the client application into meaningful live Pieces. Upload
source-specific runtime assets; use pinned shared dependencies; map
persistent/server behavior to explicit BaaS resources or approved
services. Do not upload a repository archive or opaque `dist` page
and load it through an iframe. Validate the ZZD runtime independently
from the local development server.

## Public visual references

Observe public frontend behavior only. The user must own or be
licensed to publish the resulting code, copy, media, trademarks, and
likenesses. Do not access private APIs or credentials, clone an
identity, collect data, leave trackers, remove required notices,
bypass a trial/license/watermark, or claim that a percentage of visual
change creates legal permission. Replace source-specific identity/
assets unless rights are clear.

---

# Authentication and safety contract

## Available now: browser-first authorization

A third-party coding agent may operate the normal ZZD UI in a browser
the user controls. If the user is already signed in, the browser
sends the existing session automatically. The model must not read,
export, print, copy, request, or store cookies, session IDs, CSRF
tokens, passwords, payment data, private keys, or unrelated personal
information.

If sign-in is needed, let the user complete it. Do not ask the user
to paste a password or cookie into chat. UI mutations remain subject
to CSRF, ownership, rate, quota, visibility, and audit checks.

## External credentials

Never treat ZZD's legacy CLI secret as an MCP credential. A native
external tool transport should use user-created, scoped, expiring,
revocable credentials, optionally restricted to named Shows, with
mutation logs. Suggested future scopes are `shows:read`,
`shows:write`, `shows:publish`, `assets:write`, `baas:read`,
`baas:write`, and `sales:write`.

This public gateway is a read-only resource graph. It does not issue
credentials and does not claim that mutation tools already exist.
If the agent has no signed-in browser and no platform-issued scoped
credential, it must stop at a plan or guide the user through the UI.

## Require explicit confirmation

- publish, unpublish, or materially change access;
- submit, buy, remove, delete, or materially reprice a Sale;
- create, rotate, or revoke a credential;
- delete a Show, asset, BaaS collection, or user data;
- run a destructive BaaS migration;
- make a change that removes paid functionality or buyer access;
- send data to a new external party or enable sensitive permissions.

## Never expose or provide

- generic shell, SQL, staff, supervisor, container, or arbitrary
  target-binding access;
- ZZD deployment topology, keys, database schema/ORM recipes, worker
  queues, internal prompts, model routing, private evidence paths, or
  production algorithms;
- authentication bypass, privilege escalation, ownership bypass,
  rate-limit bypass, vulnerability exploitation, spam, scraping of
  private data, credential collection, or hidden beacons;
- raw private Piece/upload/prompt routes as a shortcut around access.

Operate only on resources the user owns or is authorized to change.
Use least privilege, redact tool output, return stable public IDs/URLs,
and keep an understandable change report.

---

# ZZD external-agent capability contract

Capability maturity must remain explicit.

## Available now

- this public, unauthenticated, read-only resource gateway;
- signed-in browser use of the normal Web AI IDE and product UI;
- Show runtime APIs such as `AppRuntime` and `SpaceClient` inside an
  appropriately bound Show.

## Not advertised as available

There is no public unauthenticated mutation endpoint and this page is
not a remote MCP JSON-RPC transport. Do not call proposed tool names
unless capability discovery from a future authenticated ZZD server
explicitly returns them.

## Stable resource names for MCP-compatible ingestion

- `zzd://platform/overview`
- `zzd://shows/schema`
- `zzd://shows/lifecycle`
- `zzd://shows/quality-standard`
- `zzd://assets/guide`
- `zzd://baas/guide`
- `zzd://sales/guide`
- `zzd://safety`

## Proposed future scoped tools

- `zzd.auth.status`
- `zzd.shows.list`, `zzd.shows.get`, `zzd.shows.create`
- `zzd.shows.update_metadata`, `zzd.shows.replace_pieces`
- `zzd.shows.validate`, `zzd.shows.publish`,
  `zzd.shows.unpublish`
- `zzd.assets.upload`, `zzd.assets.upload_from_url`,
  `zzd.assets.bind`
- `zzd.baas.get_context`, `zzd.baas.configure`
- `zzd.sales.create_draft`, `zzd.sales.submit`,
  `zzd.sales.status`

Any native implementation should expose narrow, typed operations;
owner/resource scopes; expiry and revocation; idempotency keys for
mutations; dry-run and diff where useful; audit logs; structured
errors; and confirmation hints. It must rebuild raw Piece source
safely, enforce access on every read, restrict asset bindings to
owned Shows, protect upload-from-URL against SSRF, and avoid generic
shell/SQL/internal lifecycle tools.

---

# Validation matrix and final handoff

Before saying "deployed", verify applicable rows:

- environments: blank desktop, blank mobile, real editor preview
  iframe, ordinary embed iframe;
- phases: loader, ready, settled, empty, denied, offline, error;
- scroll: start, intermediate checkpoints, end, and reverse;
- input: hover, pointer, click, keyboard, wheel/touch, drag/slider;
- state: menu, modal, detail, route, return, recursive next phases;
- media: image currentSrc/dimensions, video readiness/time/error,
  audio mute/autoplay fallback, canvas/WebGL nonblank and motion;
- runtime: console, page error, unhandled rejection, request failure,
  4xx/5xx, external/source hosts, anchors/forms, overflow;
- source: meaningful live Pieces own structure/content/state/motion;
- assets: all needed runtime files are managed, described, and bound;
- BaaS: allowed/denied, schema, idempotency, empty/error/job/realtime;
- rights/privacy: license, consent, no secrets or private data;
- publication: `private` and `hidden` match user intent;
- thumbnail: fresh final usable state, not loader or stale image.

A completed agent response should include:

- outcome and current lifecycle state;
- Show ID and title;
- edit, detail, blank, and embed URLs returned by ZZD;
- architecture and Piece map;
- uploaded assets, bindings, dependencies, and remaining external
  runtime dependencies;
- BaaS resources/services and access behavior, if any;
- validation environments, meaningful interactions, console/network
  status, and notable fixes;
- public/unlisted/private status;
- Sale/listing status, only if requested;
- remaining risks, known differences, and rollback/maintenance notes.

Do not claim success if a required environment or meaningful state
was not checked. Say exactly what remains and keep the Show private/
hidden when the quality gates do not pass.