@tryvitris/website-harness 0.1.0-beta.8 → 1.0.0

package/bin/cloudflare/backend.js

@@ -881,67 +881,6 @@ async function handleInboundEmail(message, env) {
   });
 }
 
-// src/html.ts
-function escapeHtml(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-function escapeAttr(value) {
-  return escapeHtml(value);
-}
-
-// src/types.ts
-var defaultTheme = {
-  colorBg: "#F7F4EF",
-  colorText: "#1A1714",
-  colorMuted: "#5C574F",
-  colorAccent: "#B44A2C",
-  colorAccentText: "#FFFFFF",
-  colorSurface: "#FFFFFF",
-  colorSurface2: "#EFEAE3",
-  colorBorder: "#E4DDD2",
-  colorFocus: "#B44A2C",
-  fontBody: 'ui-sans-serif, system-ui, "Segoe UI", sans-serif',
-  fontDisplay: "ui-serif, Georgia, 'Times New Roman', serif",
-  radius: "8px",
-  radiusLg: "16px",
-  radiusPill: "999px",
-  maxWidth: "1120px"
-};
-
-// src/worker/tenant.ts
-async function tenantBySlug(env, slug) {
-  return env.DB.prepare("SELECT * FROM tenants WHERE slug = ?").bind(slug).first();
-}
-async function tenantById(env, id) {
-  return env.DB.prepare("SELECT * FROM tenants WHERE id = ?").bind(id).first();
-}
-async function tenantByHostname(env, hostname) {
-  const cached = await env.KV.get(`host:${hostname}`);
-  if (cached) return tenantById(env, cached);
-  const row = await env.DB.prepare(
-    `SELECT tenants.* FROM tenants JOIN hostnames ON hostnames.tenant_id = tenants.id WHERE hostnames.hostname = ?`
-  ).bind(hostname.toLowerCase()).first();
-  if (row) await env.KV.put(`host:${hostname}`, row.id, { expirationTtl: 3600 });
-  return row;
-}
-async function loadSiteSnapshot(env, tenantId) {
-  const siteRow = await env.DB.prepare("SELECT json FROM site_config WHERE tenant_id = ?").bind(tenantId).first();
-  const contentRow = await env.DB.prepare("SELECT json FROM content WHERE tenant_id = ?").bind(tenantId).first();
-  const themeRow = await env.DB.prepare("SELECT json FROM theme WHERE tenant_id = ?").bind(tenantId).first();
-  if (!siteRow || !contentRow || !themeRow) return null;
-  return {
-    site: JSON.parse(siteRow.json),
-    content: JSON.parse(contentRow.json),
-    theme: { ...defaultTheme, ...JSON.parse(themeRow.json) }
-  };
-}
-async function bumpVersion(env, tenantId) {
-  const row = await env.DB.prepare(
-    "UPDATE tenants SET content_version = content_version + 1 WHERE id = ? RETURNING content_version"
-  ).bind(tenantId).first();
-  return row?.content_version ?? 1;
-}
-
 // src/forms/config.ts
 var safeId = (s) => typeof s === "string" && /^[a-zA-Z0-9_-]{1,80}$/.test(s);
 var safeEmail = (s) => {
@@ -977,6 +916,14 @@ function validateFormConfig(value) {
   return c2;
 }
 
+// src/html.ts
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function escapeAttr(value) {
+  return escapeHtml(value);
+}
+
 // src/worker/forms.ts
 var MAX_BODY = 32768;
 function sandboxMailReadiness(env) {
@@ -1220,6 +1167,140 @@ async function handleFormsAdmin(env, request) {
   }
 }
 
+// src/worker/admin.ts
+var scopes = ["leads:read", "analytics:read", "leads:write"];
+var json2 = (data, status = 200) => Response.json(data, { status, headers: { "cache-control": "no-store", "x-content-type-options": "nosniff" } });
+async function handleAdmin(env, request) {
+  const url = new URL(request.url);
+  const match = url.pathname.match(/^\/api\/admin\/v1\/([a-zA-Z0-9_-]{1,100})\/(status|leads|analytics|leads\/status)$/);
+  if (!match) return json2({ error: "Not found" }, 404);
+  const [, tenant, resource] = match;
+  if (request.headers.has("origin")) return json2({ error: "Server credential required" }, 403);
+  const installationId = request.headers.get("x-vitris-installation") || "";
+  const token = request.headers.get("authorization")?.match(/^Bearer ([a-zA-Z0-9_-]{32,200})$/)?.[1];
+  let grant;
+  try {
+    const map = JSON.parse(env.ADMIN_CONNECTIONS || "{}");
+    if (map && typeof map === "object" && !Array.isArray(map) && Object.hasOwn(map, installationId)) grant = map[installationId];
+  } catch {
+  }
+  if (!grant || !token || !/^[a-f0-9]{64}$/.test(grant.tokenHash) || await digest(token) !== grant.tokenHash) return json2({ error: "Unauthorized" }, 401);
+  if (grant.tenantId !== tenant || grant.siteOrigin !== request.headers.get("x-vitris-site-origin") || !Array.isArray(grant.scopes) || grant.scopes.some((s) => !scopes.includes(s))) return json2({ error: "Forbidden" }, 403);
+  if (!await env.DB.prepare("SELECT id FROM tenants WHERE id=?").bind(tenant).first()) return json2({ error: "Forbidden" }, 403);
+  const identity = { schemaVersion: 1, installationId, tenantId: tenant, siteOrigin: grant.siteOrigin };
+  const required = resource === "analytics" ? "analytics:read" : resource === "leads/status" ? "leads:write" : resource === "leads" ? "leads:read" : void 0;
+  if (required && !grant.scopes.includes(required)) return json2({ error: "Forbidden" }, 403);
+  if (request.method !== (resource === "leads/status" ? "POST" : "GET")) return json2({ error: "Method not allowed" }, 405);
+  if (resource === "status") return json2({ ...identity, scopes: grant.scopes, capabilities: { leads: grant.scopes.includes("leads:read"), testSubmissions: grant.scopes.includes("leads:read"), analytics: grant.scopes.includes("analytics:read"), leadStatus: grant.scopes.includes("leads:write") } });
+  if (resource === "leads/status") {
+    if (url.searchParams.has("mode")) return json2({ error: "Test submissions are read-only" }, 400);
+    if (!request.headers.get("content-type")?.startsWith("application/json")) return json2({ error: "JSON required" }, 400);
+    const reader = request.body?.getReader();
+    let body = "";
+    let size = 0;
+    if (reader) for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > 2048) {
+        await reader.cancel();
+        return json2({ error: "Body too large" }, 413);
+      }
+      body += new TextDecoder().decode(value);
+    }
+    let data;
+    try {
+      data = JSON.parse(body);
+    } catch {
+      return json2({ error: "Invalid JSON" }, 400);
+    }
+    if (!data || typeof data.id !== "string" || data.id.length > 200 || !["new", "contacted", "closed"].includes(data.status)) return json2({ error: "Invalid lead status" }, 400);
+    const result = await env.DB.prepare("UPDATE leads SET status=? WHERE id=? AND tenant_id=? RETURNING id").bind(data.status, data.id, tenant).first();
+    return result ? json2({ ok: true }) : json2({ error: "Lead not found" }, 404);
+  }
+  if (resource === "leads") {
+    const mode = url.searchParams.get("mode") || "live";
+    if (!["live", "test"].includes(mode)) return json2({ error: "Invalid mode" }, 400);
+    const sql = mode === "test" ? `SELECT s.id,s.name,s.email,s.phone,s.message,s.page_path,s.created_at,s.fields_json,'test' AS status,s.form_id,'test' AS mode,o.status AS notification_status,o.last_error AS notification_error,o.test_output
+         FROM form_submissions s LEFT JOIN form_outbox o ON o.id=s.id AND o.tenant_id=s.tenant_id WHERE s.tenant_id=? AND s.mode='test' ORDER BY s.created_at DESC,s.id DESC LIMIT 200` : `SELECT l.id,l.name,l.email,l.phone,l.message,l.page_path,l.status,l.created_at,s.fields_json,o.status AS notification_status,o.last_error AS notification_error
+         FROM leads l LEFT JOIN form_submissions s ON s.id=l.id AND s.tenant_id=l.tenant_id AND s.mode='live'
+         LEFT JOIN form_outbox o ON o.id=s.id AND o.tenant_id=l.tenant_id WHERE l.tenant_id=? ORDER BY l.created_at DESC,l.id DESC LIMIT 200`;
+    const stored = (await env.DB.prepare(sql).bind(tenant).all()).results;
+    const rows2 = [];
+    let size = 0;
+    for (const row of stored) {
+      size += new TextEncoder().encode(JSON.stringify(row)).length;
+      if (size > 35e5) break;
+      rows2.push(row);
+    }
+    return json2({ ...identity, source: "connected", mode: mode === "live" ? "production" : "test", writable: mode !== "test" && grant.scopes.includes("leads:write"), truncated: rows2.length < stored.length || stored.length === 200, rows: rows2 });
+  }
+  const days = Number(url.searchParams.get("days") || "30");
+  if (!Number.isInteger(days) || days < 1 || days > 90) return json2({ error: "days must be 1\u201390" }, 400);
+  const rows = (await env.DB.prepare(`WITH days AS (
+    SELECT day FROM analytics_events WHERE tenant_id=? AND (src IS NULL OR src='' OR src='live')
+    UNION SELECT substr(created_at,1,10) FROM leads WHERE tenant_id=?
+  ) SELECT day,
+    (SELECT COUNT(*) FROM analytics_events e WHERE e.tenant_id=? AND e.day=days.day AND e.kind='pageview' AND (e.src IS NULL OR e.src='' OR e.src='live')) AS views,
+    (SELECT COUNT(DISTINCT vid) FROM analytics_events e WHERE e.tenant_id=? AND e.day=days.day AND e.kind='pageview' AND (e.src IS NULL OR e.src='' OR e.src='live')) AS visitors,
+    (SELECT COUNT(*) FROM leads l WHERE l.tenant_id=? AND substr(l.created_at,1,10)=days.day) AS enquiries
+    FROM days WHERE day>=date('now',?) AND day<=date('now') ORDER BY day`).bind(tenant, tenant, tenant, tenant, tenant, `-${days - 1} days`).all()).results;
+  return json2({ ...identity, source: "connected", rows });
+}
+
+// src/types.ts
+var defaultTheme = {
+  colorBg: "#F7F4EF",
+  colorText: "#1A1714",
+  colorMuted: "#5C574F",
+  colorAccent: "#B44A2C",
+  colorAccentText: "#FFFFFF",
+  colorSurface: "#FFFFFF",
+  colorSurface2: "#EFEAE3",
+  colorBorder: "#E4DDD2",
+  colorFocus: "#B44A2C",
+  fontBody: 'ui-sans-serif, system-ui, "Segoe UI", sans-serif',
+  fontDisplay: "ui-serif, Georgia, 'Times New Roman', serif",
+  radius: "8px",
+  radiusLg: "16px",
+  radiusPill: "999px",
+  maxWidth: "1120px"
+};
+
+// src/worker/tenant.ts
+async function tenantBySlug(env, slug) {
+  return env.DB.prepare("SELECT * FROM tenants WHERE slug = ?").bind(slug).first();
+}
+async function tenantById(env, id) {
+  return env.DB.prepare("SELECT * FROM tenants WHERE id = ?").bind(id).first();
+}
+async function tenantByHostname(env, hostname) {
+  const cached = await env.KV.get(`host:${hostname}`);
+  if (cached) return tenantById(env, cached);
+  const row = await env.DB.prepare(
+    `SELECT tenants.* FROM tenants JOIN hostnames ON hostnames.tenant_id = tenants.id WHERE hostnames.hostname = ?`
+  ).bind(hostname.toLowerCase()).first();
+  if (row) await env.KV.put(`host:${hostname}`, row.id, { expirationTtl: 3600 });
+  return row;
+}
+async function loadSiteSnapshot(env, tenantId) {
+  const siteRow = await env.DB.prepare("SELECT json FROM site_config WHERE tenant_id = ?").bind(tenantId).first();
+  const contentRow = await env.DB.prepare("SELECT json FROM content WHERE tenant_id = ?").bind(tenantId).first();
+  const themeRow = await env.DB.prepare("SELECT json FROM theme WHERE tenant_id = ?").bind(tenantId).first();
+  if (!siteRow || !contentRow || !themeRow) return null;
+  return {
+    site: JSON.parse(siteRow.json),
+    content: JSON.parse(contentRow.json),
+    theme: { ...defaultTheme, ...JSON.parse(themeRow.json) }
+  };
+}
+async function bumpVersion(env, tenantId) {
+  const row = await env.DB.prepare(
+    "UPDATE tenants SET content_version = content_version + 1 WHERE id = ? RETURNING content_version"
+  ).bind(tenantId).first();
+  return row?.content_version ?? 1;
+}
+
 // src/worker/surfaces/api.ts
 var KINDS = /* @__PURE__ */ new Set(["pageview", "leave", "convert", "engage", "ping"]);
 var GOALS = /* @__PURE__ */ new Set(["form", "tel", "mailto", "maps"]);
@@ -23687,6 +23768,7 @@ async function route(env, request) {
   const path = url.pathname;
   if (isPreviewHost(env, request)) return handlePreview(env, request);
   if (path.startsWith("/preview/")) return previewHandoff(env, request);
+  if (path.startsWith("/api/admin/")) return handleAdmin(env, request);
   const approve = await handleApproveReject(env, request);
   if (approve) return approve;
   const updatesApi = await handleUpdatesApi(env, request);

package/bin/types/src/admin/connection.d.ts

@@ -0,0 +1,3 @@
+import type { AdminManifest } from '@tryvitris/website-admin-contracts';
+/** Identity and response requirements of the published alpha adapter. */
+export declare function readConnection(manifest: AdminManifest, token: string, resource: 'status' | 'leads' | 'analytics', test?: boolean, transport?: typeof fetch): Promise<any>;

package/bin/types/src/cli/admin.d.ts

@@ -0,0 +1,21 @@
+import { type CommandResult } from './types.ts';
+export declare const ADMIN_VERSION = "0.1.0-alpha.1";
+export type AdminOptions = {
+    site?: string;
+    dir?: string;
+    domain?: string;
+    website?: string;
+    tenant?: string;
+    backendOrigin?: string;
+    plan?: boolean;
+    apply?: boolean;
+    leadWrite?: boolean;
+    dryRun?: boolean;
+    grants?: string;
+    out?: string;
+};
+/** Merge the operator's COMPLETE map, never replace unrelated installations. */
+export declare function mergeAdminGrant(existing: unknown, addition: unknown): {
+    [x: string]: unknown;
+};
+export declare function adminCommand(command: string, options: AdminOptions): Promise<CommandResult>;

package/bin/types/src/cli/site-create.d.ts

@@ -4,6 +4,8 @@ export type CreateSiteOptions = SiteInputOptions & {
     dir: string;
     slug: string;
     name?: string;
+    /** Opt-in instructions only; never provision during site creation. */
+    admin?: boolean;
     from?: string;
     mode?: "redesign" | "preserve";
     blank?: boolean;

package/bin/vitris-create-site.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createSite
-} from "./chunks/chunk-DYKLM4I3.js";
+} from "./chunks/chunk-UFTVWTEZ.js";
 import "./chunks/chunk-34H54KEY.js";
 import "./chunks/chunk-JCRGE6AL.js";
 import {
@@ -41,6 +41,7 @@ var arg = (flag) => {
 };
 var usage = `Usage: vitris-create-site --dir ../acme --slug acme [--name "Acme Shop"] [--from URL | --blank]
   --owner EMAIL         Owner login email
+  --admin               Prepare optional sibling admin instructions (no cloud writes)
   --template ID         Catalog ID, name, or hosted template URL; continue automatically
   --template-release R  Optional catalog revision
   --content TEXT        Additional business content or instructions
@@ -67,6 +68,7 @@ async function main() {
     blank,
     ...siteInputsFromArgv(process.argv),
     mode: arg("--mode"),
+    admin: process.argv.includes("--admin"),
     owner: arg("--owner"),
     backendOrigin: arg("--backend-origin") || arg("--kernel-origin"),
     harnessSpec: arg("--harness") || arg("--kernel")

package/bin/vitris-go.js

@@ -7,7 +7,7 @@ import {
   runCreativeProfile,
   runSite,
   statusSite
-} from "./chunks/chunk-FEFLSJM5.js";
+} from "./chunks/chunk-LZC37OJZ.js";
 import "./chunks/chunk-R2WRQDVE.js";
 import "./chunks/chunk-34H54KEY.js";
 import "./chunks/chunk-JCRGE6AL.js";

package/bin/vitris.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunks/chunk-QQOMS2DL.js";
-import "./chunks/chunk-WNE543KF.js";
+} from "./chunks/chunk-SEMH6MCV.js";
+import "./chunks/chunk-YXJAQYDE.js";
 import "./chunks/chunk-FGSQE3DU.js";
 import "./chunks/chunk-WMJVLMU2.js";
 import "./chunks/chunk-A2XMAPVW.js";
-import "./chunks/chunk-DYKLM4I3.js";
+import "./chunks/chunk-UFTVWTEZ.js";
 import "./chunks/chunk-2NW7KSPA.js";
 import "./chunks/chunk-3OKR5AZJ.js";
-import "./chunks/chunk-FEFLSJM5.js";
+import "./chunks/chunk-LZC37OJZ.js";
 import "./chunks/chunk-R2WRQDVE.js";
 import "./chunks/chunk-34H54KEY.js";
 import "./chunks/chunk-JCRGE6AL.js";

package/docs/ADMIN.md

@@ -0,0 +1,85 @@
+# Separate business admin
+
+The business owns a separate installation, accounts, D1 database, R2 bucket and Worker at `admin.customer-domain.com`. No central Vitris login is required. Pages, Media, page builders and arbitrary HTML editing are outside scope. The public website keeps its forms, backend origin, tenant identity, consent behavior and release gates.
+
+The harness pins `@tryvitris/website-admin-harness` and `@tryvitris/website-admin-contracts` to **0.1.0-alpha.1**. Setup delegates to the published runtime's `/cli` export (`vitris-admin`); its Worker uses `/worker`. The separate initializer is `@tryvitris/create-website-admin-harness@0.1.0-alpha.1`. Never use a floating `alpha` tag for a reproducible installation. See the [upstream source](https://github.com/jackperrotta/website-admin-harness).
+
+## Local preparation
+
+New websites may opt into next-step instructions with `vitris site create ... --admin` or `vitris-create-site ... --admin`. This creates `ADMIN-SETUP.md` only. Continue prepare → `agent/CURRENT.md` → work → complete and stop at verified local preview as usual. Existing websites can run setup directly.
+
+Inspect the site's launch configuration, forms, exact public origin, and actual backend tenant ID. A slug is not proof of tenant identity. Prepare the sibling admin with:
+
+```sh
+vitris admin setup --site ../acme --dir ../acme-admin --domain admin.customer-domain.com --website https://www.customer-domain.com --tenant EXISTING_TENANT_ID --backend-origin https://BACKEND --plan
+```
+
+Equivalent standalone published command:
+
+```sh
+npx --yes @tryvitris/website-admin-harness@0.1.0-alpha.1 setup --site ../acme --dir ../acme-admin --domain admin.customer-domain.com --website https://www.customer-domain.com --tenant EXISTING_TENANT_ID --backend-origin https://BACKEND --plan
+```
+
+Review `../acme/artifacts/admin/setup-plan.json`, including its exact directories, origins, tenant, scopes, package version and launch digest. Set a new dedicated `VITRIS_ADMIN_API_TOKEN` in the operator environment: 32–200 URL-safe letters/digits/underscores/hyphens generated by a secure secret manager. Repeat the identical command with `--apply` replacing `--plan`. Never pass the credential as a command argument or print it. `--lead-write` must appear in both commands only if lead status updates are explicitly wanted; default scopes are `leads:read` and `analytics:read`.
+
+Apply brands the installation from `launch.json.name`, writes public `launch.json.admin` metadata, and saves only its SHA-256 hash in the admin's ignored `.vitris/backend-grant.json`. Existing forms, backend URL and workflow progress stay intact. Matching retries are no-ops; changed launch bytes/plans, conflicting destinations/connections or changed authority require a new review. Do not delete setup receipts or use force to bypass conflicts. Keep `artifacts/`, `.vitris/`, `.env*`, `.dev.vars*`, `dist/` and local release bundles ignored. No tenant, cloud resource, account, secret, DNS record or deployment is created by setup.
+
+Inside the admin, install dependencies and retain its lockfile. Read `agent/WORKFLOW.md`, `agent/refs/harness.md`, and `agent/refs/cloudflare.md` before changing the installation. `npm run db:local` and `npm run dev` use a separate local manifest/database with synthetic demo data. They do not establish production backend access or working email authentication.
+
+## Backend compatibility and grants
+
+This source adds the admin v1 API. **An already deployed website backend may still run an older revision.** Setup does not upgrade it. Identify its owner, deployed revision, schema and hostname; perform any backend release as a separately reviewed operation. Never deploy or migrate a shared backend as an admin setup side effect. No production endpoint or credential is included in this public repository, so an existing deployment's compatibility must be checked per installation.
+
+`vitris admin status --site ../acme` reports local metadata only. After the grant is installed, use the dedicated credential in the operator environment to check the deployed API:
+
+```sh
+vitris admin verify --site ../acme --dir ../acme-admin
+```
+
+Verify requires v1 identity matching installation, tenant and site origin, both read scopes, and valid production leads, test submissions and analytics responses. It reports counts only; zero rows are valid. It fails on missing routes, rejected/revoked credentials, identity mismatch, malformed records, redirects or transport failure. It does not certify collection, email, account login or deployment. The admin's published adapter likewise surfaces failures without substituting demo records.
+
+The backend secret `ADMIN_CONNECTIONS` is a COMPLETE installation-keyed map. Each grant contains only `tenantId`, exact HTTPS `siteOrigin`, `tokenHash` and `scopes`. Retrieve the authoritative full map from the backend owner's secure configuration; Wrangler cannot recover a secret's value. For a confirmed brand-new backend only, initialize a private ignored file with `{}`. Do not treat an unknown existing map as empty.
+
+```sh
+vitris admin grant --dir ../acme-admin --grants PRIVATE_COMPLETE_MAP.json --out NEW_PRIVATE_MERGED_MAP.json
+```
+
+This local command preserves other grants, validates hashed entries and installation identity, refuses differing existing authority and refuses overwriting the output. Store input/output in ignored operator storage. Review the entire merged map before explicitly uploading it to the intended backend as `ADMIN_CONNECTIONS` via Wrangler secret stdin. Rotation/revocation is a separate reviewed complete-map update: replace the hash or remove only that installation. Never reuse forms, deployment, personal Cloudflare or session credentials.
+
+Upload the matching RAW credential to this admin as `HARNESS_API_TOKEN`, through secret stdin. For example, from the admin directory, with the dedicated token already in the operator environment (PowerShell and POSIX shells both support this pipeline):
+
+```sh
+node -e "process.stdout.write(process.env.VITRIS_ADMIN_API_TOKEN || '')" | npx wrangler secret put HARNESS_API_TOKEN --config wrangler.jsonc
+```
+
+Require a nonempty valid environment token before running this command. Install the reviewed complete backend map similarly, by piping the ignored file bytes to `wrangler secret put ADMIN_CONNECTIONS` with the backend's exact config/account. These are explicit cloud writes, outside local setup. Never log secret stdin or store raw tokens in files or public assets.
+
+## API and stored data
+
+Server-to-server requests use `Authorization: Bearer ...`, `x-vitris-installation` and `x-vitris-site-origin`. The routes are `/api/admin/v1/TENANT/status`, `/leads`, `/leads?mode=test`, `/analytics?days=14`, and optional POST `/leads/status` with JSON `{id,status}`. Cookie login, browser Origin requests, forms setup tokens and deployment tokens grant no API access. All responses are uncached; preview hosts cannot reach these routes.
+
+Every query constrains the existing tenant ID. Production reads use `leads`, including retained legacy records. Test reads use `form_submissions WHERE mode='test'` and matching notification captures from `form_outbox`; test records are always read-only. Production enquiries count stored leads. Analytics reads current `analytics_events` with live/legacy source only and excludes preview traffic; consent still controls the existing collector. Dates are UTC; the accepted range is 1–90 days. Leads return the latest 200 at most, bounded below the published adapter's 4 MB limit; `truncated` signals a bounded result. This alpha has no historical pagination/export UI.
+
+Status updates allow `new`, `contacted`, or `closed` and require `leads:write` in addition to the admin's authenticated role and CSRF protections. Cross-tenant and test IDs cannot be updated. They do not retry notifications, change recipients or change collection. Existing D1 migrations remain untouched; this API uses the current schema. Review missing migrations separately for older deployments.
+
+## Explicit Cloudflare rollout
+
+Use the customer's intended account and inspect `npx wrangler whoami` before any write. The admin defaults to Workers with Static Assets, D1, R2 and Cloudflare Email Service authentication. Its generated production config disables workers.dev and uses a canonical Custom Domain. Keep local and production manifests/resources separate.
+
+1. In the admin directory, run `npm run plan`. Review Worker/resource names, account ID, zone ownership, sender and hostname. Run `npx wrangler d1 create ACME_ADMIN_DB` and `npx wrangler r2 bucket create ACME_ADMIN_ASSETS` only as explicit provisioning steps. Put their actual identifiers into `wrangler.jsonc`; use dedicated resources for this business.
+2. Back up any existing target database. Review copied numbered migrations; apply only to the admin's intended database with `npx wrangler d1 migrations apply ACME_ADMIN_DB --remote --config wrangler.jsonc`. Do not apply admin migrations to the website backend database.
+3. Run `npx vitris-admin owner --email OWNER_EMAIL` inside the admin. Review ignored `.vitris/bootstrap-owner.sql`, then apply it with `npx wrangler d1 execute ACME_ADMIN_DB --remote --config wrangler.jsonc --file .vitris/bootstrap-owner.sql`. Existing accounts are not promoted. Each installation owns its users and sessions.
+4. Complete Cloudflare Email Service sender-domain onboarding and sending availability. Set `AUTH_FROM` and a restricted `AUTH_EMAIL` send binding in the production config. Verify provider/recipient restrictions, real delivery, single-use login and revocation. The alpha's stubbed email tests do not prove live delivery. Never enable production demo login or use local mode in production.
+5. Merge/install the backend grant and install `HARNESS_API_TOKEN` through secret stdin as above. Verify the deployed backend API independently. If it needs a compatible release, review its impact and owner authorization separately, retaining existing records/accounts and tenant IDs.
+6. Attach `admin.customer-domain.com` as the generated Worker Custom Domain in the active zone of this account. Verify DNS, TLS and canonical-host checks. Cross-account/external DNS requires a separate reviewed hostname strategy; a CNAME alone does not satisfy this contract.
+7. Run `npm run doctor` and `npm run build` (dry run), review the configuration/release diff, then explicitly deploy the admin with `npm run deploy`. Verify the canonical HTTPS domain, actual owner login, signed-in permissions, revoked access and authoritative stored records. Record the deployed revision. Public website publication continues through its own consent and release gates.
+
+### Websites without collection
+
+A static website without a registered backend has no historical lead or analytics records to import. Prepare a dedicated website backend Worker, D1 schema, R2 and KV bindings (and optional Analytics Engine) from the harness's `cloudflare/` example. Review account/resource ownership, session secret, migrations and tenant/hostname registration before any cloud writes. Keep backend provisioning and deployment separate from the admin database and deployment.
+
+Use `vitris forms inspect` and the plan/apply workflow in `docs/CONTACT-FORMS.md` to register approved origins, form schemas, Turnstile, notification sender and recipients. Preserve existing form endpoints until the owner selects the replacement flow. Validate test submissions in isolation first; do not send customer test notifications without authorization. Enable the existing analytics collector only with the site's consent policy and production hostname/tenant mapping. Scaffolding an admin, setting backendOrigin, or binding a subdomain enables none of this automatically.
+
+## Validation
+
+`npm run test:admin` runs isolated synthetic fixtures against actual local D1 and the published runtime Worker adapter, including installer plan/apply/recovery, conflicts, stale plans, identity/account isolation, unauthorized/revoked credentials, read-only grants, test separation and preview exclusion. No live challenge or mail is used: assets and backend transport are in-process test bindings; form rows and analytics are explicitly synthetic stored fixtures. `npm run verify:admin` installs all three exact public npm releases in a fresh ignored directory, then reruns acceptance against that runtime. Evidence stays in `artifacts/admin-integration/`. Run the repository's typecheck, full tests and package verification too.

package/docs/CLI.md

@@ -6,10 +6,10 @@ The `vitris` CLI (`@tryvitris/website-harness`) provides a unified, operator-fri
 
 ## 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):
+Install the stable release as a dependency or run via `npx`. For local tarballs and managed upgrades, see [distribution](DISTRIBUTION.md):
 
 ```bash
-npm install --save-dev @tryvitris/website-harness
+npm install --save-dev --save-exact @tryvitris/website-harness@1.0.0
 npx vitris --help
 ```
 
@@ -23,6 +23,12 @@ node bin/vitris.js --help
 
 ## 2. Command Reference
 
+### `vitris admin setup|status|verify|grant`
+
+Prepare a branded sibling business admin with the pinned published `0.1.0-alpha.1` installer. `vitris admin setup --site SITE --dir SIBLING_ADMIN --domain admin.customer-domain.com --website HTTPS_SITE_ORIGIN --tenant EXISTING_TENANT_ID --backend-origin HTTPS_BACKEND --plan` writes a local plan. Review it, then repeat with `--apply` and dedicated environment `VITRIS_ADMIN_API_TOKEN`. Default grants are read-only; explicit `--lead-write` must be included in both steps to grant status updates. No cloud writes occur. Site creation accepts `--admin` to create instructions only.
+
+`vitris admin status --site SITE` reports local metadata. `vitris admin verify --site SITE --dir ADMIN` checks the actual backend contract, identities and stored records without exposing PII. `vitris admin grant --dir ADMIN --grants COMPLETE_MAP_FILE --out NEW_IGNORED_FILE` prepares a local hashed grant map while preserving other installations. See [ADMIN.md](ADMIN.md) for preservation rules, API semantics, secret stdin and explicit provisioning/authentication/DNS/deployment steps.
+
 ### `vitris doctor`
 Runs environment and preflight health checks.
 ```bash
@@ -195,14 +201,14 @@ vitris preview [--site <dir>] [--port <number>] [--dry-run]
 ---
 
 ### `vitris deploy`
-Builds a verified production bundle and deploys it to Cloudflare Pages.
+Builds and verifies locally, then directly uploads the exact staged bundle to Cloudflare Pages. This is the default site deployment path; it does not require GitHub Actions or Cloudflare-hosted builds. The CLI defaults to a preview, while new redesign sites' `npm run deploy` explicitly selects production and `npm run deploy:preview` selects a preview.
 ```bash
 vitris deploy [--site <dir>] [--provider cloudflare] [--environment preview|production] [--branch <branch>] [--quick] [--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>`.
+2. Build and verify the static `dist/` bundle locally, then stage its exact bytes (aborts if verification fails or source/output changes).
+3. Upload the staged bundle through Wrangler to the configured Pages project and environment; record the source, artifact and deployment identity.
 4. Executes automated remote smoke check against the deployed `*.pages.dev` URL.
 
 Quick publish: `vitris deploy --quick --environment production` rebuilds and uploads without graph gates, browser reviews, or launch preflight. New sites also include `npm run deploy:quick`. The CLI still defaults to preview; preservation sites support previews only and quick mode also skips screenshot comparisons. Compilation, Cloudflare credentials, staged-bundle integrity and the remote HTTP smoke check still apply. Receipts use policy `quick-publish-build-only-v1` and results report `verification: "build-only"`. Skipped reviews are never marked passed. Ordinary deployment retains full verification.

package/docs/CLOUDFLARE.md

@@ -1,12 +1,34 @@
 # Use your own Cloudflare account
 
+Optional business admins use separate Workers, D1, R2 and Cloudflare Email Service authentication in the customer's intended account. See [ADMIN.md](ADMIN.md) for local `vitris admin setup`, explicit provisioning/owner bootstrap/DNS/migrations/deployment, and deployed backend compatibility checks. Setup never deploys or migrates a shared existing backend.
+
 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.
+The default is to build and verify on the operator's computer and upload the finished bundle directly to Cloudflare Pages. GitHub stores source and history; no GitHub Actions or Cloudflare Git builds are required. New sites ship an inactive hosted-workflow example under `deployment/`, outside `.github/workflows/`.
+
+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` to create a Direct Upload project. Set `launch.json.pagesProject` to that name and `launch.json.publicOrigin` to the intended production HTTPS origin. Never put credentials in launch.json, HTML, assets or Git. An unattended operator may use their own `CLOUDFLARE_ACCOUNT_ID` and an account-scoped token with Pages Edit access in ignored environment configuration.
+
+After dependency installation and `npx playwright install chromium`, run `npm run deploy:preview` for a hosted preview. After accepting the preview, run `npm run deploy` only when you intend to publish production. These scripts invoke `vitris deploy` with an explicit environment: local build and verification, exact-byte staging, direct upload, deployment receipt, and HTTP smoke check. Ordinary publishing retains the full verification gates. Keep `dist/`, `agent/release-bundles/`, `agent/release-candidate.json`, and `agent/releases/` ignored in Git. Local builds can be repeated without invoking a hosted build service; Cloudflare hosting, API, file and backend quotas still apply.
+
+Preservation mode supports temporary previews only; its `npm run deploy` selects preview. Follow PRESERVE.md for its narrower contract. Custom-domain and DNS changes remain separate explicit launch steps. The computer must be online and authenticated during an upload; Cloudflare serves the deployed site independently afterward.
+
+### Adopt local uploads in an existing site
+
+Installing a new harness version does not rewrite customer package scripts, authored files, workflow state or remote Cloudflare settings. Review each site's publication contract before making changes, especially if it uses authenticated backend Worker publication.
+
+1. Keep the existing Pages project, domains and `launch.json` settings. For a Git-connected Pages project, turn off automatic production branch deployments and set preview branches to None in Cloudflare's branch controls. Wrangler can still deploy directly to the existing project.
+2. Review and disable the site's automatic GitHub deployment workflow so source pushes do not create a second publication path. Keep any independently chosen test-only CI.
+3. Set the site's package scripts to `node ./node_modules/@tryvitris/website-harness/bin/vitris.js deploy --site . --environment production` for `deploy` and the same command with `--environment preview` for `deploy:preview`. Preservation sites must use preview for both. Keep quick publish separate and explicitly requested.
+4. Add the generated output paths listed above to `.gitignore`, preserving existing rules. Keep source and the lockfile in Git. Moving already tracked output to ignored status requires reviewing the site's index; an ignore rule alone does not untrack files.
+5. Authenticate with the site's own Cloudflare account, accept a direct-upload preview, then publish production only when requested. Check the receipt and hosted smoke result.
+
+See Cloudflare's [Direct Upload guide](https://developers.cloudflare.com/pages/get-started/direct-upload/) and [disabling automatic Git deployments](https://developers.cloudflare.com/pages/configuration/git-integration/#disable-automatic-deployments).
+
+### Optional hosted automation
 
-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.
+An operator may explicitly choose hosted builds. To use GitHub Actions, review and copy `deployment/github-actions.yml.example` into `.github/workflows/deploy.yml` and configure protected credentials. The example retains production/preview preflight and authenticated backend bundle signing where configured. Hosted CI uses the selected provider's allowance. Cloudflare Git integration is another opt-in alternative; its build must install Chromium and run the required site preflight before publication. Enable one publication path for each site.
 
 ## Optional backend Worker
 

package/docs/DISTRIBUTION.md

@@ -8,6 +8,8 @@ Generate a separate directory for each customer with `vitris site create`. Open
 
 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`.
 
+New sites build and verify locally and upload directly to Cloudflare Pages using `npm run deploy:preview` or an explicitly requested production `npm run deploy`. No active GitHub deployment workflow is scaffolded. `deployment/github-actions.yml.example` is an optional hosted alternative. Existing site scripts, workflows and remote project settings are not changed by installing or upgrading the harness; follow the migration steps in [Cloudflare setup](CLOUDFLARE.md). Keep generated output out of source control.
+
 ## Terminology and compatibility
 
 | Current name | Accepted legacy name |
@@ -27,7 +29,7 @@ At the same configuration level, current names take precedence. CLI build overri
 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.7.tgz
+node bin/vitris-migrate-site.js --site ../acme --harness ../vitris-harness/tryvitris-website-harness-1.0.0.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.
@@ -59,7 +61,7 @@ These are rollout steps, not completed migrations. This package does not automat
 
 ## 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.
+The owner selected MIT and public npm publication under `@tryvitris/website-harness`. Version `1.0.0` is the first stable release, published with the `latest` dist-tag. The `prepublishOnly` guard verifies the package identity, public registry and visibility, the `latest` tag for stable versions (`beta` for prereleases), and the 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.
 
@@ -67,4 +69,4 @@ Run `npm run test:freeze` after final source edits. It checks type safety, tests
 
 ## 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.
+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 package. 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.

package/docs/PRESERVE.md

@@ -24,7 +24,7 @@ Verification compares every captured route at 1440px and 390px against hashed so
 
 Contact forms use the shared `/api/leads` service only after explicit server registration and public `launch.json.forms` bindings. `backendOrigin` alone does not enable submissions or notifications. The old `number` field maps to the compatible phone column while retaining its authored HTML name. Default previews validate locally and display a notice. The shared runtime adds a security challenge on submission and accessible feedback while preserving layouts and fields. Verification separates resting-page fidelity from mocked challenge/submission states and sends no customer inquiries. See [CONTACT-FORMS.md](CONTACT-FORMS.md) for sandbox setup, provisioning, server readiness, delivery semantics and the separately authorized rollout. Legacy analytics and employee portal services are not migrated. External navigation links, including employee-login links, remain links to their existing destinations.
 
-Deployment requires `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` with Pages Edit permission. The harness inspects or creates the Pages project, verifies that the preview branch differs from its production branch, stages hashed verified bytes, uploads them, and repeats browser checks against the returned `pages.dev` URL. A newly created project uses `production` as its reserved production branch. No customer domains or DNS records are changed. Preview responses carry `noindex`; previews are public and do not expire automatically. The generated CI workflow is manual and preview-only.
+Deployment requires `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` with Pages Edit permission. The harness inspects or creates the Pages project, verifies that the preview branch differs from its production branch, stages hashed verified bytes, uploads them, and repeats browser checks against the returned `pages.dev` URL. A newly created project uses `production` as its reserved production branch. No customer domains or DNS records are changed. Preview responses carry `noindex`; previews are public and do not expire automatically. Local builds and direct uploads are the default. The inactive deployment/github-actions.yml.example can be installed explicitly for manual, preview-only hosted automation.
 
 Initial availability checks retry transient hosting failures. If Cloudflare has accepted the upload but its preview is not reachable yet, keep the returned URL and recheck it with `vitris verify --site DIR --remote https://HASH.PROJECT.pages.dev`. This reruns the hosted browser checks without uploading another deployment. Local and remote reports are separate.
 

package/docs/SECURITY.md

@@ -10,13 +10,13 @@ Customer HTML never renders on an admin origin. Configure a dedicated PREVIEW_HO
 
 ## Package auditing
 
-The npm beta uses an explicit file allowlist. Local credentials, operator configuration, customer captures, tests, historical archives, plans and runtime receipts are excluded. esbuild receives no secret-valued environment definitions. Integrations read the installing user's environment or Worker secret bindings.
+The npm package uses an explicit file allowlist. Local credentials, operator configuration, customer captures, tests, historical archives, plans and runtime receipts are excluded. esbuild receives no secret-valued environment definitions. Integrations read the installing user's environment or Worker secret bindings.
 
 `npm pack` builds and runs audit:package. The audit opens the actual tarball, checks every filename, detects common provider tokens/private keys/credential URLs, rejects known operator infrastructure IDs, and compares bytes against credential values available in the process environment and local credential files, including encoded forms. Reports contain file locations and rule names, never matched values. Exact-value checking covers only credentials accessible to the process; it cannot establish the absence of unknown keys.
 
 Install a verified Gitleaks release binary and set GITLEAKS_BIN to its executable before `npm run audit:package`. This independent detection layer is required by release CI. Use full redaction and archive/decoding inspection. Re-audit after any source, build, dependency or content change. Keep the final tarball SHA-256 and audit report privately under artifacts/.
 
-The prepublishOnly guard verifies the public @tryvitris/website-harness identity, registry, visibility, prerelease tag, and packed-release audit. No workflow publishes packages. Releases require owner authorization and verification of the final source and tarball. Prefer npm trusted publishing for automated releases; interactive local releases use the maintainer's npm login and 2FA.
+The prepublishOnly guard verifies the public @tryvitris/website-harness identity, registry, visibility, `latest` tag for stable versions (`beta` for prereleases), and packed-release audit. No workflow publishes packages. Releases require owner authorization and verification of the final source and tarball. Prefer npm trusted publishing for automated releases; interactive local releases use the maintainer's npm login and 2FA.
 
 Before making a repository public, separately scan all Git history and uncommitted public source. A clean npm package does not make existing history safe. Historical archives and customer experiments stay private. Never rewrite frozen baselines to remove findings. Revoke/rotate any real disclosed credential with its provider and address repository history separately.