@tryvitris/website-harness 1.0.1 → 1.1.0

package/bin/vitris-verify-browser.js

@@ -10,8 +10,9 @@ import {
   motionCompositionPolicy,
   observeMotion,
   templateMotionHash,
+  typographyPolicy,
   validateTemplateMotionPlan
-} from "./chunks/chunk-GQPUILFR.js";
+} from "./chunks/chunk-WK7HJI5H.js";
 import "./chunks/chunk-KVMZSQ3D.js";
 import "./chunks/chunk-WOORR67N.js";
 import "./chunks/chunk-PRLL7B63.js";
@@ -26,7 +27,12 @@ import {
   hasAnalyticsRuntime,
   productionQuality
 } from "./chunks/chunk-M2ETYSVJ.js";
-import "./chunks/chunk-AUO5I56E.js";
+import {
+  TYPOGRAPHY_SCENARIO,
+  captureTypography,
+  captureTypographyStates,
+  typographyConsistencyFailures
+} from "./chunks/chunk-C3F7XQD2.js";
 import "./chunks/chunk-BIEDSEL2.js";
 import {
   measurePerformance,
@@ -37,11 +43,14 @@ import {
 } from "./chunks/chunk-WEFDVXFX.js";
 import {
   buildVerified
-} from "./chunks/chunk-H3BS2EBR.js";
-import "./chunks/chunk-L44ZTNDM.js";
-import "./chunks/chunk-37F7XIMH.js";
-import "./chunks/chunk-LKN75JGA.js";
+} from "./chunks/chunk-WIT6364Y.js";
+import {
+  loadSitePages
+} from "./chunks/chunk-GPS3SAGQ.js";
+import "./chunks/chunk-JTXFTNEA.js";
+import "./chunks/chunk-GE6UUEG2.js";
 import "./chunks/chunk-YYPYYOEV.js";
+import "./chunks/chunk-S2XVNTQP.js";
 import "./chunks/chunk-GZDLXYZV.js";
 import "./chunks/chunk-G7MNMULR.js";
 import {
@@ -340,6 +349,7 @@ var arg = (key) => {
 };
 var root = resolve(arg("--site") || ".");
 var representative = process.argv.includes("--representative");
+var typePolicy = typographyPolicy(root);
 var concurrency = Number(arg("--concurrency") || process.env.VITRIS_BROWSER_CONCURRENCY || "1");
 if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new Error("--concurrency must be an integer from 1 to 4");
 var extraViewports = (arg("--extra-viewports") || "").split(",").filter(Boolean).map(Number);
@@ -373,10 +383,14 @@ var checks = [];
 var routeChecks = [];
 var compositionTargets = [];
 var pagesToCheck = plan.pages.filter((p) => !representative || p.path === "/" || p.representative);
+if (typePolicy.enabled && !representative) {
+  for (const page of await loadSitePages(root)) if (!pagesToCheck.some((p) => p.path === page.path)) pagesToCheck.push({ path: page.path, sections: [], purpose: "Authored route", representative: false });
+}
 if (!representative && existsSync(join2(dist, "cookie-compliance/index.html")) && !pagesToCheck.some((p) => p.path === "/cookie-compliance")) pagesToCheck.push({ path: "/cookie-compliance" });
 var consentChecks = [];
 var temporalMotion = [];
 var routeJourneys = [];
+var typography = [];
 try {
   try {
     const chromium = await loadPlaywrightChromium();
@@ -424,6 +438,7 @@ try {
     let firstVisit;
     const cookieBanner = page.locator("#vitris-cookie-banner");
     if (await cookieBanner.isVisible()) {
+      if (typePolicy.enabled) typography.push(await captureTypography(page, typePolicy.theme, p.path, width, "first-visit"));
       if (p.path === "/") {
         const path = `${directory}/first-visit-${width}${motion === "reduce" ? "" : "-normal"}.png`;
         await page.screenshot({ path: join2(root, path) });
@@ -484,6 +499,7 @@ try {
       await page.evaluate(`(async () => { await Promise.race([Promise.all([...document.images].filter(i=>i.getClientRects().length).map(i=>{i.loading='eager';return i.decode().catch(()=>{});})),new Promise(r=>setTimeout(r,5000))]); })()`);
       const broken = await page.evaluate(`Array.from(document.images).filter(i=>i.getClientRects().length&&(!i.complete||!i.naturalWidth)).map(i=>i.getAttribute('src'))`);
       failures.push(...broken.map((src) => `Broken tab image: ${src}`));
+      if (typePolicy.enabled) typography.push(await captureTypography(page, typePolicy.theme, p.path, width, `tab-${i}`));
     }
     if (await tabs.count()) await tabs.first().click();
     for (const carousel of await page.locator('[data-island="carousel"]').all()) {
@@ -567,6 +583,7 @@ try {
     const slug = p.path === "/" ? "home" : p.path.replace(/^\//, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/-+$/, "") || "home";
     const screenshot = `${directory}/${slug}-${width}${motion === "reduce" ? "" : "-normal"}.png`;
     await page.evaluate("window.VitrisMotion?.dispose(); window.VitrisCounters?.dispose()");
+    if (typePolicy.enabled) typography.push(...await captureTypographyStates(page, typePolicy.theme, p.path, width));
     const unreadableMotion = await page.locator("[data-motion],[data-reveal],[data-motion-child],[data-reveal-child]").evaluateAll((es) => es.filter((e) => Number(getComputedStyle(e).opacity) < 0.99).map((e) => e.id || e.tagName));
     if (unreadableMotion.length) failures.push(`Motion teardown left final static content hidden: ${unreadableMotion.join(", ")}`);
     await page.evaluate("window.scrollTo(0,0)");
@@ -627,6 +644,10 @@ try {
       }
       const statusBefore = await page.locator('[role="status"]:visible').allTextContents();
       const postsBefore = mockedLeadPosts;
+      if (typePolicy.enabled && !await form.evaluate((e) => e.checkValidity())) {
+        await form.locator("button[type=submit],input[type=submit],button:not([type])").first().click({ timeout: 3e3 });
+        typography.push(await captureTypography(page, typePolicy.theme, p.path, width, "form-invalid"));
+      }
       let supported = true;
       for (const field of await form.locator("input:not([type=hidden]):not([type=submit]),textarea,select").all()) {
         const type = (await field.getAttribute("type") || "text").toLowerCase();
@@ -660,6 +681,7 @@ try {
         const next = page.url();
         const statusAfter = await page.locator('[role="status"]:visible').allTextContents();
         const newStatus = statusAfter.some((text) => text.trim() && !statusBefore.includes(text));
+        if (typePolicy.enabled) typography.push(await captureTypography(page, typePolicy.theme, p.path, width, "form-result"));
         if (mockedLeadPosts === postsBefore) failures.push("Lead form did not reach the mocked POST /api/leads adapter");
         else if (!newStatus && !(new URL(next).searchParams.get("sent") && next !== before)) failures.push("Lead form has no new success state or destination");
       } catch (error) {
@@ -680,8 +702,11 @@ try {
   const compare = (a, b) => a.path.localeCompare(b.path) || a.width - b.width || String(a.motion || a.mode).localeCompare(String(b.motion || b.mode));
   checks.sort(compare);
   routeJourneys.sort(compare);
+  typography.sort((a, b) => compare(a, b) || a.state.localeCompare(b.state));
+  const typographyFailures = typePolicy.enabled ? [.../* @__PURE__ */ new Set([...typography.flatMap((c) => c.failures.map((f) => `${c.path} ${c.width}px ${c.state}: ${f}`)), ...typographyConsistencyFailures(typography)])] : [];
+  for (const failure of typographyFailures) console.log(`Typography: ${failure}`);
   const templateMotion = existsSync(join2(root, TEMPLATE_MOTION_PATH)) ? await captureTemplateMotion(browser, root, `http://127.0.0.1:${address.port}/`, directory + "/template-motion", json(join2(root, TEMPLATE_MOTION_PATH))) : void 0;
-  save(join2(root, `agent/reviews/${name}.json`), { version: 4, sourceHash: sourceHash(root), distHash: fingerprint(root, ["dist"]), scope: name, concurrency, viewports, motionModes, staticMotionState: "complete-after-teardown", motionScenarioHash: MOTION_SCENARIO_HASH, temporalMotion, routeJourneys, checks, routeChecks, consentChecks, ...templateMotion ? { templateMotion } : {}, ...compositionMode ? { compositionTargets } : {} });
+  save(join2(root, `agent/reviews/${name}.json`), { version: 4, sourceHash: sourceHash(root), distHash: fingerprint(root, ["dist"]), scope: name, concurrency, viewports, motionModes, staticMotionState: "complete-after-teardown", motionScenarioHash: MOTION_SCENARIO_HASH, temporalMotion, routeJourneys, checks, routeChecks, consentChecks, ...typePolicy.enabled ? { typography: { scenario: TYPOGRAPHY_SCENARIO, captures: typography, failures: typographyFailures } } : {}, ...templateMotion ? { templateMotion } : {}, ...compositionMode ? { compositionTargets } : {} });
   if (!representative && performancePolicy(root).enabled) {
     const performance = await measurePerformance(root, `http://127.0.0.1:${address.port}`, { log: console.log });
     if (performance.failures.length) {
@@ -690,7 +715,7 @@ try {
     }
   }
   console.log(`${name}: ${checks.length} route/viewport checks`);
-  if (checks.some((c) => c.failures.length) || routeJourneys.some((j) => j.failures.length) || templateMotion?.captures.some((c) => c.failures.length)) process.exitCode = 1;
+  if (typographyFailures.length || checks.some((c) => c.failures.length) || routeJourneys.some((j) => j.failures.length) || templateMotion?.captures.some((c) => c.failures.length)) process.exitCode = 1;
 } finally {
   await browser?.close();
   await new Promise((r) => server.close(() => r()));

package/bin/vitris-verify-performance.js

@@ -7,11 +7,12 @@ import {
 } from "./chunks/chunk-WEFDVXFX.js";
 import {
   buildVerified
-} from "./chunks/chunk-H3BS2EBR.js";
-import "./chunks/chunk-L44ZTNDM.js";
-import "./chunks/chunk-37F7XIMH.js";
-import "./chunks/chunk-LKN75JGA.js";
+} from "./chunks/chunk-WIT6364Y.js";
+import "./chunks/chunk-GPS3SAGQ.js";
+import "./chunks/chunk-JTXFTNEA.js";
+import "./chunks/chunk-GE6UUEG2.js";
 import "./chunks/chunk-YYPYYOEV.js";
+import "./chunks/chunk-S2XVNTQP.js";
 import "./chunks/chunk-GZDLXYZV.js";
 import "./chunks/chunk-T6PE4KN4.js";
 import "./chunks/chunk-7FS67SRF.js";

package/bin/vitris.js

@@ -1,22 +1,22 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunks/chunk-445FZZEC.js";
-import "./chunks/chunk-KIWEFRNG.js";
-import "./chunks/chunk-72Y4YMTV.js";
-import "./chunks/chunk-UR4NWYVW.js";
-import "./chunks/chunk-JBSGJR7X.js";
-import "./chunks/chunk-M72KKZIB.js";
+} from "./chunks/chunk-DDJ3QCRR.js";
+import "./chunks/chunk-SXPLCCO7.js";
+import "./chunks/chunk-AD7WAHW2.js";
+import "./chunks/chunk-SBOUSO3S.js";
+import "./chunks/chunk-KR5ZUZV2.js";
+import "./chunks/chunk-5KRJQKHB.js";
 import "./chunks/chunk-2NW7KSPA.js";
-import "./chunks/chunk-VKU5TY5C.js";
-import "./chunks/chunk-RE4GOHSU.js";
-import "./chunks/chunk-65LRZIBP.js";
+import "./chunks/chunk-MYX4FET4.js";
+import "./chunks/chunk-AS74YXGM.js";
+import "./chunks/chunk-MAPY3YVE.js";
 import "./chunks/chunk-34H54KEY.js";
 import "./chunks/chunk-JCRGE6AL.js";
 import "./chunks/chunk-XL2DRAYI.js";
-import "./chunks/chunk-54QPYUM2.js";
+import "./chunks/chunk-OZD7ZWDX.js";
 import "./chunks/chunk-XGTHGWPW.js";
-import "./chunks/chunk-GQPUILFR.js";
+import "./chunks/chunk-WK7HJI5H.js";
 import "./chunks/chunk-KVMZSQ3D.js";
 import "./chunks/chunk-WOORR67N.js";
 import "./chunks/chunk-PRLL7B63.js";
@@ -26,15 +26,16 @@ import "./chunks/chunk-M4LNHYYR.js";
 import "./chunks/chunk-TY33XMHW.js";
 import "./chunks/chunk-HL6JVA4A.js";
 import "./chunks/chunk-M2ETYSVJ.js";
-import "./chunks/chunk-AUO5I56E.js";
+import "./chunks/chunk-C3F7XQD2.js";
 import "./chunks/chunk-BIEDSEL2.js";
 import "./chunks/chunk-IKNMBGGD.js";
 import "./chunks/chunk-WEFDVXFX.js";
-import "./chunks/chunk-H3BS2EBR.js";
-import "./chunks/chunk-L44ZTNDM.js";
-import "./chunks/chunk-37F7XIMH.js";
-import "./chunks/chunk-LKN75JGA.js";
+import "./chunks/chunk-WIT6364Y.js";
+import "./chunks/chunk-GPS3SAGQ.js";
+import "./chunks/chunk-JTXFTNEA.js";
+import "./chunks/chunk-GE6UUEG2.js";
 import "./chunks/chunk-YYPYYOEV.js";
+import "./chunks/chunk-S2XVNTQP.js";
 import "./chunks/chunk-GZDLXYZV.js";
 import "./chunks/chunk-G7MNMULR.js";
 import "./chunks/chunk-T6PE4KN4.js";

package/design-system/MASTER.md

@@ -74,3 +74,7 @@ New authored sites and reauthored routes compose the entire temporal journey wit
 Used-component CSS only, islands only when needed. Give the actual LCP image priority when there is one; lazy-load images outside the initial view. Avoid `transition: all`.
 
 New builds use original Vitris SVG icons through paired `<vitris-icon name="phone"></vitris-icon>` tags. Read `agent/refs/icons.md`; use `vitris-icons inspect NAME --json` for supported families and sizing. Choose by meaning, keep a coherent family and visible service labels, and verify actual desktop/mobile rendering. The compiler emits only the geometry used by each route, with no client catalog. Studio industry support is curated to eight symbols; never synthesize unavailable variants.
+
+## Shared typography for new sites
+
+New redesigns enable site.json typography version 1. Follow agent/refs/typography.md: shared size, weight, leading, tracking and font roles in theme/defaults.json; 18px body, 16px controls, 14px supporting text and a 12px rendered floor. Ordinary H3s share one responsive treatment across pages. Named, justified role variants preserve deliberate hierarchy. Browser acceptance checks every authored route and exposed interaction states. Historical sites retain their styles until an explicit reviewed adoption; kit upgrades never enable this automatically.

package/docs/ADMIN.md

@@ -1,85 +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.
+# 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.2**. 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.2`. 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.2 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.