@getvitops/create 0.8.2 → 0.9.0-alpha.1

package/templates/emdash/site.json

@@ -23,8 +23,14 @@
             }
           },
           "roles": {
-            "neutral": { "hue": "ink", "kind": "surface" },
-            "surface": { "hue": "ink", "kind": "surface" },
+            "neutral": {
+              "hue": "ink",
+              "kind": "surface"
+            },
+            "surface": {
+              "hue": "ink",
+              "kind": "surface"
+            },
             "ui-primary": "brand",
             "brand-primary": "brand",
             "info": "sky",
@@ -93,6 +99,13 @@
               "br": "0.5rem",
               "p": "1rem",
               "fs": "var(--fs-default)"
+            },
+            "label": {
+              "ds": "var(--ds-default)",
+              "b": "none",
+              "br": "0.25rem",
+              "p": "0.25em 0.5em",
+              "fs": "0.75rem"
             }
           },
           "z": {
@@ -126,7 +139,8 @@
                   "ring": true
                 }
               },
-              "roles": []
+              "roles": ["success", "danger", "warning", "info"],
+              "class": "btn"
             },
             "card": {
               "group": "panel",
@@ -140,6 +154,51 @@
               },
               "states": {},
               "roles": []
+            },
+            "badge": {
+              "group": "label",
+              "class": "badge",
+              "default_role": "brand-primary",
+              "overrides": {
+                "p": "0.2em 0.6em",
+                "br": "999px",
+                "fs": "0.85em"
+              },
+              "base": {
+                "display": "inline-block",
+                "padding": "var(--p-badge-group)",
+                "border-radius": "var(--br-badge-group)",
+                "font-size": "var(--fs-badge-group)",
+                "font-weight": "600",
+                "color": "var(--color-text-on-brand-primary)"
+              },
+              "states": {},
+              "roles": ["success", "danger", "warning", "info"]
+            },
+            "tag": {
+              "group": "label",
+              "class": "tag",
+              "default_role": "neutral",
+              "overrides": {
+                "p": "0.25em 0.6em",
+                "b": "1px solid currentColor",
+                "fs": "0.85em"
+              },
+              "base": {
+                "display": "inline-flex",
+                "align-items": "center",
+                "gap": "0.25em",
+                "padding": "var(--p-tag-group)",
+                "border": "var(--b-tag-group)",
+                "border-radius": "var(--br-tag-group)",
+                "font-size": "var(--fs-tag-group)",
+                "font-weight": "500",
+                "line-height": "1.2",
+                "white-space": "nowrap",
+                "color": "var(--color-text-neutral-bold)"
+              },
+              "states": {},
+              "roles": ["success", "danger", "warning", "info"]
             }
           }
         },
@@ -168,6 +227,46 @@
               "size": "var(--text-m)",
               "weight": 400,
               "line-height": "1.55"
+            },
+            "title": {
+              "family": "display",
+              "size": "var(--text-2xl)",
+              "weight": 600,
+              "line-height": "1.15",
+              "tracking": "-0.025em",
+              "text-wrap": "balance"
+            },
+            "lead": {
+              "family": "sans",
+              "size": "var(--text-l)",
+              "weight": 400,
+              "line-height": "1.5",
+              "text-wrap": "pretty"
+            },
+            "caption": {
+              "family": "sans",
+              "size": "var(--text-s)",
+              "weight": 400,
+              "line-height": "1.3",
+              "text-wrap": "pretty",
+              "color": "var(--color-text-neutral-muted)"
+            },
+            "eyebrow": {
+              "family": "sans",
+              "size": "var(--text-s)",
+              "weight": 600,
+              "line-height": "1.3",
+              "tracking": "0.08em",
+              "text-transform": "uppercase",
+              "text-wrap": "balance"
+            },
+            "footnote": {
+              "family": "sans",
+              "size": "var(--text-xs)",
+              "weight": 400,
+              "line-height": "1.4",
+              "text-wrap": "pretty",
+              "color": "var(--color-text-neutral-muted)"
             }
           },
           "headings": {

package/templates/emdash/src/cloudflare-workers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Worker's bindings, as `src/pages/api/track.ts` reads them. Deliberately loose: the route
+ * looks each secret up by name and checks it is a string, so the real binding types (which depend
+ * on what `wrangler.jsonc` declares) are not needed to typecheck it. Replace with the output of
+ * `wrangler types` if you want them.
+ */
+declare module 'cloudflare:workers' {
+  export const env: Record<string, unknown>;
+}

package/templates/emdash/src/layouts/Layout.astro

@@ -3,7 +3,11 @@ import VitopsHead from '@getvitops/astro/Head.astro';
 import { resolveOrganizationName } from '@getvitops/astro/routes';
 import { getMenu, getSiteSettings } from 'emdash';
 import { createPublicPageContext } from 'emdash/page';
+import SiteFooter from '@getvitops/astro/components/SiteFooter.astro';
+import SiteNav from '@getvitops/astro/components/SiteNav.astro';
+import { loadNavMenus } from '@getvitops/astro/components/sitenav.ts';
 import { EmDashHead } from 'emdash/ui';
+import { VitopsWidgetArea } from '@getvitops/emdash/astro';
 import config from '../../site.json' with { type: 'json' };
 // Design-system CSS, layout-scoped (vitops css.inject: false): only pages
 // rendered through this layout get it — keeps it out of /_emdash/admin, while
@@ -42,18 +46,18 @@ const pageCtx = createPublicPageContext({
   siteName: siteTitle,
 });
 
-// Editor-managed navigation (seeded as "primary" and "footer"; edit under
-// Menus in the admin). Falls back to a bare home link if the menu is deleted.
-const menu = await getMenu('primary');
-const navLinks = menu?.items?.length
-  ? menu.items.map((item) => ({ label: item.label, href: item.url ?? '/' }))
-  : [{ label: 'Home', href: '/' }];
-const footerMenu = await getMenu('footer');
-const footerLinks = (footerMenu?.items ?? []).map((item) => ({
-  label: item.label,
-  href: item.url ?? '/',
-}));
-const year = new Date().getFullYear();
+// Editor-managed navigation, read from EmDash menus (edit under Menus in the admin):
+//   `primary`         header nav (the logo is the home link, so it holds no Home item).
+//                     Nested items become dropdowns; an item's `titleAttr` is its description.
+//   `primary-mobile`  OPTIONAL — a simpler depth-1 nav that replaces `primary` below `md`.
+//   `primary-mega`    OPTIONAL — a mega menu that replaces `primary` from `xl`.
+//   `footer-sitemap`, `footer-legal`  footer columns.
+// Variants need no code change: create the menu and <SiteNav> picks it up. A missing menu
+// renders nothing rather than failing (a fresh DB before the seed has applied).
+const nav = await loadNavMenus(getMenu);
+const footerSitemap = await getMenu('footer-sitemap');
+const footerLegal = await getMenu('footer-legal');
+const orgName = config.organization?.name || siteTitle;
 ---
 
 <!doctype html>
@@ -69,23 +73,18 @@ const year = new Date().getFullYear();
     <VitopsHead />
   </head>
   <body>
+    <!-- Widget areas (Widgets in the admin): the same content wherever they appear. -->
+    <VitopsWidgetArea name="announcement" class="centered" />
     <header class="navbar-sticky centered">
       <div class="navbar">
         <a class="brand flex items-center" href="/" aria-label={`${siteTitle} home`}>
           <span class="brand-mark" set:html={logo} aria-hidden="true" />
           <span class="font-heading">{siteTitle}</span>
         </a>
-        <nav aria-label="Primary">
-          <ul class="nav-items justify-center">
-            {
-              navLinks.map((link) => (
-                <li>
-                  <a href={link.href}>{link.label}</a>
-                </li>
-              ))
-            }
-          </ul>
-        </nav>
+        <div class="header-end flex items-center">
+          <SiteNav {...nav} />
+          <wc-color-scheme-toggle></wc-color-scheme-toggle>
+        </div>
       </div>
     </header>
 
@@ -93,24 +92,9 @@ const year = new Date().getFullYear();
       <slot />
     </main>
 
-    <footer class="centered">
-      {
-        footerLinks.length > 0 && (
-          <nav aria-label="Footer">
-            <ul class="nav-items justify-center">
-              {footerLinks.map((link) => (
-                <li>
-                  <a class="font-caption" href={link.href}>
-                    {link.label}
-                  </a>
-                </li>
-              ))}
-            </ul>
-          </nav>
-        )
-      }
-      <p class="font-caption text-neutral-muted">© {year} {siteTitle}</p>
-    </footer>
+    <VitopsWidgetArea name="pre-footer" class="centered" />
+
+    <SiteFooter class="centered" sitemap={footerSitemap} legal={footerLegal} name={orgName} />
 
     <style>
       .brand {
@@ -129,10 +113,8 @@ const year = new Date().getFullYear();
         block-size: 64px;
       }
 
-      footer {
-        margin-block-start: var(--space-2xl);
-        padding-block: var(--space-l);
-        border-block-start: 1px solid var(--color-border-neutral);
+      .header-end {
+        gap: var(--space-s, 0.75rem);
       }
     </style>
   </body>

package/templates/emdash/src/pages/404.astro

@@ -1,9 +1,10 @@
 ---
 import Layout from '../layouts/Layout.astro';
 
-// No per-request data — safe to prerender per AGENTS.md's "Prerender by
-// default" rule. [...slug].astro reaches this via Astro.rewrite('/404'),
-// which resolves a prerendered destination the same as a server-rendered one.
+// Prerendered to /404.html. Astro serves it, with a 404 status, for any URL no
+// route matches — including every slug not in [...slug].astro's getStaticPaths.
+// Nothing rewrites to this page: rewriting an on-demand route to a prerendered one
+// is what used to turn unknown URLs into 500s.
 export const prerender = true;
 ---
 

package/templates/emdash/src/pages/[...slug].astro

@@ -1,23 +1,33 @@
 ---
-import { getEmDashEntry } from 'emdash';
+import { getEmDashCollection } from 'emdash';
 import { PortableText } from 'emdash/ui';
 import Layout from '../layouts/Layout.astro';
 
-// Catch-all: any entry in the `pages` collection renders at its slug.
+// Prerendered: every published entry in `pages` becomes a static HTML file at
+// its slug, written at build time and served as a static asset. The build reads
+// the content database — `scripts/pull-content.mjs` loads production's into the
+// local build database first (it is part of `deploy`/`deploy:dev`) — so an edit
+// in the admin goes live on the next rebuild, which a publish webhook triggers
+// (see AGENTS.md "Rendering and freshness").
 //
-// Deliberately NOT prerendered, unlike AGENTS.md's general "prerender by
-// default" rule — see index.astro's comment for why: a live EmDash publish
-// should reach visitors without a redeploy. A page that's known ahead of
-// time and doesn't need that (rarely edited, or fine to lag a build) can
-// move to its own prerendered route with `getStaticPaths()` over the
-// `pages` collection instead of relying on this catch-all.
-const { slug } = Astro.params;
-const { entry: page } = slug ? await getEmDashEntry('pages', slug) : { entry: null };
+// There is no `Astro.rewrite('/404')` here and no on-demand fallback: a URL that
+// isn't in the list below simply has no route, so Astro serves the prerendered
+// `404.astro` with a real 404 status. (The previous version rewrote an
+// on-demand route to the prerendered `/404`, which Astro refuses — every
+// unknown URL was a 500.)
+export const prerender = true;
 
-if (!page) {
-  return Astro.rewrite('/404');
+export async function getStaticPaths() {
+  const { entries, error } = await getEmDashCollection('pages');
+  // Fail the build rather than ship a site with no pages.
+  if (error) throw error;
+  return entries
+    // `home` is served by index.astro at `/`.
+    .filter((entry) => entry.id !== 'home')
+    .map((entry) => ({ params: { slug: entry.id }, props: { page: entry } }));
 }
 
+const { page } = Astro.props;
 // `page.data` is typed `unknown` until `.emdash/types.ts` is generated from a
 // running site (`pnpm dev`, then `emdash types`), so a fresh scaffold would fail
 // `astro check`; the cast keeps it passing both before and after, where the

package/templates/emdash/src/pages/api/track.ts

@@ -0,0 +1,158 @@
+/**
+ * The site's one on-demand endpoint: contact-form posts (the `vitops.form` block) and the
+ * conversion beacons (`<Tracking />`, `tel:`/`mailto:` clicks) all arrive here.
+ *
+ * Every public page is prerendered (see AGENTS.md, "Rendering and freshness"); this route sets
+ * `prerender = false` because it has to run on each request. It is the one exception, and the
+ * Cloudflare adapter handles it in the Worker beside the EmDash admin.
+ *
+ * Credentials are functions of the request, read from the Worker's bindings and never from
+ * `site.json`:
+ *   VITOPS_TURNSTILE_SECRET            created by `vitops setup turnstile`
+ *   EMAIL                              the `send_email` binding in wrangler.jsonc
+ *   VITOPS_HUBSPOT_ACCESS_TOKEN        or VITOPS_ZOHO_* / VITOPS_JOBBER_*, when `site.crm` is set
+ *
+ * Where a submission goes: `site.notifications.email` (or the primary location's email) and,
+ * when `site.crm` is set, the CRM. The email is the durability floor: a failed CRM write never
+ * fails the request and is stated in the email. With neither configured the post is refused,
+ * because accepting a message nobody receives is worse than an error page.
+ */
+import { env } from 'cloudflare:workers';
+import {
+  createConversionRoute,
+  toNotifyContext,
+  type RateLimitStore,
+} from '@getvitops/astro/routes';
+import type { APIRoute } from 'astro';
+import config from '../../../site.json' with { type: 'json' };
+
+export const prerender = false;
+
+type Site = Parameters<typeof toNotifyContext>[0];
+const site = config as unknown as Site;
+
+/**
+ * Challenge every form post that carries no token when a Turnstile key exists. `false` keeps a
+ * no-JavaScript visitor able to submit, at the price that a bot can simply omit the token and be
+ * held only by the honeypot, origin and rate checks. A form that gets spam should keep this true.
+ */
+const TURNSTILE_REQUIRED = true;
+
+const bindings: Record<string, unknown> = env;
+const secret = (name: string): string | undefined => {
+  const v = bindings[name];
+  return typeof v === 'string' && v ? v : undefined;
+};
+
+/**
+ * One store for the life of the isolate. `createConversionRoute` builds its default store per
+ * call, and this handler builds a route per request (the redirect depends on the form's page),
+ * so the default would never see a second hit. Per-isolate only; a fleet-wide limit needs a KV
+ * or Durable Object store behind the same one-method interface.
+ */
+const hits = new Map<string, number>();
+const rateLimitStore: RateLimitStore = {
+  hit(id, at) {
+    const prev = hits.get(id);
+    hits.set(id, at);
+    if (hits.size > 5000) for (const [k, t] of hits) if (at - t > 60_000) hits.delete(k);
+    return prev === undefined ? null : at - prev;
+  },
+};
+
+/** A same-site path or nothing: `_next` comes from the request, so it must never be an open redirect. */
+function safeNext(input: unknown): string | null {
+  const v = typeof input === 'string' ? input : '';
+  if (!v.startsWith('/') || v.startsWith('//') || v.includes('\\') || v.length > 200) return null;
+  return /[\u0000-\u001f\u007f#?]/.test(v) ? null : v;
+}
+
+function crmCredentials() {
+  const crm = site.site.crm;
+  if (!crm) return undefined;
+  switch (crm.provider) {
+    case 'hubspot': {
+      const accessToken = secret('VITOPS_HUBSPOT_ACCESS_TOKEN');
+      return accessToken ? { provider: 'hubspot' as const, hubspot: { accessToken } } : undefined;
+    }
+    case 'bigin': {
+      const clientId = secret('VITOPS_ZOHO_CLIENT_ID');
+      const clientSecret = secret('VITOPS_ZOHO_CLIENT_SECRET');
+      const refreshToken = secret('VITOPS_ZOHO_REFRESH_TOKEN');
+      return clientId && clientSecret && refreshToken
+        ? { provider: 'bigin' as const, bigin: { clientId, clientSecret, refreshToken } }
+        : undefined;
+    }
+    case 'jobber': {
+      const clientId = secret('VITOPS_JOBBER_CLIENT_ID');
+      const clientSecret = secret('VITOPS_JOBBER_CLIENT_SECRET');
+      const refreshToken = secret('VITOPS_JOBBER_REFRESH_TOKEN');
+      return clientId && clientSecret && refreshToken
+        ? { provider: 'jobber' as const, jobber: { clientId, clientSecret, refreshToken } }
+        : undefined;
+    }
+  }
+}
+
+export const POST: APIRoute = async ({ request, locals }) => {
+  const context = toNotifyContext(site);
+  const isForm = /multipart\/form-data|application\/x-www-form-urlencoded/.test(
+    request.headers.get('content-type') ?? '',
+  );
+
+  // Where a no-JS visitor lands: the page the form was on, with the fragment that reveals the
+  // right notice. A JSON/beacon caller gets a JSON response and never reaches these.
+  let next: string | null = null;
+  if (isForm) {
+    try {
+      next = safeNext((await request.clone().formData()).get('_next'));
+    } catch {
+      // A body that will not parse is the route's own 400; the redirect falls back to the root.
+    }
+  }
+  const page = next ?? '/';
+  const sent = `${page}?sent=1#form-sent`;
+  const failed = `${page}?error=1#form-error`;
+
+  // Nothing to deliver to: refuse rather than accept and lose the message.
+  if (
+    isForm &&
+    !context.notifications?.email &&
+    !context.locationEmails?.length &&
+    !site.site.crm
+  ) {
+    console.error(
+      '[vitops] form post refused: set site.notifications.email (or a location email, or site.crm) in site.json',
+    );
+    return Response.redirect(new URL(failed, request.url), 303);
+  }
+
+  // A site key means the page renders the widget, so a missing secret would mean a check that
+  // nothing enforces. Fail closed.
+  const siteKey = site.site.security?.turnstile?.siteKey;
+  const turnstileSecret = secret('VITOPS_TURNSTILE_SECRET');
+  if (isForm && siteKey && !turnstileSecret) {
+    console.error(
+      '[vitops] form post refused: site.security.turnstile.siteKey is set but the VITOPS_TURNSTILE_SECRET Worker secret is not (run `vitops setup turnstile`)',
+    );
+    return Response.redirect(new URL(failed, request.url), 303);
+  }
+
+  const handle = createConversionRoute({
+    context,
+    binding: () => bindings['EMAIL'] as never,
+    ...(site.site.crm
+      ? { crm: { config: site.site.crm, credentials: () => crmCredentials() } }
+      : {}),
+    ...(siteKey && turnstileSecret
+      ? { turnstile: { secretKey: turnstileSecret, required: TURNSTILE_REQUIRED } }
+      : {}),
+    // The request's own origin: a cross-site form post carries a different `Origin` and is
+    // refused. Set `site.domains.canonical` and this follows it instead.
+    ...(context.canonical ? {} : { allowedOrigin: new URL(request.url).origin }),
+    rateLimit: { store: rateLimitStore },
+    redirectTo: sent,
+    errorRedirectTo: failed,
+  });
+  return handle({ request, locals });
+};

package/templates/emdash/src/pages/index.astro

@@ -3,16 +3,17 @@ import { getEmDashEntry } from 'emdash';
 import { PortableText } from 'emdash/ui';
 import Layout from '../layouts/Layout.astro';
 
-// The seeded home page (seed/seed.json → pages/home). Edit it in the admin;
-// the Vitops blocks from @getvitops/emdash render automatically — EmDash
-// merges the plugin's block components into <PortableText>.
+// Prerendered, like every page in this template: written to static HTML at build
+// time from the `home` entry (seed/seed.json → pages/home). Edit it in the admin;
+// a publish triggers a rebuild that bakes the change in (AGENTS.md "Rendering and
+// freshness"). The Vitops blocks from @getvitops/emdash render automatically —
+// EmDash merges the plugin's block components into <PortableText>.
 //
-// Deliberately NOT prerendered, unlike AGENTS.md's general "prerender by
-// default" rule: this is the one route where the tradeoff that rule names
-// (prerendered = fast, but reflects the database as of the last build) is
-// unacceptable — the whole point of editing in EmDash is that a publish
-// shows up without a redeploy. Add `getStaticPaths()` + `prerender = true`
-// here only if this site's home page genuinely doesn't need that.
+// Anything on a page that must be fresh per request (a stock count, a signed-in
+// greeting) goes in a server island — `<Thing server:defer />` — which stays out
+// of this static HTML and loads after it.
+export const prerender = true;
+
 const { entry: page } = await getEmDashEntry('pages', 'home');
 
 // `page.data` is typed `unknown` until `.emdash/types.ts` is generated from a

package/templates/static/.agents/skills/setup/SKILL.md

@@ -7,14 +7,14 @@ description: Work the client-onboarding checklist (SETUP.html) autonomously —
 
 `SETUP.html` is the canonical checklist — this skill adds only sequencing,
 gates, and where to stop. It does not restate the steps; read `SETUP.html`
-(or `npx vitops setup --help`) for what each stage actually does and why.
+(or `vp exec vitops setup --help`) for what each stage actually does and why.
 
 ## Steps
 
 1. **Preview the whole sequence first.**
 
    ```bash
-   npx vitops setup all --dry
+   vp exec vitops setup all --dry
    ```
 
    Read the plan before doing anything. It names every step it would take and
@@ -24,10 +24,10 @@ gates, and where to stop. It does not restate the steps; read `SETUP.html`
 2. **Run it.**
 
    ```bash
-   npx vitops setup all
+   vp exec vitops setup all
    ```
 
-   Re-run `npx vitops setup --check` after each leg rather than retrying on
+   Re-run `vp exec vitops setup --check` after each leg rather than retrying on
    your own judgment — a step already done resolves to a no-op skip, so a
    second run is safe, and `--check` tells you exactly what still needs doing
    instead of you guessing from output.

package/templates/static/AGENTS.md

@@ -14,7 +14,7 @@ as Cloudflare Workers static assets (no server runtime, no database).
   portrait, landscape; SVG + PNG) for layout work before real imagery
   exists. Delete the directory once real assets land.
 - Prefer framework CSS classes (utilities, patterns, type roles like
-  `font-heading`) over bespoke CSS. Run `npx vitops agents` to append the
+  `font-heading`) over bespoke CSS. Run `vp exec vitops agents` to append the
   full generated class-vocabulary reference to this file.
 - **Layout foundations — these are the answer, not a starting point.** Six
   substitutions carry the structure of nearly every page:
@@ -47,18 +47,72 @@ as Cloudflare Workers static assets (no server runtime, no database).
   PR with auto-merge; merging deploys prod. Only run it when the user
   explicitly asks to promote/ship to production.
 
+## Labels: badge and tag
+
+Two label patterns, both enabled in `site.json`'s `patterns.items`: **`badge`** is a
+static label (a status, count or category) and **`tag`** is a label that may be
+static _or_ dynamic (editable, dismissable, in a `tag-list`). Don't invent a third
+name — `chip` and `pill` are not part of this vocabulary. The button pattern's class
+is `btn` (`<a class="btn">` is styled, not just a bare `<button>`).
+
+## Content Security Policy
+
+`public/_headers` ships a **`Content-Security-Policy-Report-Only`** header for every
+page (they are all static assets): violations are logged to the browser console and
+nothing is blocked, so it can't break a page. Its `script-src` is `'self'` plus the
+SHA-256 of each inline script `<Head />` emits (the colour-scheme bootstrap and the
+consent-gate stub), with no `'unsafe-inline'`. `contentSecurityPolicy()` and
+`inlineScriptHashes()` from `@getvitops/astro` produce the same strings.
+
+Before enforcing it (rename the header to `Content-Security-Policy`), browse the pages
+with the console open: add the origins of any third-party tag the consent gate
+activates to `script-src` / `connect-src`, any embed to `frame-src`, and hash any
+inline script you add yourself. Hashes rather than nonces because a static page has no
+per-request response to carry one.
+
 ## Commands
 
-- `pnpm dev` — local dev
-- `pnpm typecheck` — `astro check`
-- `pnpm run build:css` — regenerate the framework CSS from `site.json`
-- `pnpm deploy` — build + `wrangler deploy` to prod
-- `pnpm run deploy:dev` — build + deploy the isolated dev worker
-- `pnpm run init:github` — one-time: create + push the GitHub repo (main +
-  dev, dev default, branch protection + environment policy). Only run when
-  the user asks to set up GitHub.
-- `pnpm run init:hosting` — one-time: read the Cloudflare account id and set
-  it as a repo secret. Only run when the user asks for it.
-- `npx vitops validate site.json` — schema-check the site config
-- `npx vitops lint -i site.json -f css` — find framework classes in
-  source that resolve to nothing under this format
+This is a **Vite+** project: use `vp` (and its `vpr` shorthand), not `pnpm`/`npm`/`npx`.
+The package manager underneath is pnpm, but `vp` picks it up for you.
+
+| To…                                      | Run                                                  |
+| ---------------------------------------- | ---------------------------------------------------- |
+| install dependencies                     | `vp install`                                         |
+| add / remove / update a package          | `vp add <pkg>` · `vp remove <pkg>` · `vp update`     |
+| run a `package.json` script              | `vpr <script>` (alias for `vp run <script>`)         |
+| run a locally installed binary           | `vp exec <bin>` (e.g. `vp exec vitops docs classes`) |
+| run a one-off package without installing | `vp dlx <pkg>`                                       |
+| format + lint + typecheck (files)        | `vp check`                                           |
+| typecheck Astro (`.astro` files)         | `vpr typecheck`                                      |
+
+**Scripts that wrap Astro must go through `vpr`.** `vp dev` / `vp build` run Vite
+directly and skip Astro, so use `vpr dev`, `vpr build`, `vpr preview`.
+
+**`vpr dev` returns immediately.** `astro dev` now starts the server in the
+background. Check it with `vp exec astro dev status`, read its output with
+`vp exec astro dev logs --follow`, and stop it with `vp exec astro dev stop`; the
+site is at <http://localhost:4321>. Don't wait on it as if it were a foreground
+process.
+
+| Script                                    | What it does                                                                                                                        |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `vpr dev`                                 | local dev                                                                                                                           |
+| `vpr build:css`                           | regenerate the framework CSS from `site.json`                                                                                       |
+| `vpr deploy`                              | build + `wrangler deploy` to prod                                                                                                   |
+| `vpr deploy:dev`                          | build + deploy the isolated dev worker                                                                                              |
+| `vpr init:github`                         | one-time: create + push the GitHub repo (main + dev, dev default, branch protection + environment policy). Only when the user asks. |
+| `vpr init:hosting`                        | one-time: read the Cloudflare account id and set it as a repo secret. Only when the user asks.                                      |
+| `vp exec vitops validate site.json`       | schema-check the site config                                                                                                        |
+| `vp exec vitops lint -i site.json -f css` | find framework classes in source that resolve to nothing under this format                                                          |
+
+**Release flow.** A site is not a published package, so there is no changeset or
+version bump: ship by committing to `dev` (auto-deploys the dev worker) and then
+running the **promote** workflow. `vp` has no `vp change` / `vp pm change` command
+(checked against vp 1.5.0); for a _package_ it does have `vp pm version`,
+`vp pm publish` and `vp pm stage`.
+
+**Naming the project.** `vp create` takes the package name from the target
+directory and invents a random slug when none is given, so pass one:
+`vp create @getvitops:static --directory <client-slug>`. `wrangler.jsonc`'s `name`
+is separate and still says what the template shipped — rename it to match before
+the first deploy.