[Agentic Preview task] Publish the versioned site-tool contract and bounded wire format

[Flow-Fly]

Parent

#553 — Expose the public Site Tool Facade and WebMCP fallback

Sources of truth

• [Spec] Agentic Preview — creative agents build complete pixel-art assets #523 — approved Agentic Preview specification
• [Agentic Preview capability] Public site tools #534 — Public site tools
• [Agentic Preview delivery slice] Expose the public Site Tool Facade and WebMCP fallback #553 — delivery brief and shared stop gates

Planning baseline

Inspected at origin/develop@e94f52e4f8c22f78db93688f5dab3ad95430a652. Revalidate live origin/develop and create a fresh isolated worktree before editing.

Outcome

Publish one versioned, catalogue-backed bootstrap and site-tool contract that an external client can validate without learning anything about local projects.

This is task 1 of 4 in delivery slice #553 and the first focused commit in the same PR.

Acceptance criteria

• Define a compact Bootstrap Guide for discovery, version negotiation, session request/status, observation before writes, transaction proposals, run control/recovery, package preparation, and stable error recovery.
• Define typed public envelopes for the coherent facade operations named by [Agentic Preview delivery slice] Expose the public Site Tool Facade and WebMCP fallback #553 without exposing one internal command per tool or an untyped executor.
• Publish valid JSON Schemas for every input and result. Derive them from or mechanically verify them against catalogue identifiers and limits plus runtime validators; introduce no second command catalogue.
• Define catalogue/facade compatibility ranges: major mismatch blocks writes, minor mismatch omits unavailable capabilities, and failures tell the client how to recover.
• Define bounded JSON result/error envelopes with stable refusal, revision-conflict, cancellation, budget, and incompatibility outcomes.
• Choose and document one bounded, versioned representation for binary observations and prepared artifacts, or an opaque same-session retrieval handle. The contract covers maximum size, digest, byte count/agreement, expiry where applicable, and content-grant enforcement.
• Contract tests reject schema drift, unknown/oversized fields, incompatible versions, and invalid binary/result envelopes.

Write boundaries

Own the public bootstrap, facade type, schema, version, and wire-contract modules plus their focused tests and support documentation. Catalogue identifiers, existing runtime validators, and limits remain the source of truth.

Leave runtime session approval, Creative Run composition, WebMCP registration, application lifecycle, backend code, and production telemetry to the other tasks or outside this slice.

Non-goals

Exact tool count or file layout prescribed by the issue, a second schema catalogue, editor commands, project persistence changes, a server API, real agent calls, or live deployment.

Stop gates

Stop if schema parity requires duplicating command definitions, if the wire contract cannot be bounded and content-grant checked, or if compatibility requires silently accepting an unknown major shape.

Verification

Add focused contract tests for valid round trips and materially distinct schema/version/size failures. Run the delivery-slice verification from #553 after the complete four-task head.

Delivery record — #553

Technical delivery merged into develop through PR #617. Reviewed candidate: a5a5869eeca274a09c9864212e5e29ff368fabd3. Integration commit: d6d4042bddba54a050442534c32e97da9d8a8c07. Astra Medium implemented the slice; Astra High finalizer pass 1 repaired five findings, and a fresh Astra High pass 2 approved the unchanged corrected head.

Verification: 978 standard unit tests, 129 Chromium tests, typecheck, lint, build, explicit-baseline Fallow (18 files), whitespace checks, and CI 34454210254 passed. One native-only test is explicitly skipped; coverage was not collected.

The deterministic fallback and supported-shape conformance are verified. Installed Chromium lacks the native API; activated Canary 153 does not supply the required invocation cancellation signal and is refused before effects. Actual deployed pixel-forge.app/external-agent proof remains unclaimed and owner-controlled under #524. No deployment or promotion to main occurred. The existing owner release checklist in docs/agents/site-tools.md remains open.