@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.6

package/design-system/references/v3/manifest.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "release": "2026-10-06.2",
+  "status": "curated; technically validated; not human-approved taste data",
+  "selectorVersion": "task-expression-complementarity-2",
+  "catalog": {
+    "path": "catalog.json",
+    "sha256": "b386d289ce4ffafa066df487416f7782915eec3a3dcf41575d2694943cb9caaa"
+  },
+  "labeledPreferenceData": false
+}

package/docs/CLI.md

@@ -0,0 +1,299 @@
+# Vitris Unified CLI & Automation Contracts
+
+The `vitris` CLI (`@tryvitris/website-harness`) provides a unified, operator-friendly command line interface and automation harness for creating, running, refining, evaluating, sharing, and deploying static websites.
+
+---
+
+## 1. Installation & Binary
+
+After the first registry release, install as a dependency or run via `npx`. Until then use the tarball instructions in [distribution](DISTRIBUTION.md):
+
+```bash
+npm install --save-dev @tryvitris/website-harness
+npx vitris --help
+```
+
+Within the `@tryvitris/website-harness` repository itself:
+```bash
+npm run build:cli
+node bin/vitris.js --help
+```
+
+---
+
+## 2. Command Reference
+
+### `vitris doctor`
+Runs environment and preflight health checks.
+```bash
+vitris doctor [--site <dir>] [--provider cloudflare] [--operation pages|deploy] [--json]
+```
+Checks:
+- Node.js runtime version (`>= 24`)
+- Git availability and worktree cleanliness
+- Wrangler installation and authentication
+- Site configuration (`launch.json`, `package.json`, `agent/graph.yaml`, `agent/STATE.json`)
+- Active process lock (`agent/RUN.lock`)
+- Pending transaction recovery journals (`.journal.json`)
+- Cloudflare dual authentication (`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` or interactive OAuth via `wrangler whoami`)
+- Scoped resource validation (Pages vs D1/R2)
+
+---
+
+### `vitris site create`
+Scaffolds a new customer or project site repository with the workflow graph, agent kit, and configuration.
+```bash
+vitris site create --dir <target-path> --slug <site-slug> [--name <display-name>] [--from <source-url>] [--owner <email>] [--blank] [--force] [--dry-run]
+```
+Options:
+- `--dir`: Target directory for the new site.
+- `--harness`: Dependency spec (defaults to this package's exact version); before registry publication, use a tarball or explicit `file:` path relative to the new site.
+- `--backend-origin`: Optional backend URL, saved as `launch.json.backendOrigin`. Legacy `--kernel` and `--kernel-origin` flags remain accepted.
+- `--slug`: Unique identifier for the site (used in Cloudflare Pages project names).
+- `--name`: Human-readable site name.
+- `--from`: Live website URL to harvest and crawl.
+- `--template`: Catalog template ID, display name, or hosted demo/preview URL. Records the supplied choice and continues through local preview without the selection artifact or adaptation/representative-feedback prompts. The choice is bound after harvest and media auditing so branding uses captured evidence. This route delegates section adaptation to the agent and uses existing, harvested, or stock media; AI image generation is disabled. Reference inventory, critic, fidelity, browser, and quality gates still apply. Missing content remains a visible fill-in and blocks launch.
+- `--template-release`: Optional catalog revision for an ID/name; a hosted URL pins its revision automatically.
+- `--content` / `--content-file`: Additional business content and instructions, supplied inline or from a UTF-8 file (up to 256 KB; choose one). Wording is preserved in `onboarding/additional-content.md`, survives harvesting, and is included in authoring and review dependencies.
+- `--owner`: Site owner contact email.
+- `--blank`: Initialize without a live source URL (skips initial crawl).
+- `--force`: Overwrite existing files in non-empty directory.
+- `--dry-run`: Preview directory scaffolding actions without touching disk.
+
+Provide the source, template, and extra content together:
+
+```bash
+vitris site create --dir ../acme --slug acme --from https://old-site.example --template "Still & Field" --content-file ./acme-notes.md --harness file:../vitris-harness
+```
+
+Open the new site in your coding agent and continue the prepare/work/complete loop with `npm run go` until local preview is ready. The same inputs work with `vitris-create-site` and `npm run create-site -- ...`. When the initial chat already names a template and supplies content, the agent should pass them at setup and continue the workflow without asking the user to select that template again.
+
+---
+
+### `vitris run`
+Executes single-variant or multi-variant site generation workflows.
+```bash
+vitris run [--site <dir>] [--variants 1|5] [--theme <theme-name>] [--theme-scope all|one] [--restart-from <node>] [--reason <text>] [--jev-mode off|shadow|assist] [--compact-packets] [--dry-run]
+```
+Options:
+- `--site`: Path to the site repository (defaults to `.`).
+- `--template`, `--template-release`, `--content`, `--content-file`: The same direct inputs as site creation, also accepted by `npm run go -- ...`. Supply them at run start or preparation, after finishing/canceling any active stage. An identical request preserves the selection identity and history; a revised choice uses normal downstream invalidation. Later explicit picker/chat choices take precedence until a new direct request is supplied. Dry runs validate inputs without saving them. Redesign inputs are rejected in preserve mode.
+- `--variants`: Number of design directions to generate (`1` or `5`). Default: `1`.
+- `--theme`: Explicit design theme or direction.
+- `--theme-scope`: In 5-variant runs, apply theme to `all` variants or `one` variant.
+- The active host supplies the author/model. Legacy `--adapter` and `--model` options do not provide unattended author execution. Configure an independent representative-quality reviewer explicitly in `agent/adapter.reviewer.json` if needed.
+- `--restart-from`: Invalidate and restart from a specific graph node.
+- `--reason`: Required rationale when using `--restart-from`.
+- `--jev-mode`: Bounded semantic decision mode (`off`, `shadow`, `assist`). Default: `off`.
+- `--design-assist`: One preset that sets mode to `assist` and enables `creativeScoring`, `componentSelection`, and `compositionCheck` when those capabilities were not explicitly set. `--jev-mode off` and `--no-jev` win. Explicit `"creativeScoring": "off"` in `agent/jev.json` stays off. This preset does not enable `workOwnership: delegated`.
+- `--no-jev`: Force mode `off`.
+- `--compact-packets`: Enable bounded context packet slicing and coverage manifests.
+- `--dry-run`: Preview workflow execution plan without launching agent loops.
+
+---
+
+### Jev Decision Service & Evaluation Tooling
+
+#### Usage Audit:
+Audit recorded tokens, cache reads, and provider stream events across site runs:
+```bash
+node scripts/audit-workflow-usage.ts --runs <runs-directory> [--out <output-json>]
+```
+
+#### Evaluation Harness:
+Run comparative benchmarking across the 3 treatments (baseline, compact packets, compact + Jev):
+```bash
+node scripts/eval-jev.ts [--mock|--live] [--runs <count>] [--out <output-json>]
+```
+
+#### Packet Expansion:
+Expand a partitioned context item on demand during active-agent execution:
+```bash
+node scripts/eval-site.ts --site <dir> --expand-packet <expansion-id> --node <node-id>
+```
+
+---
+
+### `vitris refine`
+Performs targeted, post-launch site refinements using intelligent scope routing, layout preservation, and verifiable regression constraints.
+```bash
+vitris refine [--site <dir>] --request "<instruction>" [--scope copy|direction|pages|business] [--force] [--dry-run]
+```
+Options:
+- `--request`: Natural language change request from operator.
+- `--scope`: Optional explicit scope override. If omitted, the classifier automatically routes to `copy`, `direction`, `pages`, or `business`.
+- `--force`: Bypass non-critical gate warnings.
+- `--dry-run`: Preview classified scope, rationale, and proposed change plan.
+
+Key Invariants:
+- Never restarts harvest.
+- Unchanged sections and navigation structure are preserved with AST-level integrity.
+- Recoverable file replacement with rollback on validation failure.
+- Violating navigation links or dropping media triggers fail-closed rejection (exit code 4).
+
+---
+
+### `vitris status`
+Inspects the current state of a site workflow or design run.
+```bash
+vitris status [--site <dir>] [--run <run-id>] [--json]
+```
+Reports active node, attempt counts, preview status, and lock ownership without altering progress or acquiring locks.
+
+---
+
+### `vitris resume`
+Resumes a paused, interrupted, or checkpointed workflow.
+```bash
+vitris resume [--site <dir>] [--run <run-id>] [--dry-run]
+```
+
+---
+
+Production browser verification defaults to a one-hour subprocess timeout. Set `VITRIS_BROWSER_TIMEOUT_MS` to a bounded integer from 1000 to 86400000 milliseconds when the full route and motion suite needs a different limit. The outer production verifier allows an additional minute for preflight to seal its report. This changes only the runtime allowance; every browser, accessibility, motion and performance check still runs.
+
+### `vitris cancel`
+Safely terminates an active workflow run, releases process locks (`agent/RUN.lock`), and cleans up stale temporary files.
+```bash
+vitris cancel [--site <dir>] [--run <run-id>]
+```
+
+---
+
+### `vitris feedback import`
+Imports structured stakeholder feedback for multi-variant design review.
+```bash
+vitris feedback import [--site <dir>] [--run <run-id>] --file <feedback.json> [--dry-run]
+```
+
+---
+
+### `vitris synthesize`
+Synthesizes stakeholder feedback across 5 variants into a unified, high-quality final site candidate.
+```bash
+vitris synthesize [--site <dir>] [--run <run-id>] [--feedback <feedback.json>] [--dry-run]
+```
+
+---
+
+### `vitris verify`
+Evaluates build verification and all deterministic graph gates.
+```bash
+vitris verify [--site <dir>] [--json] [--dry-run]
+```
+Returns structured gate summaries and exit code `0` (pass) or `1` (gates failed).
+
+---
+
+### `vitris preview`
+Serves the local static `dist/` bundle with Single-Page Application (SPA) routing, migration redirect emulation, and cookie compliance sandboxing.
+```bash
+vitris preview [--site <dir>] [--port <number>] [--dry-run]
+```
+
+---
+
+### `vitris deploy`
+Builds a verified production bundle and deploys it to Cloudflare Pages.
+```bash
+vitris deploy [--site <dir>] [--provider cloudflare] [--environment preview|production] [--branch <branch>] [--dry-run]
+```
+Workflow:
+1. Scoped preflight check verifying Cloudflare credentials (`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` or `wrangler login`).
+2. Build verified static `dist/` bundle (aborts if build fails or is dirty).
+3. Executes `npx wrangler pages deploy dist --project-name=<slug>`.
+4. Executes automated remote smoke check against the deployed `*.pages.dev` URL.
+
+---
+
+### `vitris share`
+Launches an authenticated preview or interactive multi-variant comparison review server.
+```bash
+vitris share [--site <dir>] [--run <run-id>] [--port <number>] [--dry-run]
+```
+
+---
+
+## 3. Automation Contracts
+
+The `vitris` CLI is designed for programmatic execution in CI/CD pipelines, agent harnesses, and orchestration scripts.
+
+### Stable Exit Codes
+
+| Code | Constant | Meaning |
+| :---: | :--- | :--- |
+| `0` | `SUCCESS` | Command completed successfully. |
+| `1` | `GATES_FAILED` | Graph evaluation or quality verification failed. |
+| `2` | `CONFIG_OR_CLI_ERROR` | Missing or invalid arguments, configuration, or environment. |
+| `3` | `PRECONDITION_FAILED` | Directory already exists, required predecessor not finished. |
+| `4` | `REFINEMENT_REJECTED` | Proposed refinement caused a regression (e.g. dropped route or missing asset). |
+| `5` | `ABORTED` | Execution canceled via signal (`SIGINT`, `SIGTERM`, `AbortSignal`). |
+| `6` | `DEPLOYMENT_FAILED` | Cloudflare Pages deployment or remote smoke check failed. |
+
+### Structured Output Modes
+
+`--json` and `--events` are **strictly mutually exclusive**:
+- `--json`: Emits exactly one valid JSON envelope to `stdout` upon completion.
+- `--events`: Streams timestamped NDJSON events (`{"type": "...", "timestamp": "...", ...}`) to `stdout`.
+
+#### Standard JSON Envelope Schema
+```json
+{
+  "ok": true,
+  "exitCode": 0,
+  "summary": "Human-readable summary message",
+  "data": {},
+  "failures": [],
+  "error": "Error message if ok is false"
+}
+```
+
+### Security & Credential Isolation
+
+- Tokens, passwords, and API secrets are **never** logged to stdout, stderr, or event streams.
+- Credentials are **never** written into `launch.json`, prompts, or artifacts.
+- Subprocesses receive environment variables directly via secure process inheritance.
+
+---
+
+## 4. Programmatic TypeScript API
+
+The CLI features are also exported as an ES Module TypeScript API:
+
+```typescript
+import {
+  createSite,
+  runDoctor,
+  runSite,
+  refineSite,
+  statusSite,
+  resumeSite,
+  cancelSite,
+  importFeedback,
+  synthesizeSite,
+  verifySite,
+  previewSite,
+  deploySite,
+  shareSite,
+  EXIT_CODES,
+} from "@tryvitris/website-harness/cli";
+
+// Example: Run doctor preflight
+const doctorResult = await runDoctor({ site: "./my-site", provider: "cloudflare" });
+if (!doctorResult.ok) {
+  console.error("Doctor failed:", doctorResult.summary);
+}
+
+// Example: Refine copy with AbortController
+const controller = new AbortController();
+const refineResult = await refineSite({
+  site: "./my-site",
+  request: "Update homepage headline to emphasize local reliability.",
+  signal: controller.signal,
+});
+```
+
+
+### Reproducible harness checks and trials
+
+`npm run test:freeze` runs typecheck, CLI build, the full tests, a packed install/build smoke check, and source archive round-trip verification. It writes a new baseline under `artifacts/official-test/`. See [official test protocol](OFFICIAL-TEST.md) for trial creation, active-agent continuation, spend limitations, and outcome labeling.

package/docs/CLOUDFLARE.md

@@ -0,0 +1,53 @@
+# Use your own Cloudflare account
+
+Local authoring, compilation and preview require no Cloudflare account or API keys. Hosting is an explicit later operation. These examples provision resources in your own account.
+
+## Static customer websites
+
+Create a Cloudflare account. From the customer directory run `npx wrangler login`, check the account with `npx wrangler whoami`, and run `npx wrangler pages project create YOUR_PROJECT`. Set `launch.json.pagesProject` to that name. CI uses your own `CLOUDFLARE_ACCOUNT_ID` and an account-scoped token with Pages Edit access, stored in protected CI secrets. Never put a token in launch.json, HTML, assets or Git.
+
+Run `npm run build` and `npm run preflight` locally. Run `npm run deploy` only when you intend to upload. Accept the hosted preview before separate custom-domain and DNS changes. Preservation mode supports temporary previews; follow PRESERVE.md for its narrower contract.
+
+## Optional backend Worker
+
+Copy `node_modules/@tryvitris/website-harness/cloudflare/wrangler.jsonc` to a dedicated backend directory. Set `main` to the installed harness's `bin/cloudflare/backend.js` and `migrations_dir` to its `migrations` directory, relative to the copied config. Install Wrangler there. Choose your own Worker, database, bucket, namespace, workflow and analytics dataset names.
+
+After `npx wrangler login`, provision your resources:
+
+```sh
+npx wrangler d1 create my-vitris
+npx wrangler kv namespace create KV
+npx wrangler r2 bucket create my-vitris-assets
+```
+
+Replace the D1 and KV placeholders with the returned IDs. Account selection uses your login or your own CLOUDFLARE_ACCOUNT_ID. Initialize the database explicitly with `npx wrangler d1 migrations apply my-vitris --remote --config wrangler.jsonc`.
+
+Generate your own long random session secret and run `npx wrangler secret put SESSION_SECRET --config wrangler.jsonc`. Keep DEV_LOGIN unset in production. Optional email/GitHub integrations use your credentials through `wrangler secret put`. Worker-managed Pages publication additionally needs your own CF_ACCOUNT_ID, narrowly scoped CF_API_TOKEN, and matching PUBLISH_ATTESTATION_SECRET in the Worker and protected site CI. Direct static Pages hosting does not require these Worker features.
+
+Apply all migrations, including `0005_auth.sql`, before upgrading the Worker. This upgrade intentionally invalidates old KV sessions and magic links. Production creates no demo users: provision legitimate tenant/user/membership rows through your own controlled D1 administration, using your actual owner/operator email and generated UUIDs. Never import the local demo operator into production.
+
+Configure production sign-in delivery with either GMAIL_SA_CLIENT_EMAIL, GMAIL_SA_PRIVATE_KEY and GMAIL_IMPERSONATE (or MAIL_FROM), or MAIL_API_KEY and MAIL_FROM for Resend. Keep VITRIS_BACKEND_ORIGIN set to the HTTPS administration origin. Missing mail configuration returns an unavailable response; failed delivery never exposes a sign-in link. Verify delivery to your own account before onboarding users.
+
+### Private GitHub site previews
+
+Set PREVIEW_HOST_SUFFIX to a dedicated domain such as `previews.your-domain.example` and route `*.previews.your-domain.example` to this Worker using your own DNS, Worker routes and TLS configuration. Reserve that suffix exclusively for Vitris previews. APP_HOST, OPS_HOST and the backend origin must remain outside it. A tenant with slug `acme` renders at `https://acme.previews.your-domain.example/preview/acme/`; no administration or APIs run on that host.
+
+Open `/preview/acme/` from the signed-in admin app. Owners can open only their own tenant; operators can open any registered tenant. The app redirects using a signed 15-minute access handoff, which becomes a host-only HttpOnly cookie before any customer HTML renders. Keep that handoff private. Preview requests verify the session in D1, enforce the selected GitHub branch and stop working after logout or expiry. Reopen from the admin app to renew access. With no separate preview suffix, hosted previews remain unavailable. Public customer sites still deploy independently to Pages; local CLI previews are unchanged.
+
+### Validate and launch
+
+Validate without deploying using `npx wrangler deploy --dry-run --config wrangler.jsonc`. Deploy explicitly when ready and set the resulting URL in the customer's launch.json.backendOrigin. Contact form registration, allowed origins, delivery and Turnstile setup are separate; follow CONTACT-FORMS.md and test delivery before launch.
+
+Optional template-library and isolated form-test configs also use your resources. The public Vitris demonstration library is a separate hosted service; browsing it conveys no credentials or ownership of its assets.
+
+## Credentials
+
+Keep local .dev.vars and .env files ignored. Use Cloudflare secrets and protected CI secrets in production. Copy public configuration, never another operator's credential files. Wrangler's authentication cache stays outside the package. See SECURITY.md for release auditing.
+
+Cloudflare references: [configuration](https://developers.cloudflare.com/workers/wrangler/configuration/) and [secrets](https://developers.cloudflare.com/workers/configuration/secrets/).
+
+## Optional repository previews
+
+The Worker preview GitHub workflow is disabled by default. A repository owner may opt in with the `VITRIS_WORKER_PREVIEW_ENABLED=true` repository variable after provisioning their own isolated preview resources and GitHub secrets. No account credentials are included in source.
+
+Template library maintainers also configure their own `VITRIS_TEMPLATE_ORIGIN`, `VITRIS_TEMPLATE_BUCKET`, R2 S3 endpoint, and access credentials; see `agent/refs/template-library.md`. Static-site users can use the public gallery without those credentials.

package/docs/CONTACT-FORMS.md

@@ -0,0 +1,161 @@
+# Shared Vitris contact forms
+
+One shared Worker serves preserved and generated/custom websites. Each site keeps its authored layouts, labels and controls. There is no structured website editor. The public `/api/leads` transport remains, but inferred Origin/Referer tenants, preview slugs, wildcard CORS and the old KV lead counter no longer authorize submissions. Existing leads and unrelated Gmail/Resend workflows are preserved.
+
+## Configuration and migration
+
+Apply additive migration `0004_contact_forms.sql` after the existing migrations. Back up D1 first for an authorized rollout. It does not enable any existing form or modify old lead rows/site configuration. Old assets without a registered `form_id`, retry UUID and challenge token receive a configuration error. Upgrade their assets with the setup workflow; keep a site disabled until verification is complete. Unconverted old forms need an accessible listed contact option during this transition.
+
+The server stores `contact_forms.config_json`: stable global form ID, tenant ID, `disabled | test | live`, exact origins, field schema/mappings, recipients, and Turnstile sitekey/action/secret reference. Public `launch.json.forms` contains only `{ id, pagePath, index, sitekey, action }`. Backend origin alone enables neither submission nor live notifications. New sites have empty bindings and show a preview notice. Server mode decides acceptance; browser attributes cannot activate live delivery.
+
+`vitris forms inspect --site SITE --json` builds and inventories forms. Only `data-lead-form` or recognized legacy `emailSendButton` contact forms qualify. Search/login/payment forms remain unrelated. File inputs, unknown hidden fields, custom submission handlers, unsupported control types, duplicate scalar names and unsupported multiple selects are reported; setup fails instead of discarding fields. Capture refuses unrelated interactive forms until an explicit preservation adapter exists. Attachments and visitor autoresponders are outside v1.
+
+Setup infers bounded schemas from every named supported control. It recognizes `number`, `telephone`, `phone_number`, `phoneNumber` and `phone` as phone aliases, retaining their HTML names. Textarea limits can preserve the legacy 5,000-character field. All fields remain in the submission snapshot and notification; name/email/phone/message mappings also populate the existing production leads table. Choice values must match configured options; checkbox groups preserve multiple values. Schemas have at most 32 fields, 40 options/values per choice field, 8,000 characters per field and five server-configured recipients. A required visitor email mapping is mandatory. For deliberate schema/label/mapping changes, use `--forms-config FILE` with a `{forms:[...]}` array containing complete server configurations plus `pagePath` and `index`. Keep this operator file outside public assets. Stabilize authored form IDs explicitly when reordering forms.
+
+## Local sandbox
+
+`wrangler.forms-test.jsonc` has local resource placeholders, public test-only credentials, no email binding, and `FORMS_SANDBOX=1`, which forbids live activation. Never deploy it unchanged. Use a separate persistence directory; none of these commands applies a remote migration:
+
+```powershell
+npx wrangler d1 migrations apply vitris-forms-test --local --config wrangler.forms-test.jsonc --persist-to artifacts/contact-forms/wrangler-state
+npx wrangler dev --local --config wrangler.forms-test.jsonc --persist-to artifacts/contact-forms/wrangler-state --port 8789 --test-scheduled
+```
+
+In another terminal, serve a **copy** of the acceptance project on a fixed port, then register that exact origin:
+
+```powershell
+$env:VITRIS_FORMS_SETUP_TOKEN = 'local-test-setup-key-never-use-in-production'
+node bin/vitris.js forms inspect --site artifacts/contact-forms/dwperrotta-local --json
+node bin/vitris.js forms setup --site artifacts/contact-forms/dwperrotta-local --tenant dw-test --backend-origin http://127.0.0.1:8789 --origins http://localhost:4173 --mode test --test-keys --json
+# Review artifacts/forms/setup-plan.json, then reconcile:
+node bin/vitris.js forms setup --site artifacts/contact-forms/dwperrotta-local --tenant dw-test --backend-origin http://127.0.0.1:8789 --origins http://localhost:4173 --mode test --test-keys --apply --json
+node bin/vitris.js forms status --site artifacts/contact-forms/dwperrotta-local --tenant dw-test --backend-origin http://127.0.0.1:8789 --json
+```
+
+Use `vitris preview --site SITE --port 4173` to serve the copy. The scheduled test endpoint is Wrangler's `/__scheduled?cron=*/5%20*%20*%20*%20*`. It captures test notifications in D1. Do not bind remote mail to this sandbox.
+
+The `--test-keys` preset prepares controlled tests with action `test`; it does not provide manual end-to-end acceptance against the public Siteverify endpoint. In the actual October 9 smoke check, Cloudflare accepted its public dummy token but returned hostname `example.com` with no action. The service correctly rejected that result for the configured local hostname/action. Official dummy tokens can also repeat; this service's replay guard rejects reuse of an accepted token. Use a real widget with server mode `test` for manual end-to-end acceptance, or the deterministic unique-token fixture in the browser tests. Do not weaken hostname/action verification or replay protection for dummy keys. The automated browser fixture calls the real submission handler and D1, but substitutes Siteverify and widget execution; it does not validate Cloudflare's live challenge execution.
+
+## Provisioning and permissions
+
+`forms setup` writes a reviewable `artifacts/forms/setup-plan.json`. Without `--apply`, it creates no cloud resources or server configuration. `--apply` registers an authorized tenant if absent, reconciles configurations, writes public frontend bindings while preserving other launch settings, builds the site, and fetches status. Same inputs reuse IDs/resources. Omitted forms are retained; disable them explicitly rather than deleting history. Default setup mode is disabled. Setup supports only disabled/test; live activation uses the reviewed configuration API.
+
+The backend uses tenant-scoped automation credentials in the Worker secret `FORMS_SETUP_TOKENS`, a JSON object mapping tenant IDs to separate random tokens of at least 32 characters. The CLI receives one token through `VITRIS_FORMS_SETUP_TOKEN`. These credentials permit configuration, status and retry **only for that tenant**. Do not use the existing global deploy token. Owner sessions also work with the API; mutation requests require the backend's exact Origin as CSRF protection. Customer-dashboard retry controls have the same ownership/Origin checks. No operator API exposes a Turnstile secret.
+
+Authenticated Cloudflare APIs work unattended; an available Cloudflare management MCP may perform the same operator actions, but is not a runtime dependency. No Cloudflare management MCP was connected during this implementation. Configure `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` for API provisioning. Required account permissions depend on the operation: Turnstile Read/Edit for widget inventory/allocation, Workers Scripts Read/Edit for Worker inspection/deployment/secrets, D1 Read/Edit for backup/resource creation/migrations, and KV/R2 permissions for the existing Worker bindings. Pages Edit is required for a separate preview deployment. Vitris sender onboarding requires access to the Vitris-owned zone, DNS Edit and Email Sending Edit; customer DNS is not involved. Verify token type and resource scope: account tokens use `/accounts/ACCOUNT/tokens/verify`, user tokens use `/user/tokens/verify`. Listing access alone does not prove write permission or Email Service availability.
+
+Use `--cloudflare --worker ISOLATED_WORKER` to plan/reconcile Turnstile widgets. The command lists existing resources first. It pools exact hostnames under names `vitris-forms-pool-N`, reuses matching/capable managed widgets, leaves unmanaged widgets alone, and stops at free-plan capacity. Run account-wide pool updates serially; Cloudflare widget updates do not offer a cross-process allocation transaction. Retried setup reconciles partial completion. Supply the **complete current** `FORMS_TURNSTILE_SECRETS` JSON map in the operator environment when applying; `{}` is appropriate only for a new isolated Worker. The command fetches managed widget secrets and merges them into that map before writing the Worker secret. This prevents silently erasing other secret references. Never print or save this map in site assets.
+
+Example plan (no cloud writes):
+
+```powershell
+node bin/vitris.js forms setup --site SITE --tenant TENANT --backend-origin https://ISOLATED-WORKER.workers.dev --origins https://HASH.PROJECT.pages.dev --mode test --cloudflare --worker ISOLATED-WORKER --json
+```
+
+Approve hashed preview URLs explicitly after deployment. Never approve `*.pages.dev`. The form origin registry prevents two tenants owning the same exact origin, and registration checks existing hostname ownership. The form service reads authoritative D1 configuration on each submission; it does not use the hostname KV cache for authorization. Different sites sharing a widget still have separate form/origin/action validation and database ownership.
+
+## Worker readiness and Email Service
+
+Keep these settings server-side:
+
+| Setting | Purpose |
+| --- | --- |
+| `FORMS_TURNSTILE_SECRETS` | JSON map of secret references to Turnstile secrets |
+| `FORMS_ABUSE_SECRET` | Random 32+ character HMAC secret for source counters; no raw IP storage |
+| `FORMS_SETUP_TOKENS` | Separate tenant-scoped provisioning tokens |
+| `FORMS_FROM` | Authenticated Vitris sender address; never supplied by the browser |
+| `FORMS_SENDER_READY=1` | Operator attestation after domain authentication/account access verification |
+| `FORMS_EMAIL` | Cloudflare Email Service `send_email` binding |
+| `FORMS_TEST_EMAIL`, `FORMS_TEST_RECIPIENT` | Optional restricted operator sink; requires sandbox and authenticated sender |
+| `FORMS_SANDBOX=1` | Prevent live activation on an isolated test backend |
+
+Live readiness requires all mail settings, recipients, non-dummy Turnstile keys/secrets and approved HTTPS origins. Test readiness still requires challenge and abuse configuration. Test notifications are rendered/captured in D1 by default; the customer `FORMS_EMAIL` binding is never used for test records. A separately configured sandbox operator sink can send explicitly authorized test messages as described below. Missing settings appear in `forms status` and the leads dashboard and block live configuration/acceptance. The sender-ready flag is an operator attestation, not an automatic DNS or inbox-delivery check.
+
+After **separate approval** for a shared-backend rollout, add a restricted binding to its reviewed Wrangler deployment configuration:
+
+```json
+{
+  "send_email": [{
+    "name": "FORMS_EMAIL",
+    "allowed_sender_addresses": ["forms@YOUR-VITRIS-DOMAIN"],
+    "allowed_destination_addresses": ["APPROVED-RECIPIENT@example.com"]
+  }]
+}
+```
+
+Use the structured `send()` builder with a Vitris From address and validated visitor email as `replyTo`. Recipients and field-schema labels come from the server-side acceptance snapshot. The binding must permit those recipients; do not assume an unrestricted binding can send to arbitrary addresses on every plan. Cloudflare's current sending guide requires Cloudflare DNS and sender-domain onboarding with authentication/bounce records. Check SPF, DKIM, DMARC, account availability and recipient restrictions before attesting readiness. Do not replace the existing Gmail/Resend login/operator mail workflows. [Sending setup](https://developers.cloudflare.com/email-service/get-started/send-emails/), [binding restrictions](https://developers.cloudflare.com/email-service/configuration/send-bindings/), [Workers API](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/).
+
+As checked October 9, 2026, sending is documented as beta. Arbitrary-recipient sending requires Workers Paid; the account includes 3,000 outbound emails/month, then $0.35/1,000. Verified-destination sends are free under the documented conditions. Include the Workers subscription plus D1 reads/writes/storage in budgeting; the new scheduler runs every five minutes (about 8,640 runs per 30 days) and handles at most 20 notifications per invocation. At low contact-form volume mail usage should normally fit the included allowance, but provider acceptance/bounces can count toward billing. [Email pricing](https://developers.cloudflare.com/email-service/platform/pricing/).
+
+Turnstile Free currently permits 20 widgets/account, 10 hostnames/widget and unlimited challenges. Pooling permits several sites per widget; server authorization remains exact per form. Reserve capacity for staging and customer origins instead of allocating a widget per form. [Current Turnstile plans](https://developers.cloudflare.com/turnstile/plans/).
+
+## Acceptance, retry and delivery semantics
+
+Requests require URL-encoded content, at most 32 KiB including chunked bodies, exact registered form/origin ownership, valid bounded fields and a v4 idempotency UUID. Browser-controlled recipient/sender fields and unknown fields are rejected. Honeypots reject without creating records. D1 conditional UPSERTs enforce 10 attempts/source/tenant and 100 attempts/tenant per ten-minute window atomically; these are fixed-window limits, not sliding limits. Failed challenge attempts consume budget. Keep Cloudflare edge protections for volumetric abuse; per-form validation is not a network-DDoS defense.
+
+Siteverify must succeed with the configured action and requesting origin's exact hostname. Tokens are single-use/short-lived; the browser refreshes them after attempts. A token-specific deterministic UUID is used for Siteverify retries. A new challenge token does not reuse the old verification verdict. Accepted tenant/form/idempotency receipts are checked before another challenge verification; matching accepted retries return the existing receipt, while changed values return 409. A database-unique challenge digest also prevents accepted-token reuse with another submission key. [Siteverify contract](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/).
+
+The `form_submissions` insert, outbox, compatible production lead and production conversion are one D1 transaction through an insertion trigger. Acknowledgement means durable acceptance, not email delivery. Production conversions are inserted once in D1; test submissions never enter production leads, conversions or Analytics Engine. Both modes preserve all configured fields.
+
+The five-minute cron processes bounded batches with conditional claims, five-minute leases, eight attempts and exponential backoff (60 seconds, doubling to a six-hour cap). Abandoned leases are reclaimable; an abandoned final attempt becomes a visible terminal failure. Invalid sender/recipient/configuration errors become terminal immediately. Provider calls have a 30-second processing deadline; timeouts are ambiguous because the binding cannot cancel an in-flight send. The original daily analytics rollup still runs at `0 6 * * *`. Processing does not rely on `waitUntil`.
+
+Statuses are `pending`, `processing`, `captured` (test), `accepted` (provider message ID/time), and `failed` (bounded actionable error code). The leads dashboard shows all fields, readiness and notification status, with a separate test view. Retry controls cannot target another tenant. Changing the configured mode pauses unmatched pending jobs; test jobs never become live jobs. Acceptance-time recipients are immutable snapshots; review pending jobs before changing recipient policy.
+
+The provider interface receives the stable outbox ID for providers supporting idempotency. The current documented Cloudflare Workers send builder has **no idempotency parameter**; no invented header/key is sent. A crash or ambiguous timeout after provider acceptance but before the database update can cause a duplicate send on retry. A 30-second deadline or lease is not proof that an earlier send was canceled. Terminal manual retries also carry that risk. No exactly-once email or inbox-delivery guarantee is made. `accepted` is distinct from confirmed mailbox delivery; bounce/delivery webhooks are not implemented in v1. Use Cloudflare email logs when investigating provider acceptance and recipient delivery.
+
+Leads keep the existing retention policy (no automatic lead deletion). Archiving does not delete PII. Deleting a production lead deletes its submission/receipt/outbox snapshot through a trigger; analytics retain their existing 90-day raw/400-day aggregate policy. Test submissions/captures expire after seven days, and rate counters after their window. Deleting an idempotency receipt removes replay protection for that record; expire data deliberately and rely on fresh challenge validation afterward. Operator setup plans and test screenshots may contain test data; never use customer PII in verification artifacts.
+
+## Browser behavior and preservation
+
+### Isolated Cloudflare acceptance deployment
+
+`src/worker/forms-sandbox.ts` deploys the same submission, management and outbox handlers with only an isolated D1 binding. It requires `FORMS_SANDBOX=1`, exposes no login, customer dashboard, publishing, inbound email or analytics endpoints, and accepts tenant-scoped bearer credentials for configuration/status/retry. Its five-minute cron processes the durable outbox. Use real Turnstile credentials and exact preview hostnames; never deploy the local placeholder resources or dummy secrets remotely.
+
+Test mode captures output by default. For an explicitly authorized operator email test, configure a **separate** `FORMS_TEST_EMAIL` send binding restricted by `destination_address` (and an authenticated sender restriction), plus server-side `FORMS_TEST_RECIPIENT`, `FORMS_FROM` and `FORMS_SENDER_READY=1`. This opt-in is permitted only on a sandbox backend. The outbox replaces all snapshotted recipients with the single operator sink and prefixes the subject with `[VITRIS TEST]`; browser fields cannot choose its recipient. Missing sink/sender configuration fails visibly without falling back to the customer binding. Status includes `sandboxMail` readiness. An `accepted` test record means provider acceptance, not inbox delivery. It remains a test submission with zero production leads/conversions and the existing seven-day test retention. Previously captured jobs remain captured; use fresh submissions after mail setup.
+
+Example restricted operator binding (replace the authenticated Vitris sender):
+
+```json
+{
+  "vars": {
+    "FORMS_SANDBOX": "1",
+    "FORMS_TEST_RECIPIENT": "operator@example.com",
+    "FORMS_FROM": "forms-test@YOUR-VERIFIED-VITRIS-DOMAIN",
+    "FORMS_SENDER_READY": "1"
+  },
+  "send_email": [{
+    "name": "FORMS_TEST_EMAIL",
+    "destination_address": "operator@example.com",
+    "allowed_sender_addresses": ["forms-test@YOUR-VERIFIED-VITRIS-DOMAIN"]
+  }]
+}
+```
+
+The October 9 isolated deployment/evidence is under `artifacts/contact-forms/cloud-test-20261009/`. It uses `vitris-forms-sandbox-20261009`, a new D1 database, and the new `dwperrotta-forms-test-20261009` Pages project on the `sandbox` preview branch. The existing `vitris` database, original preserve preview and customer domains are outside this deployment. One real managed widget is shared by all nine route-level contact forms on that exact preview hostname. Its secrets are Worker secrets, never frontend assets. Local provisioning scripts reconcile their named resources on rerun and load Cloudflare credentials without printing them; `.private-secrets.json` is ignored and must stay operator-only.
+
+Remote D1 execution exposed a nested `CASE ... END` trigger parsing failure. Migration 0004 now uses equivalent trigger `WHEN` clauses, which passed actual remote Wrangler migration execution as well as local ownership/atomicity tests. No preservation reference or frozen baseline was changed.
+
+The shared runtime defers Turnstile until submission, preserves fields, HTML constraints and labels, prevents concurrent requests, retains the retry UUID after an ambiguous failure, and suppresses resubmission of the same successfully accepted values. It provides live status/alert regions and distinct errors for validation, expiry, rate limits, unavailable challenge/backend and timeouts. It claims only saved acceptance; test feedback explicitly says no customer email will be sent. Without JavaScript, a visible `noscript` notice directs visitors to listed contact details, and native POST cannot bypass challenge/idempotency validation.
+
+Preservation CSP adds only the configured backend and `https://challenges.cloudflare.com` to the required script/connect/frame directives for connected forms. The verifier's request policy admits only that backend's `/api/leads` and required challenge paths, with controlled responses during UI verification. Old services remain blocked. Resting-page screenshots use the original references and unchanged 0.5% threshold; intentional challenge/submission states are verified separately. Generated-site verification uses the same narrowly mocked challenge/acceptance adapter and blocks other outbound mutations. Passing those mocks does not establish live backend readiness.
+
+## Staged rollout and rollback
+
+1. Review local evidence under `artifacts/contact-forms/`, including read-only account inspection. The inspected account had an active account token, zero widgets, zero listed Workers and the existing `vitris` D1 database. The configured `vitris-backend` Worker settings lookup returned 404. Resolve the intended deployed Worker/account/resource mapping before any remote change.
+2. Create a separately named sandbox Worker/database using a reviewed copy of the test configuration with real isolated resource IDs. Retain `FORMS_SANDBOX=1`; enable no customer mail binding. Apply migrations there, provision real widgets for exact isolated preview hostnames and execute the test-mode acceptance checks with real Turnstile. Establish actual account Email Service availability and Vitris sender setup separately.
+3. Review permissions, recipient lists, sender restrictions and all field mappings. Back up the existing shared backend/D1. Only after explicit rollout authorization, deploy the additive migration, code and notification cron/binding. Keep every customer form disabled while its asset/configuration migration is staged.
+4. Activate one reviewed tenant/form in `test`, inspect captured output and exact challenge hostname/action, then obtain separate authorization for `live` configuration and customer notifications. No customer-domain migration is part of this forms rollout. Existing preview hosts can remain previews; domains require their own approval/workflow.
+5. Monitor pending age, terminal codes, rate limits, provider acceptance and mail logs. Expand tenant by tenant. Confirm retention and deletion operations before broad activation.
+
+Rollback first sets affected forms to `disabled` using the tenant-scoped API, pausing future acceptance and pending mismatched jobs. Preserve D1 leads/outbox for investigation. Restore previously verified disabled preview assets; do not restore an insecure origin-inferred public lead handler. If needed, pause the added notification cron while preserving the daily analytics schedule. Re-enable only after reviewing pending jobs and possible duplicate-send windows. No destructive migration rollback or deletion of old lead history is required.
+
+## Verification commands
+
+```powershell
+node --experimental-strip-types --test src/contact-forms.test.ts src/contact-forms-operations.test.ts src/contact-forms-browser.test.ts src/lead-forms.test.ts src/preserve.test.ts
+npm run typecheck
+npm run build:cli
+npm run verify:package
+```
+
+Tests use the installed Wrangler/Miniflare D1 simulator and real migrations; mail providers are fakes and browser challenge execution/Siteverify are controlled fixtures. No remote migrations, customer messages, production-backend changes or customer-domain changes are part of this implementation verification.

package/docs/DISTRIBUTION.md

@@ -0,0 +1,70 @@
+# Distribution, client starters, and migration
+
+## Repository boundaries
+
+`@tryvitris/website-harness` is the reusable package maintained here. `vitris` is the command. The workflow graph schedules agent, tool, and critic stages; skills and references supply stage-specific knowledge. The compiler builds static websites. The optional backend Worker supplies owner administration, leads, and analytics.
+
+Generate a separate directory for each customer with `vitris site create`. Open that directory in the coding agent, initialize its Git repository, and commit its authored source and lockfile. Keep customer secrets and captures out of the public harness repository. A second starter repository is unnecessary: `templates/site` is the versioned starter shipped with the npm package.
+
+New sites depend on the exact creating package version, avoiding paths into an ephemeral `npx` cache. Before a registry release, pass `--harness` with a tarball path or an explicit `file:` dependency. Both paths are relative to the generated site directory. Registry and tarball installations include bundled JavaScript commands and APIs; consumers do not need to strip TypeScript inside `node_modules`.
+
+## Terminology and compatibility
+
+| Current name | Accepted legacy name |
+| --- | --- |
+| `@tryvitris/website-harness` | Existing `@tryvitris/harness`, `@vitris/harness` and `@vitris/kernel` installations continue running their installed version; migrate dependencies explicitly |
+| `--harness`, `harnessSpec` | `--kernel`, `kernelSpec` |
+| `VITRIS_HARNESS` | `VITRIS_KERNEL` |
+| `launch.json.backendOrigin`, `--backend-origin` | `launch.json.kernelOrigin`, `--kernel-origin` |
+| `VITRIS_BACKEND_ORIGIN` | `KERNEL_ORIGIN` |
+| Workflow command `{harness}` | `{kernel}` |
+| HTML `data-backend` | The compiler also emits `data-kernel`; the beacon accepts both |
+
+At the same configuration level, current names take precedence. CLI build overrides environment, which overrides launch configuration. Internal variable names, historical reports, and calibration issuer identifiers may retain `kernel`; changing evidence identity or signatures is not part of a naming migration.
+
+## Migrate an existing client
+
+Stop its workflow first. From the harness checkout, preview changes:
+
+```bash
+node bin/vitris-migrate-site.js --site ../acme --harness ../vitris-harness/tryvitris-website-harness-0.1.0-beta.6.tgz
+```
+
+Add `--apply` to perform the displayed changes. The command backs up affected files under the client's `agent-backups/`, renames the package dependency and known script paths, and converts the backend origin key. Conflicting old/new origins fail before writes. Client pages, components, media, secrets, existing lockfile, and workflow state are preserved. Repeating it makes no further edits.
+
+Then run inside the client directory:
+
+```bash
+npm install
+npm run refresh-agent
+npm run build
+```
+
+Review the migration diff and regenerated lockfile before committing. `refresh-agent` now plans and applies only managed instruction files whose previous hashes are known. Older copied kits without provenance keep customized or unknown files and report conflicts. Existing graph progress is retained; a graph-version change is deferred for explicit audit. Use `vitris upgrade --site . --plan` to inspect the plan and `--apply` to apply an unchanged plan. This managed-kit operation does not install npm dependencies. Custom imports of `@vitris/harness` or `@vitris/kernel` must also be updated; the migration only handles known configuration and command paths. An npm alias under the old dependency name can temporarily support a custom integration. No compatibility package has been published under the old name.
+
+## Backend deployment identity
+
+The new default Worker name is `vitris-backend`. This does not rename an existing remote Worker. Existing Vitris deployments must continue using the deployed name and resource bindings until an explicit service cutover. For example, use the old Worker name with Wrangler's `--name vitris-kernel` override while preserving its existing configuration. Keep the existing backend URL in client launch settings during that transition.
+
+The checked-in Wrangler examples contain placeholder resource identifiers. Provision your own Cloudflare bindings and keep local account configuration outside version control; see [Cloudflare setup](CLOUDFLARE.md). Static client builds do not require backend resources. Preparing this source does not change any remote Worker, DNS record, binding, or client deployment.
+
+## First migrations from Amazon
+
+1. Generate a client repo with `--from` pointing at its current website. Capture pages, important URLs, business facts, and original brand media while the old site remains available.
+2. Build through the workflow to a verified local preview. Preserve logos, founder/staff identity, and unique project imagery; use inspected stock for appropriate gaps. Confirm content and forms with the customer.
+3. Verify a hosted preview, including URL coverage, redirects, assets, forms, and mobile behavior. Keep email/MX records separate from website hosting changes.
+4. Schedule the domain cutover after acceptance, record rollback settings, and check the live site before retiring old hosting.
+
+These are rollout steps, not completed migrations. This package does not automatically transfer Amazon infrastructure or DNS.
+
+## Public release preparation
+
+The owner selected MIT and public npm publication under `@tryvitris/website-harness`. The `prepublishOnly` guard verifies the package identity, public registry and visibility, beta dist-tag, and packed-release audit before allowing publication. See SECURITY.md for the release audit and CLOUDFLARE.md for user-owned infrastructure.
+
+MIT licensing and intended repository metadata are included. Before public release, review third-party provenance and dependency notices, confirm npm scope ownership/authentication, and repeat the source, Git-history, and tarball credential checks. The dedicated `vitris-harness` repository starts with fresh history. Keep the original private development repository and customer repositories private. Creating a remote repository, changing visibility, and publishing npm are separate explicitly authorized operations.
+
+Run `npm run test:freeze` after final source edits. It checks type safety, tests, package installation, generated-site installation and build, public API imports, first-stage preparation, and restoration of the source archive. Use the immutable result for the official pilot. Publishing and production deployment are separate operations.
+
+## Optional corrected teaching data
+
+The core npm package includes the original v1/v2 teaching studies and reference metadata. The larger immutable corrected studies (v3/v4, releases 2026-10-06.1 and 2026-10-06.2) are optional data, supplied separately from the core beta. They retain their original bytes and hashes; the package does not substitute reduced images or waive inspection. Set VITRIS_REFERENCE_DATA to a verified data root containing design-system/compositions/v3 and v4 before opting into those releases through launch.json.designReferences. A source checkout can serve as that root. Missing data produces an explicit error. The ordinary new-site workflow does not opt into those corrected teaching releases.