@tryvitris/website-harness 1.0.2 → 1.1.0

package/docs/CLI.md

@@ -1,312 +1,314 @@
-# 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
-
-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 --save-exact @tryvitris/website-harness@1.0.0
-npx vitris --help
-```
-
-Within the `@tryvitris/website-harness` repository itself:
-```bash
-npm run build:cli
-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
-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 input first reads the hosted gallery catalog and pins the selected entry and its hash in `agent/template-input.json`. If the catalog is unavailable, the command warns and uses the bundled snapshot, which may be stale. A template absent from that snapshot cannot be selected offline.
-- `--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.
-
-New redesign sites enable `site.json.typography: {"version":1}` and ship concrete shared roles in `theme/defaults.json`. Defaults are 18px body, 16px controls/navigation, 14px supporting text and one responsive 24–32px H3 treatment. The 12px rendered minimum is a harness quality policy. See [the typography guide](../agent/refs/typography.md) for role tokens, named variants, font weights and reviewed adoption on an existing site. Existing sites and preserve-mode captures retain their current rendering; upgrading the harness does not opt them in.
-
-For enabled sites, `npm run verify:browser -- --site .` records typography evidence in `agent/reviews/browser.json`, checks every authored route even if omitted from the storyboard, and blocks completion on undersized text or inconsistent roles. Checks cover resting text, supported disclosures/tabs and form validation/results. Refinement verification retains this policy and cannot skip browser checks. New template publication validates every original/branded route before changing the catalog. Custom widgets and text embedded in images still need visual review.
-
----
-
-### `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` 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 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 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.
-
----
-
-### `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.
+# 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
+
+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 --save-exact @tryvitris/website-harness@1.0.0
+npx vitris --help
+```
+
+Within the `@tryvitris/website-harness` repository itself:
+```bash
+npm run build:cli
+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
+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 input first reads the hosted gallery catalog and pins the selected entry and its hash in `agent/template-input.json`. If the catalog is unavailable, the command warns and uses the bundled snapshot, which may be stale. A template absent from that snapshot cannot be selected offline.
+- `--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.
+
+New redesign sites enable `site.json.typography: {"version":1}` and ship concrete shared roles in `theme/defaults.json`. Defaults are 18px body, 16px controls/navigation, 14px supporting text and one responsive 24–32px H3 treatment. The 12px rendered minimum is a harness quality policy. See [the typography guide](../agent/refs/typography.md) for role tokens, named variants, font weights and reviewed adoption on an existing site. Existing sites and preserve-mode captures retain their current rendering; upgrading the harness does not opt them in.
+
+For enabled sites, `npm run verify:browser -- --site .` records typography evidence in `agent/reviews/browser.json`, checks every authored route even if omitted from the storyboard, and blocks completion on undersized text or inconsistent roles. Checks cover resting text, supported disclosures/tabs and form validation/results. Refinement verification retains this policy and cannot skip browser checks. New template publication validates every original/branded route before changing the catalog. Custom widgets and text embedded in images still need visual review.
+
+---
+
+### `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` 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 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 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.
+
+---
+
+### `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.
+
+For explicitly requested appointment booking, read [SCHEDULING.md](SCHEDULING.md). Public `launch.json.scheduling` metadata enables the standard route on compatible source/release builds; no scheduling setup CLI, remote migration or production activation is implied.