Publishing this site

This VitePress tree (docs-public/) is static HTML. Production is a dedicated Vercel project (not the main product app in the same monorepo), usually on a personal domain.

Local

pnpm run docs:public:dev       # hot reload (usually :5173)
pnpm run docs:public:build     # → docs-public/.vitepress/dist
pnpm run docs:public:preview

Vercel (one-time)

New project from the monorepo Git remote:

Setting	Value
Framework	Other
Install	pnpm install
Build	pnpm run docs:public:build
Output	docs-public/.vitepress/dist
Node	20.x

No secrets required for the static build.

Optional env on the Vercel project: DOCS_PUBLIC_SITE_URL (absolute origin, e.g. https://notes.example.com) so Open Graph / Twitter image meta uses a full URL. Without it, the build uses VERCEL_PROJECT_PRODUCTION_URL when available, otherwise a root-relative /og-image.png.

Deploy day-to-day

Preferred: Git push to the branch connected to the docs-public Vercel project (production + preview deploys).

CLI (this monorepo, current tree): ship without waiting for Git — targets the docs project only:

pnpm run docs:public:build
pnpm exec vercel deploy --prod --yes --project=docs-public

Do not use pnpm run deploy / bare vercel --prod from a directory linked to the brochure app (root .vercel is often the Next product). That is a different Vercel project.

Clean URLs

VitePress uses cleanUrls: true (paths without .html). The monorepo root vercel.json sets "cleanUrls": true so Vercel serves /tooling/eslint → tooling/eslint.html. A copy of the intent also lives at docs-public/vercel.json.

Domain (registrar DNS)

At Vercel: add apex + www, pick a redirect direction.

At the DNS host (e.g. GoDaddy), typical records:

Type	Name	Value
A	@	76.76.21.21 (or the IP Vercel shows)
CNAME	www	cname.vercel-dns.com (or the target Vercel shows)

Keep existing nameservers if DNS stays at the registrar. Avoid “domain forwarding” for the same hostnames. Leave email-related TXT (e.g. DMARC) alone.

Related

• Claude Code hooks — quality gate before you push
• Grok agent hooks — same bar for Grok sessions