Run, preview and test the app

One scaffold for local and CloudflareCopy Anchor Link

wrangler.jsonc is the source of truth for the Worker entry, compatibility flags, bindings and observability. Vite generates dist/server/wrangler.json and .wrangler/deploy/config.json; do not hand-edit or commit either generated file. Both local preview and Wrangler deployment consume the generated production build. Development uses the same Worker source and Cloudflare runtime with hot reload.

Every command for the app, its checks and its deployments, with what each does: Commands. In short, the app runs locally on port 5173 with hot reload (vp run dev) and as the production build on 4173 (vp run preview), and the checks run on that same local host. Every branch other than main gets a preview on Cloudflare: on Cloudflare, below. The agent's own browser on a laptop (pnpm dlx chrome-devtools-mcp, Chrome DevTools) is not CI: the checks never use it.

vp run ci runs the whole suite on the production build, here and on GitHub. To run it against a deployed URL (a branch's Preview, or production):

pnpm remy test remote https://your-worker.your-subdomain.workers.dev

The URL must be an origin, without a path or query. The checks that need a new person read their code from the local mail capture, so they run against the local target only. The rest ask the Worker which environment it is (/healthz) and expect what the table gives it: against a Preview the seeded people are there and one press signs in as one of them; against production none of it exists. The remote test task can also target an already-running local preview to check the external-server path.

The commands are remy-cli's (remy), each reading what it needs where it is kept (the origins: the app's .env); this repository's own are its tasks (the root vite.config.ts: ready, new-app, skills:build, publish) and scripts. The Playwright configuration is the package's playwrightConfig().

There is one Worker configuration, wrangler.jsonc: production, and its previews section for every branch's Preview (its own databases and secret, ENVIRONMENT: "staging", so the test sign-in is on). There is no separate staging Worker: a Preview is it (owner, 2026-10-18). Keep the implementation shared; vary only resource identifiers, secrets and other environment values. Bindings and vars are not inherited by the previews section: each is declared again there. Do not copy the application or use remote bindings for ordinary local development. Local secrets stay in ignored .dev.vars; deployed secrets are managed through Cloudflare. Local data is not uploaded by deployment.

Two kinds of pageCopy Anchor Link

packages/remy-ui/src/paths.js is the one list of pages and says what each kind promises; the two are never mixed.

• Site pages (sitePaths: the home and formats) are for Google: complete in the server's HTML without JavaScript, indexed, in the sitemap with hreflang alternates, and judged by Google's audits. Their frame is SiteShell in shell.tsx, built from static shadcn parts.
• App pages (appPaths, under /app) need JavaScript, carry noindex (added by pageHead) and stay out of the sitemap. Their frame is AppShell in app-shell.tsx, shadcn's sidebar-16 block owned in blocks/sidebar-16.

The docs are not this app's pages: they are the docs Worker (apps/remy-auth-docs/ here, an app's docs/; Fumadocs), with the guide at /docs, these developer docs at /dev and the API reference at /reference, each with search and Ask AI (writing docs). The app's header links there, and its old /<locale>/docs/... addresses redirect there permanently.

The language picker follows the kind: site pages use LanguageSwitcher, plain links that need no JavaScript; app pages use LanguageMenu, shadcn's DropdownMenu calling Paraglide's setLocale (both in language.tsx).

What is implementedCopy Anchor Link

Every page exists in every locale (13 prefixes such as /en, /ar, /ja; the docs pages in English only); the table names them without it.

Localized pages never redirect. When the visitor's preferred language differs from the page, a dismissible hint offers that version; choosing or dismissing is remembered in Paraglide's PARAGLIDE_LOCALE cookie, which only the entry URLs act on. Locale detection, the cookie, URL localisation and the redirect are Paraglide's own strategies and middleware (packages/remy-ui/paraglide.mjs holds the one compiler configuration), wired as Paraglide's official TanStack Start integration: the middleware wraps the Worker entry, and the router's rewrite removes the locale before matching and adds it to every link, so routes carry no locale segment.

TanStack Start runs through Cloudflare's Vite plugin (apps/remy-auth/vite.config.ts, the package's remyApp()). Every route is server-rendered except the demo. In-app links preload their route's code and data on intent; language changes on site pages are full navigations.

shadcn, stockCopy Anchor Link

Components and the theme are what the shadcn CLI writes, in shadcn's monorepo layout: this app's apps/remy-auth/components.json routes shadcn add into the package (packages/remy-ui/components.json), and packages/remy-ui/src/styles/globals.css is written by the CLI too. Nobody edits either by hand; the scripts in package.json are the only way they change:

vp run ui:components       # Re-add every shadcn component (extend the list there to add one)
vp run ui:theme            # Rewrite globals.css with shadcn's default theme
vp run ui:blocks           # Diff each owned block against upstream, in place
vp run ui:verify           # Re-run both and fail on any difference (runs before every release)

Blocks are owned copies, as shadcn intends; sidebar-16's README says what was changed. The package's components alias (@joeblew999/remy-ui/blocks) is where shadcn writes a block's own files when run from the package (shadcn add <block> -c packages/remy-ui): blocks/<name>/components. So ui:blocks diffs them in place and upstream changes are merged by hand.

Fonts live in packages/remy-ui/src/fonts.css, imported after globals.css (see src/styles.css); the file explains its rules. fontaine in the app's Vite configuration (remyApp()) generates the size-matched fallback faces it names. publicPageChecks fails on any named family that is not loaded.

On CloudflareCopy Anchor Link

There is one way to deploy: push. Cloudflare builds and deploys this repository itself, from GitHub; nothing of ours uploads code, and nobody runs wrangler deploy by hand (owner, 2026-10-18: "you've got multiple ways to deploy. It's bloody confusing"). The words, one meaning each:

• Two Workers, one per app, each with its own Git build, both at the repository's main: remy-auth (root /apps/remy-auth) and remy-auth-docs (root /apps/remy-auth-docs), each with its own wrangler.jsonc. Each build installs with pnpm (from pnpm-lock.yaml, the build variable PNPM_VERSION as in devEngines, NODE_VERSION as in .node-version), then runs pnpm vp run build, then pnpm wrangler deploy on main or pnpm wrangler preview elsewhere. These settings live on Cloudflare, not in the repository: they are written here and changed only through the connector, to match.
• From the owner's Mac (signed in to Cloudflare): Wrangler itself (pnpm wrangler deployments list, pnpm wrangler tail, reading only), pnpm remy docs publish after the docs change (Ask AI's index), and remote database migrations. From Claude's cloud (no Cloudflare login for Wrangler): push, and Cloudflare builds; the Cloudflare connector shows a build and its log, changes the build settings and starts a rebuild. Then check a Preview: pnpm remy test remote https://<branch>-remy-auth.gedw99.workers.dev (our checks only: a Preview is hidden from search engines on purpose, so Google's audits judge production).
• Speed far from the databases: the Worker runs with Smart Placement (wrangler.jsonc, checked by pnpm remy verify tooling), and every request reads through its own D1 session, so reads come from the nearest copy (@joeblew999/remy-ui/replicas; a unit check refuses app code using a database binding raw).
• Every D1 database keeps read copies and lives in production's region: the platform's rule, which pnpm remy cloudflare provisioned asks Cloudflare about, the Previews' databases included, naming the fix. Neither is a setting Wrangler's configuration can hold.

Which version is deployedCopy Anchor Link

Nothing records what is deployed: each deployment says what it is when asked, so the answer cannot be out of date (the design is remy-sport's, whose committed record of deployments was wrong for weeks).

• The build stamp. remyApp() and remyDocs() work it out once per build from the sources: the app's package, the commit, a short hash of anything uncommitted, and the installed version of each platform package (build: { packages: [...] } in remyApp() lists more). The same checkout builds the same stamp; there is no build time in it, so a bundle changes only when its code does.
• /healthz, on every Worker built on the package, answers with it: service, environment (what the Worker declares; production when it declares none), release and deployedAt (Cloudflare's version and when it was given it) and build. It names nobody, and any origin may read it.
• BuildStamp (@joeblew999/remy-ui/versions) is in the app frame's footer, so every app page of every app has it: the environment unless it is production, the product's name, the commit. The page carries the stamp it was built with; when its deployment answers with another, the page is a tab left open across a deploy, and the stamp offers the reload. It never reloads by itself.
• Versions, for a settings or about page: this app, its docs Worker (docs in defineRemyApp) and the deployments the app lists there (a service it calls), each answering for itself, then the packages this build was made with. remy-auth's Settings page shows it.
• pnpm remy cloudflare versions prints a row per deployment (the origins in the app's .env, or the origins given), with each commit placed against this checkout: = HEAD, 3 behind HEAD. Use it before saying what is live.

The shared check sets prove it in every app: /healthz names this checkout's commit on a local run (a stamp left over from an earlier build fails), and the frame offers the reload only when the deployment has moved on.

The product's nameCopy Anchor Link

Remy is this prototype's name. A project built on the same code has its own, and writes it once:

// docs/docs.config.ts: the docs say it, and the app takes it from here
const product = 'Harbor';
export const docsConfig = defineDocsConfig({ product, ... });

// src/remy-app.tsx
export const remyApp = defineRemyApp({ brand: docsConfig.product, ... });

An app without docs writes brand directly. Everything a person reads takes the name from there: the frame, every page's title, the home page's structured data, and every message that says the name, which takes it as a parameter:

m.home_title({ product: useRemyApp().brand }, { locale })                       // in a page
pageHead({ ..., description: (locale, product) => m.home_description({ product }, { locale }) })   // in a head
codeMail({ otp, product }, locale)                                              // the sign-in email

A message that names the product is written with {product}, never with a name, so Paraglide's types refuse a caller that leaves it out. remy-auth's Settings page shows where the name is used, and how each place reads under another name.

What is not the product's name, and stays: the packages (@joeblew999/remy-ui), the remy skill, task names, a Worker's service name and an MCP server's name. Those are identifiers a developer sees.

Checks: every page's title ends with the app's name, and an app of another name never shows "Remy" (productNameChecks, in every app's shared set; the consumer fixture, called "My app", is where it bites); the platform's catalog names no product (tests/product.spec.ts).

Structure and reuseCopy Anchor Link

The app is apps/remy-auth/ (its paths below are from there); the packages beside it are packages/*, the docs apps/remy-auth-docs/, all one pnpm workspace (pnpm-workspace.yaml) whose root holds the repository's own checks.

• src/routes/: TanStack file routes (loaders, head, per-route rendering) that render the package's pages, plus this app's extra formats rows (src/formats-extras.tsx), while robots.txt and sitemap.xml (the seo-routes part) and /csp-report (app-routes) are the package's server routes, mounted beside them; src/routeTree.gen.ts is generated by the router plugin during dev and build and committed.
• src/server.ts: Worker entry through the package's localizedWorker (request IDs, structured status logs, /healthz, Paraglide's middleware, entry redirects). Start receives the original request, so server functions read Cloudflare's geolocation from the request's cf properties in a server-only module under Start's import protection (packages/remy-showcase/src/parts/deferred-place/place.server.ts, the showcase's deferred-place part). The wrapper passes its request ID inward as X-Request-ID; Start's request middleware exposes it as context.requestId, and a function middleware logs one server_fn line per call (the package's start, registered in src/start.ts). A second request middleware there makes the per-request CSP nonce that the shared router (router) hands to TanStack Router, and the package's server route /csp-report (app-routes) logs the policy's reports (security headers). The service name has one home, src/service.ts.
• src/api/: the contract's implementation (router.ts, behind the guard; no Workers imports so the checks load it in Node), each call's context, with the caller's session (context.server.ts), and the isomorphic client with its TanStack Query utilities (client.ts). The contract is packages/remy-auth-contract/; the shared mechanism is the package's api/* exports; the contracts plan owns the design.
• src/auth/: Better Auth in this Worker (the auth plan): its options, shared by the Worker and the CLI (options.ts), the instance built on first use from the D1 binding (auth.server.ts), the CLI's configuration (cli.ts), the environment table (environment.ts), the seeded people (seed.ts, people.server.ts), mail delivery and the code's email (mail.server.ts, code-mail.ts), the rule on fields a person can write (fields.ts), the account server function (account.ts) and the sign-in form, its picker and Better Auth's browser client (sign-in.tsx, client.ts). migrations/ holds the numbered D1 migrations (the Better Auth scripts).
• src/notes/: the notes demo, which uses the relation engine as any app would: its data in its own D1 (DEMO_DB, migrations-demo/; a person is only an account ID there) through store.ts, the page (page.tsx) and the server function its loader asks (state.ts). The vocabulary and the shapes are the contract's (packages/remy-auth-contract/src/notes.ts).
• src/router.tsx: the package's remyRouter, a new router and TanStack Query client per request, with Query's SSR integration. src/routes/__root.tsx is the package's remyRoot with this app's config; TanStack Devtools (Router and Query panels) is passed in there, in the app's own file, because its devtools() Vite plugin strips it from production builds only outside node_modules; the build-boundary check proves no devtools or server-only code reaches the browser.
• src/parts.json: the package's parts this app uses, one per line (the showcase's @joeblew999/remy-showcase/time-zones, deferred-place and status-card, and the platform's seo-routes); remyApp() (in vite.config.ts) mounts their routes and partChecks() in tests/gui.spec.ts runs their checks.
• packages/remy-ui/ (at the root): everything both apps share; its README lists the exports.
• tests/: the app's browser checks: the package's shared checks (@joeblew999/remy-ui/checks, the showcase's @joeblew999/remy-showcase/*.checks) plus the checks only this repository owns (catalogs, concurrent server renders, hydration, its extra formats rows); lighthouse.spec.ts is vp run ci's audits part and performance.spec.ts the release's Core Web Vitals.

Locale is passed explicitly into compiled message functions; concurrent requests share no mutable locale state. The catalogs are the locales in settings.json; every one except English and Spanish was written by an agent and is unreviewed. Direction, endonyms, dates, numbers, currency and plurals follow the decisions recorded in the GUI plan.

The package's real consumer is remy-auth-app, which installs the published package and runs its checks on prerendered pages, while this app runs them on server-rendered ones.

Evidence and limitsCopy Anchor Link

vp run ci runs every check (vp run ready), then the browser checks (test:browser), then Google's Lighthouse audits (test:audits) and, in remy-auth, a brand-new app on this commit's package (new-app), one after the other: the audits measure speed, so they never run beside another browser run. GitHub runs the same tasks as parallel jobs (the browser checks in three slices, vp run test:browser --shard 1/3). Core Web Vitals on a deployment are the release's (pnpm remy test cwv: production, or a Preview's origin). There are no levels to choose and no part decides to skip itself, and what nothing touched comes from Vite Plus's cache instead of running again. What is tested is decided once, by what a check can show (owner, 2026-10-17: "you really need to decide what is tested and what isn't"):

• A check of how text is drawn (fonts and scripts, hyphenation, direction, fitting a phone, formats) runs in one language per way the app draws text (checkedLocales): each language fonts.css gives its own font stack, each Han language, and English for the shared default stack; 9 of the 13 today, worked out from fonts.css. Spanish, Polish, Turkish and German draw exactly as English does.
• A check of behaviour that does not depend on the language (the security policy, noindex, search params, the demo form, error pages, API answers) runs in English and the first right-to-left language (behaviourLocales).
• What does differ in every language is checked in every language: the catalogs and their plurals (the unit checks), the sitemap, hreflang and the language switcher, and the casing and hyphenation samples.
• A release runs every check in every language (CHECK_LOCALES=all, its script sets it). By hand, CHECK_LOCALES takes all, quick (English and Arabic) or a comma-separated list. What the checks cover is the checks themselves: tests/ and the package's @joeblew999/remy-ui/checks (each check's title says what it proves); the flow's steps that run them are in how we work. In short: every page in every language without JavaScript (language, direction, metadata, links), catalogs and plurals, the formats values against Intl, entry redirects and the language hint, hydration, the demo form and the API, HTTP statuses, the sitemap and hreflang, security headers and the CSP nonce, narrow screens, and the docs, search and ask pages.

Google's level covers site pages only (app pages are noindex by design): Lighthouse audits /en (mobile and desktop), /es, /ar and /en/formats (tests/lighthouse.spec.ts); Core Web Vitals, from Google's pinned lighthouse package, judge /en (mobile and desktop) and /en/formats (tests/performance.spec.ts) against Google's good thresholds (LCP 2.5 s, CLS 0.1, TBT 200 ms, Performance at least 0.9), on a deployment (pnpm remy test cwv: production unless a Preview's origin is given), not localhost.

Limits: no organizations, OAuth tokens or cross-app sign-in yet, so only remy-auth's own pages know who is signed in (the auth plan). The site is served from its workers.dev address (VITE_DEPLOY_ORIGIN in the app's .env); the production public origin and Search Console are owner decisions (now).

Known tooling notices: Node may print the Chrome DevTools localStorage experimental warning; pnpm runs no install script outside allowBuilds (pnpm-workspace.yaml) and may name the ones it skipped; Vite's isolated package check may report that Base UI's use client directives are ignored in a plain client bundle. These notices do not change the tested behaviors.