ci(web): codify the Vercel deployment

AGENTS.md

@@ -117,10 +117,9 @@ If a change brushes against any of these, stop and record a decision in
 - Docs: feature docs live in the phase contracts (P0/P1/P2 style — contract,
   deferrals, known limitations). Keep README claims backed by tests or
   evidence.
-- Web (`apps/web`): content is currently hand-duplicated in three places
-  (backlog §F2) — if you change CLI behavior, grep the site
-  (`app/docs/page.tsx`, `components/docs-markdown.ts`, `README.md`) and
-  update all copies.
+- Web (`apps/web`): rendered content derives from `README.md`,
+  `apps/headless/docs/COMMANDS.md`, and the generated benchmark results. Update
+  those sources when CLI behavior changes; web lint checks their provenance.
 - Commits: conventional-ish prefixes in use (`feat:`, `fix:`, `docs:`,
   `ci:`, scope in parens like `fix(macos):`).
 
@@ -130,3 +129,13 @@ Tags `v*` trigger `.github/workflows/release.yml` (macOS zip + Linux
 tarballs). `HEADLESS_VERSION` flows from the tag; protocol version (`"0.5"`
 in `Protocol.swift`) is independent — bump it only for wire-visible changes,
 with a decision entry.
+
+## Website deployment
+
+Vercel deploys `apps/web` from the repository root using
+[`vercel.json`](vercel.json). The production branch is `main`, and the
+canonical production URL is <https://headless-web-pi.vercel.app>. Keep the
+Vercel for GitHub integration enabled for pull-request previews and preview-URL
+comments. Do not add a second deployment workflow that can race the integration.
+Hosting setup, verification, rollback, and the custom-domain decision are in
+[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).

apps/web/package.json

@@ -6,7 +6,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-bundle-policy.mjs && eslint .",
+    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
     "brand": "node scripts/render-brand.mjs"
   },
   "dependencies": {

apps/web/scripts/validate-deployment-config.mjs

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "../../..");
+const read = (path) => readFile(resolve(root, path), "utf8");
+const config = JSON.parse(await read("vercel.json"));
+
+assert.deepEqual(config, {
+  $schema: "https://openapi.vercel.sh/vercel.json",
+  framework: "nextjs",
+  buildCommand: "pnpm --filter @headless/web build",
+  devCommand: "pnpm --filter @headless/web exec next dev --port $PORT",
+  outputDirectory: "apps/web/.next",
+});
+
+const productionUrl = "https://headless-web-pi.vercel.app";
+const [metadata, deploymentDocs, agentRules, nextConfig, rootPackage, lockfile] =
+  await Promise.all([
+    read("apps/web/lib/site-metadata.ts"),
+    read("docs/DEPLOYMENT.md"),
+    read("AGENTS.md"),
+    read("apps/web/next.config.ts"),
+    read("package.json"),
+    read("pnpm-lock.yaml"),
+  ]);
+
+const packageJson = JSON.parse(rootPackage);
+assert.match(packageJson.packageManager ?? "", /^pnpm@9\./);
+assert.match(packageJson.engines?.pnpm ?? "", />=9/);
+assert.match(lockfile, /^lockfileVersion: ['"]?9\.0['"]?$/m);
+assert.equal(config.installCommand, undefined);
+
+for (const source of [metadata, deploymentDocs, agentRules]) {
+  assert.match(source, new RegExp(productionUrl.replaceAll(".", "\\.")));
+}
+
+assert.doesNotMatch(JSON.stringify(config), /headers|contentSecurityPolicy/i);
+for (const header of [
+  "Content-Security-Policy",
+  "Permissions-Policy",
+  "Referrer-Policy",
+  "X-Content-Type-Options",
+  "X-Frame-Options",
+]) {
+  assert.match(nextConfig, new RegExp(`key: "${header}"`));
+}
+for (const directive of [
+  "base-uri 'none'",
+  "frame-ancestors 'none'",
+  "object-src 'none'",
+]) {
+  assert.match(nextConfig, new RegExp(directive.replaceAll("'", "\\'")));
+}
+
+console.log("Vercel deployment configuration is consistent");

docs/DEPLOYMENT.md

@@ -0,0 +1,65 @@
+# Website deployment
+
+The marketing and documentation site is deployed to Vercel from this monorepo.
+The repository configuration in [`vercel.json`](../vercel.json) is the source
+of truth for framework detection, build and development commands, and output
+location. Vercel derives pnpm from the root lockfile. Do not add an install
+override with plain `pnpm install`: Vercel uses its oldest available pnpm
+runtime for that override, while this repository requires pnpm 9 or newer.
+
+## Production contract
+
+- **Production branch:** `main`.
+- **Production URL:** <https://headless-web-pi.vercel.app>.
+- **Project root:** the repository root, not `apps/web`.
+- **Application:** `apps/web` (`@headless/web`).
+- **Security headers:** `apps/web/next.config.ts`. Do not duplicate them in
+  `vercel.json`, where they could drift from local and CI builds.
+
+The Vercel project alias is the canonical domain for now. The LockInTime
+organization does not publish a verifiable custom domain in repository or
+organization metadata, so this project must not claim one. A custom domain can
+replace the alias only after a maintainer confirms control of its DNS. That
+change must update `apps/web/lib/site-metadata.ts`, the GitHub repository
+homepage, this document, and the Vercel production-domain assignment together.
+
+## GitHub integration
+
+Connect the `LockInTime/headless` repository through Vercel for GitHub with
+these project settings:
+
+1. Leave Root Directory empty so Vercel reads the root `vercel.json` and the
+   workspace lockfile.
+2. Set the production branch to `main`.
+3. Keep preview deployments enabled for pull requests and branch pushes.
+4. Keep pull-request comments enabled so each PR receives its immutable preview
+   URL. Keep deployment status events enabled so the URL also appears in the
+   GitHub deployment timeline.
+5. Do not add a second token-driven GitHub Actions deployment. Two independent
+   deployers can race production aliases and make rollback history ambiguous.
+
+The integration is an account-level control and cannot be stored in git. If a
+PR has no Vercel deployment or preview link, treat that as a disconnected or
+disabled integration. A Vercel project maintainer must reconnect the repository
+under Project Settings, Git before the PR is considered deployment-verified.
+
+## Verification
+
+Run the same web gates locally before pushing:
+
+```sh
+pnpm install --frozen-lockfile --filter @headless/web
+pnpm --filter @headless/web lint
+pnpm --filter @headless/web build
+```
+
+For a pull request, open the Vercel preview from the PR deployment entry and
+check the homepage, one docs route, `robots.txt`, and `sitemap.xml`. Confirm the
+response still carries the CSP, `X-Content-Type-Options`, `X-Frame-Options`,
+`Referrer-Policy`, and `Permissions-Policy` headers declared in
+`apps/web/next.config.ts`.
+
+After merging, verify that the production deployment points at the merge commit
+and that <https://headless-web-pi.vercel.app> serves it. Vercel keeps prior
+production deployments available for rollback. Roll back in Vercel, then
+revert the faulty commit in git so repository history and production converge.

docs/ROADMAP.md

@@ -103,7 +103,7 @@ summary|outline|text|actions|full`, `--task`, `--within @rN`, `--budget`)
   notarization/stapling, a checksum-pinned Homebrew cask, the verified Linux
   bootstrap, release checksums, and a multi-platform GHCR image. These paths
   become user-visible with the next tag.
-- A Next.js marketing/docs site (`apps/web`) — built, not deployed.
+- A Next.js marketing/docs site (`apps/web`) deployed to Vercel from `main`.
 - An agent skill (`.agents/skills/headless-computer-use/`) with safety rules,
   command reference, and a Docker sandbox wrapper.
 
@@ -118,9 +118,8 @@ summary|outline|text|actions|full`, `--task`, `--within @rN`, `--budget`)
   unimplemented.
 - The latest features (capture formats, context pruning) are **unreleased** —
   no tag since v1.0.2 (2026-07-19).
-- No `CLAUDE.md`/`AGENTS.md`; the skill is not auto-discovered by Claude Code.
-- The website's benchmark numbers, docs prose, and commands are hand-copied in
-  three places each and will drift; the site has no deploy pipeline.
+- The website deployment configuration is versioned, but GitHub-to-Vercel
+  preview and production deployments remain unverified.
 - Windows is not supported.
 - A list of real code defects (thread-safety on shutdown, oversized `qa
 report` responses, `@eN` ref invalidation surprises, host code duplication)
@@ -265,7 +264,8 @@ and drive Headless with zero manual prompting beyond repo checkout.
 
 ### Phase 5 — Website and docs as a product surface
 
-- Deploy `apps/web` (Vercel or static export + CDN) with CI.
+- Keep the Vercel deployment of `apps/web` reproducible, previewable, and
+  verified alongside CI.
 - Kill the three-copy content drift: docs prose and benchmark numbers come
   from single sources (benchmark emits JSON; site imports it; command tables
   generated from the CLI) (backlog §F).

docs/roadmap/improvements-backlog.md

@@ -408,14 +408,7 @@ Owner-decided scope: package managers, no hosted service.
 
 ## §F — Website & docs (Phase 5)
 
-- **F1. Deploy pipeline is invisible to the repo** ([#47](https://github.com/LockInTime/headless/issues/47)) — the site _is_ live at
-  `https://headless-web-pi.vercel.app` (set as the repo homepage) via Vercel's
-  GitHub integration, but nothing in the tree records that: no `vercel.json`,
-  no deploy docs, no preview-URL comment on PRs, and the temporary
-  `*-pi.vercel.app` hostname suggests no custom domain. Make the deployment
-  reproducible and reviewable — check in the project config, document the
-  hosting in `AGENTS.md`, and decide on a domain. Keep the existing headers/CSP
-  in `next.config.ts`; consider a nonce so `unsafe-inline` can be dropped.
+- **F1. Deploy pipeline is invisible to the repo** ([#47](https://github.com/LockInTime/headless/issues/47)) — **Repository side ready:** root deployment settings are versioned and linted, the GitHub preview and rollback contract is documented, security headers remain in Next.js, and the proven Vercel project alias is canonical until the organization publishes a controlled custom domain. **Pending account verification:** reconnect the Vercel for GitHub integration and confirm a PR preview plus a `main` production deployment before checking this item off.
 - **F2. Content provenance** ([#48](https://github.com/LockInTime/headless/issues/48)) — ~~benchmark numbers hand-copied in
   `app/page.tsx:26-38`, `components/efficiency-chart.tsx:26-31`,
   `components/benchmark-chart.tsx:21-26` (+ date in two places); docs prose

vercel.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "buildCommand": "pnpm --filter @headless/web build",
+  "devCommand": "pnpm --filter @headless/web exec next dev --port $PORT",
+  "outputDirectory": "apps/web/.next"
+}