saasaloy 0.5.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasaloy",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Composable SaaS accelerator kit.",
   "keywords": [
     "saas",

package/schemas/registry-item.schema.json

@@ -117,9 +117,39 @@
         "type": "string"
       }
     },
+    "envServices": {
+      "type": "object",
+      "description": "Which services read each of this module's `envVars` — a service being a workspace that reads a `.env` (`api`, `web`, `admin`), or `deploy`, the Cloudflare credentials `pnpm deploy:production` loads with no file. `default` covers every key the module declares; a key named alongside it overrides that list for itself. `saasaloy add` groups the key list in `packages/env/.env.example` under a `# @services` line per distinct set. Omit it and the `PUBLIC_` prefix rule decides instead, with a warning naming the module: a prefixed key goes to every client service, everything else to the api.",
+      "properties": {
+        "default": {
+          "type": "array",
+          "uniqueItems": true,
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "enum": ["api", "web", "admin", "deploy"]
+          }
+        }
+      },
+      "propertyNames": {
+        "pattern": "^(default|[A-Z][A-Z0-9_]*)$"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "uniqueItems": true,
+        "minItems": 1,
+        "items": { "type": "string", "enum": ["api", "web", "admin", "deploy"] }
+      }
+    },
+    "envOptional": {
+      "type": "array",
+      "description": "Keys from `envVars` that may stay empty. `saasaloy add` writes a `# Blank on purpose` line above each one in `packages/env/.env.example`, which is what stops `pnpm env:setup` failing on a key the capability's schema gives a default or marks optional. Every name here must also appear in `envVars`.",
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" }
+    },
     "devVars": {
       "type": "object",
-      "description": "Local-development values for a subset of `envVars`: NAME → the value `saasaloy add` pre-fills into the generated `apps/api/.dev.vars.example`. Only for a value that is the same on every machine and is not a secret (a loopback URL, a fixed port). Every key here must also appear in `envVars`; a key absent here is written with an empty value for the owner to fill in.",
+      "description": "Local-development values for a subset of `envVars`: NAME → the value `saasaloy add` pre-fills into the generated `packages/env/.env.example`. Only for a value that is the same on every machine and is not a secret (a loopback URL, a fixed port). Every key here must also appear in `envVars`; a key absent here is written with an empty value for the owner to fill in.",
       "propertyNames": {
         "pattern": "^[A-Z][A-Z0-9_]*$"
       },

package/templates/base/AGENTS.md

@@ -10,9 +10,6 @@ This is a **pnpm workspace monorepo** managed by **Turborepo**.
 - **Root**: Configuration files, shared tooling
 - **`apps/*`**: Applications (Next.js, Astro apps - currently empty, will be added)
 - **`packages/*`**: Shared packages
-- **`infra`**: Centralized Cloudflare deployment (Pulumi), if the `infra` capability is installed —
-  a root-level workspace, not nested under `apps/*` or `packages/*` (it's neither an app nor a
-  shared package)
 
 ### Dev Port Map
 
@@ -25,7 +22,7 @@ drifting port turns into an unexplained CORS rejection.
 | `apps/web` (Astro) | 3000 | `http://localhost:3000` | `apps/web/astro.config.mjs` (`server.port`) |
 | `apps/admin` (TanStack Start) | 3001 | `http://localhost:3001` | `apps/admin/vite.config.ts` (`server.port`, `strictPort`) |
 | `apps/api` (Hono on Workers) | 4000 | `http://localhost:4000` | `apps/api/wrangler.jsonc` (`dev.port`) |
-| Postgres (local, `database-postgres`) | 5432 | `postgres://postgres:postgres@127.0.0.1:5432/app` | `DATABASE_URL` in `.env` |
+| Postgres (local, `database-postgres`) | 5432 | `postgres://postgres:postgres@127.0.0.1:5432/app` | `DATABASE_URL` in `packages/env/.env.example` |
 
 The `apps/admin` and `apps/api` rows apply once you run `saasaloy add admin` or
 `saasaloy add api`.
@@ -36,8 +33,9 @@ Rules for a new app or service:
   from 4000. Add a row to this table in the same change.
 - **Set `strictPort` (or the framework's equivalent).** A busy port must fail loudly. A
   silent `+1` moves the app to an origin nothing allows.
-- **Name the origin, don't infer it.** A browser-side caller reads `PUBLIC_API_URL` and
-  falls back to `http://localhost:4000`; a server-side caller reads its own env var.
+- **Name the origin, don't infer it.** A browser-side caller reads `PUBLIC_API_URL`
+  through `webEnv()` or `adminEnv()`, with no fallback — an unset key fails the build
+  naming the key. A server-side caller reads its own key through `apiEnv(c.env)`.
 - **Update both allow-lists when you add a browser origin**: `DEV_ORIGINS` in
   `apps/api/src/index.ts` and `DEV_ORIGINS` in `packages/auth/src/auth.ts`.
 
@@ -90,16 +88,70 @@ without one is silently skipped by `turbo run clean` and leaves stale build outp
   and expecting it to mount: nothing globs that folder, and the entry file's `AppType` is
   what the typed `hc` client reads.
 
-### The `@repo/ui` Design Layer
+### The `@repo/env` Environment Layer
+
+`packages/env` owns every environment value this project reads. One tracked key list, one
+command that distributes it, one typed gate in front of the capabilities.
+
+- **`packages/env/.env.example` is the key list**, and it is the only example file. It is
+  tracked, and `saasaloy add` regenerates it from the installed modules' own descriptions.
+  A value you type in it survives that, and nothing is ever removed.
+- **`packages/env/.env` holds the values**, and it is gitignored. `saasaloy env` prompts
+  for each unset key and writes it.
+- **`pnpm env:setup` writes every service's own `.env`** from those two files. A *service*
+  is a workspace that reads a `.env` — `api`, `web`, `admin` — and
+  `packages/env/src/services.ts` is the table. The `deploy` row has no file: it holds the
+  Cloudflare credentials a deploy loads in memory.
+- **`pnpm deploy:production` deploys every Worker.** It checks every service's production
+  values first, then runs `turbo run deploy`, where each deployable workspace runs
+  `env-deploy <service>`: build with the production values in the environment, then
+  `wrangler deploy --secrets-file`. The `local` source reads production values from the
+  gitignored `packages/env/.env.prod`. Nothing writes a production value under `apps/`.
+- **`createEnv` is the gate.** `apiEnv(c.env)` on the server, `webEnv()` in a frontend.
+  It validates on the first call and throws once naming every failing key, its module and
+  what the key is for.
+- **A `client` key must start with `PUBLIC_`**, and the type system enforces it. Client
+  code reading a server key throws by name.
+- **There is no `.dev.vars`.** Every runtime here reads `.env`. A leftover `.dev.vars`
+  hides `.env` from wrangler without warning, so `saasaloy doctor` reports one and
+  `pnpm env:setup` carries its values across and deletes it.
+- **Never read `process.env`** in a file a Worker imports. Node tooling reads it freely.
+
+The `saasaloy-env` skill is the runbook: adding a key, the section rule, the server/client
+split, blank-on-purpose keys, and the offline rule.
 
-`packages/ui` owns the design layer: the Tailwind 4 theme (`src/styles/globals.css`),
-the `cn()` helper, the vendored [shadcn](https://ui.shadcn.com) primitives in
-`src/components/`, the marketing **blocks** in `src/blocks/`, the store-bound
-**containers** in `src/containers/`, and the landing page's copy in `src/content/`.
-`apps/web` pulls the theme in once, through the shared layout that imports
-`@repo/ui/globals.css`.
+### The `@repo/ui` Design Layer
 
-`DESIGN.md` at the repository root records the token values and the rules behind them. Read it before you add or change UI.
+`packages/ui` owns the design layer: the Tailwind 4 theme in `src/styles/`, the `cn()`
+helper, the vendored [shadcn](https://ui.shadcn.com) primitives in `src/components/`, the
+marketing **blocks** in `src/blocks/`, the store-bound **containers** in
+`src/containers/`, and the landing page's copy in `src/content/`.
+
+Those layer folders are the whole top level of `src/`: `assets` (images, SVGs and icons, added when the first one arrives), `blocks`, `components`, `containers`, `content`, `lib` and `styles`. Do not add an app folder such as `src/admin/` or `src/web/` beside them. When one app needs its own files inside a layer, give that layer a child folder (`blocks/admin/`, `components/shared/`).
+
+The theme is one shared file plus one theme file per app:
+
+- **`src/styles/globals.css`** is the shared layer: the Tailwind imports, the `@source`
+  globs and the base layer. It holds no token values, and no app imports it directly.
+- **`src/styles/web.css`** is the web app's theme: the `dark` custom variant, its `:root`
+  and `.dark` token values, its `@theme inline` colour mapping and its radius scale. It
+  imports `globals.css`, and `apps/web` pulls it in once, through the shared layout that
+  imports `@repo/ui/styles/web.css`. `components.json` points here, so a shadcn preset
+  lands here. The landing page's layout, type and motion utilities sit at the end of the
+  file, after the colour tokens, and a preset leaves them alone.
+- **`src/styles/admin.css`** is the admin app's theme, in the same shape, written by
+  `saasaloy add admin`.
+
+Each theme file repeats the `dark` variant and the `@theme inline` mapping on purpose.
+shadcn merges a preset in place only when the target file itself holds them, and it does
+not look through an `@import`. Move either one into `globals.css` and a preset appends a
+duplicate to `web.css` instead.
+
+**Each app has its own `DESIGN.md`, in its own folder.** `apps/web/DESIGN.md` records the
+web tokens in `web.css` and the rules behind them, and fingerprints `web.css`. An app
+that carries its own theme file gets its own `apps/<app>/DESIGN.md`, which fingerprints
+that file. There is no `DESIGN.md` at the repository root. Read the document for the app
+you are changing before you add or change UI.
 
 Primitives, blocks and containers are reached by subpath — none is re-exported from the
 package root, so importing one never drags in the rest. The root export is project-wide
@@ -152,7 +204,7 @@ pnpm --filter @repo/ui exec shadcn add dialog
   imports and a blanket glob charges every app for every primitive. A primitive the
   landing page or `src/blocks/` renders gets an `@source "../components/<name>.tsx";` line
   in `globals.css`; a primitive only one app renders gets its `@source` line in that app's
-  own stylesheet, the way `apps/admin/src/styles/admin.css` takes the whole directory.
+  own theme file, the way `src/styles/admin.css` takes the whole directory.
   Nothing errors when you skip this — the classes just never reach the CSS.
 - `style` is `base-nova` (Base UI) and is fixed at init — the CLI cannot change it later.
 - `rsc` is `false`, so the CLI strips the `"use client"` directive for you. It means
@@ -160,8 +212,10 @@ pnpm --filter @repo/ui exec shadcn add dialog
 
 Primitives are source you own. Edit them in place rather than wrapping them.
 
+**No UI kit or component library as a dependency.** When a design comes from a kit (Tailark, coss ui, a licensed dashboard kit), copy or rebuild the component into `src/components/` or `src/blocks/` as source this project owns. Do not install the kit's package, and keep no link to its repository for later updates. A copied component changes by hand, like any other file here. The shadcn CLI above is the one sanctioned way to fetch a primitive, because it writes source and leaves no runtime dependency behind.
+
 **Swapping the whole theme for a preset.** The token set in
-`packages/ui/src/styles/globals.css` is shadcn's `neutral` with `cssVariables: true`, and
+`packages/ui/src/styles/web.css` is shadcn's `neutral` with `cssVariables: true`, and
 any shadcn **`registry:style`** item is a drop-in replacement for it. The same
 `--filter … exec` form applies — there is no separate theme command:
 
@@ -170,10 +224,11 @@ pnpm --filter @repo/ui exec shadcn add https://tweakcn.com/r/themes/modern-minim
 ```
 
 The CLI merges the preset's `:root`, `.dark` and `@theme inline` blocks **into** the
-existing ones, so the file's hand-written parts — the `@source` rules, the
-`@custom-variant dark`, the `@layer base` rules — stay put, and `components.json` is not
-touched. It usually *extends* `@theme inline` with mappings the base does not carry
-(fonts, tracking, shadows); that is expected.
+existing ones in `web.css` and keeps its `@custom-variant dark`, so the hand-written
+parts in `globals.css` — the `@source` rules and the `@layer base` rules — stay put, and
+`components.json` is not touched. The preset reaches the web app only; the admin theme
+in `admin.css` keeps its own values. It usually *extends* `@theme inline` with mappings
+the base does not carry (fonts, tracking, shadows); that is expected.
 
 Two places to get an item from:
 
@@ -185,19 +240,78 @@ Two places to get an item from:
 Neither is special: the mechanism is the `registry:style` shape, so any URL that serves
 one works.
 
-**This edits a base file, and base files have no update path.** Saasaloy hands you the
-template once; it never comes back to migrate it. A swapped theme is yours to maintain,
-including re-applying anything you had customised in `globals.css` that the preset
-overwrote. Diff the file after running the command rather than assuming.
-
-A preset swap invalidates `DESIGN.md`, which records the token values the old theme had. The `saasaloy-design` skill's `theme` flow runs the command above for you and re-derives the contract from the merged result, so prefer it over running the command by hand. Pick one or the other — running both applies the preset twice.
-
-Light/dark/system switching is unaffected by any of this — it keys off the `.dark` class,
-which every preset keeps.
-
-**Blocks — the page-level compositions.** `src/blocks/` holds the marketing blocks the
-landing page is built from: `navbar`, `hero`, `feature-grid`, `pricing-table`, `faq`,
-`cta`, `footer`. The rules are not stylistic — each one prevents a real failure:
+**This edits a file the project owns.** `web.css` is an owned base file: `saasaloy
+update` never overwrites it, and a later template change to it reaches you only through
+the merge plan. A swapped theme is yours to maintain, including re-applying anything you
+had customised in `web.css` that the preset overwrote. Diff the file after running the
+command rather than assuming.
+
+A preset swap invalidates `apps/web/DESIGN.md`, which records the token values the old theme had. The `saasaloy-design` skill's `theme` flow runs the command above for you and re-derives the contract from the merged result, so prefer it over running the command by hand. Pick one or the other — running both applies the preset twice.
+
+Theme switching is unaffected by any of this. It keys off the `.dark` class, which every preset keeps. The toggle has two states, light and dark: `system` is only the starting state for a visitor who never pressed it, and no press steps back to `system`. Do not give the toggle a third state or a light/dark/system menu.
+
+**A project made before the theme split.** Older projects kept the web tokens in
+`globals.css` and the design document at the repository root. `saasaloy update` creates
+`packages/ui/src/styles/web.css` and lists `globals.css` and `Layout.astro` in the merge
+plan, because the project owns both; it never moves your tokens for you. Finish the split
+by hand, in this order:
+
+1. Move the `@custom-variant dark` line, the `:root` block, the `.dark` block and the
+   `@theme inline` block from `globals.css` into `web.css`, replacing the template's
+   copies there, below its `@import "./globals.css";`. Keep your own values, not the
+   template's.
+2. Add `"./styles/*": "./src/styles/*"` to the `exports` of `packages/ui/package.json`,
+   if the update did not.
+3. In `apps/web/src/layouts/Layout.astro`, import `@repo/ui/styles/web.css` in place of
+   `@repo/ui/globals.css`.
+4. Set `tailwind.css` in `packages/ui/components.json` to `src/styles/web.css`, if the
+   update did not.
+5. Move `DESIGN.md` to `apps/web/DESIGN.md`, and run the `saasaloy-design` skill's
+   `update` flow so its fingerprint names `web.css`.
+6. Run `pnpm build` and check that `globals.css` and `web.css` hold one `@theme inline`
+   and one `@custom-variant dark` between them.
+
+With the admin app installed, `saasaloy update` also moves its theme: it creates
+`packages/ui/src/styles/admin.css` and deletes `apps/admin/src/styles/admin.css`, or
+keeps it with a warning when you edited it. Carry any edit across to the new file, then
+delete the old one. The new admin app imports `@repo/ui/styles/admin.css`, so its build
+fails until step 2 adds the `./styles/*` export. Update the base and finish step 2 before
+you build admin, and before you run `saasaloy add admin` on a project made before the
+split.
+
+**Blocks — the page-level compositions.** `src/blocks/` holds the thirteen marketing
+blocks the landing page is built from: `navbar`, `hero`, `logo-cloud`, `pain-points`,
+`how-it-works`, `feature-grid`, `showcase`, `audience`, `testimonials`, `pricing-table`,
+`faq`, `cta` and `footer`. `logo-cloud`, `pain-points`, `how-it-works`, `showcase`,
+`audience` and `testimonials` are new; a project scaffolded before them gets the files
+through `saasaloy update`, and adds each to its own `index.astro` by hand, since the page
+is the owner's. The blocks need the landing utilities at the end of `web.css`. `web.css`
+is an owned file, so `update` lists it in the merge plan and never adds them for you.
+Copy the template's block, from the comment that opens "The landing page's layout" to
+the `stylelint-enable` line, to the end of your `web.css`. A project made before the
+theme split skips this: `update` creates its `web.css` from the template, block included.
+
+**The section recipe.** `index.astro` composes the page from explicit imports, one line
+per section. To remove a section, delete its line and its import, delete its file in
+`src/blocks/`, and blank its navbar and footer labels in `landing.ts`. To reorder, move
+the lines. Every block uses the same container (`section-container`, `-narrow`, `-wide`)
+and spacing (`section-y`) utilities from `src/styles/web.css`, so any order keeps one
+rhythm. A block sets no width, no section padding and no keyframes of its own; motion
+comes from the named utilities there (`blur-in`, `beam-in`, `reveal`, `marquee`,
+`shine-text`, `nav-float`, `hover-lift`), and every one stops under reduced motion.
+
+**The logo recipe.** `landing.logos.items[]` is `{ id, name, mark }`. `mark` is a key in
+`LOGO_MARKS` at the top of `blocks/logo-cloud.tsx`. Paste a customer's SVG there under a
+kebab-case key with `fill="currentColor"`, then name the key in content. An unknown key
+renders `name` as a text wordmark.
+
+**The production bar.** The page holds to a rubric: no axe violation at WCAG 2.1 AA in
+either theme, no sideways scroll from 360px up, nothing animating under reduced motion, a
+skip link to `<main>` on every page, link-preview metadata on `/`, and exactly two islands
+(`Navbar`, `PricingTable`). Keep each true when you change a block: a new section with
+state is a third island and needs a reason.
+
+The rules below are not stylistic — each one prevents a real failure:
 
 - **One block, one file, one component export (plus its prop types).**
   `pricing-table.tsx` exports `PricingTable` alongside `PricingTier` and
@@ -222,13 +336,13 @@ landing page is built from: `navbar`, `hero`, `feature-grid`, `pricing-table`, `
   `client:load` on the page hydrates everything and throws away the reason this is a
   static site — see `apps/web/src/pages/index.astro` for the worked example.
 - **`theme-toggle` is the exception that proves the rule.** It sits in `src/blocks/`
-  beside the marketing blocks but is chrome, not copy: `index.astro` places it as a
-  sibling of `<Navbar />` and it takes **no** client directive despite being
-  interactive. It has no `onClick` and no state — the pre-paint inline script the shared
-  layout emits (`THEME_INIT_SCRIPT`, from `packages/ui/src/lib/theme.ts`) drives every
+  beside the marketing blocks but is chrome, not copy: `navbar.tsx` renders it inside the
+  bar, and it needs **no** client directive of its own despite being interactive. It has
+  no `onClick` and no state — the pre-paint inline script the shared layout emits
+  (`THEME_INIT_SCRIPT`, from `packages/ui/src/lib/theme.ts`) drives every
   `[data-theme-toggle]` on the page through one delegated listener, and CSS picks the
   icon off `<html data-theme>`. Move it, restyle it via its `className`, or delete the
-  one line in `index.astro` to drop it. Do **not** "fix" it by adding `client:*` or an
+  one line in `navbar.tsx` to drop it. Do **not** "fix" it by adding `client:*` or an
   `onClick`, and do not paste a second copy of the boot script into a page: any document
   that renders the block must inline that one constant in its `<head>`, or the control
   stays hidden.
@@ -259,6 +373,8 @@ landing page is built from: `navbar`, `hero`, `feature-grid`, `pricing-table`, `
   React file under `apps/web/src/components/` builds the client and passes the function
   down. Astro serializes island props, so the page renders **that** file, never the block
   directly.
+- **A link that leaves the site opens a new tab.** Spread `externalLinkProps(href)` from `@repo/ui/lib/external-link` onto the anchor and render `newTabHint(href)` inside it. The href decides: an absolute URL gets `target="_blank"`, `rel="noopener noreferrer"` and a screen-reader hint, and a path or a same-page anchor stays in the tab. Do not write `target="_blank"` by hand.
+- **A value that waits on a request shows a skeleton.** Render the `Skeleton` primitive at the size the value will take until the response arrives, never a blank gap or a spinner. Add it with `pnpm --filter @repo/ui exec shadcn add skeleton` the first time a block needs it.
 - **A block never imports a store either.** Local state is fine; shared state is not. See
   the containers section below.
 - **A module's UI arrives here too, and you wire it up by hand.** `saasaloy add <module>`
@@ -328,20 +444,27 @@ record and nothing else. Follow them when you add a block or a key:
    messages (`ui.pricing.perMonth`, `ui.pricing.perMonthAnnual`) — word order does not
    survive the seam in every language.
 5. **Only user-visible strings move.** Section `id`s and the same-page anchors pointing at
-   them are structure and stay in the block. Three things break the rule, all because a
+   them are structure and stay in the block. A few things break the rule, all because a
    thing rewritten *with* the copy belongs *near* the copy: the whole `tiers` array (prices
-   and `ctaHref`s included); each feature's `icon`, held as a registry *name* like `"zap"`
-   and resolved to a component by the map at the top of `blocks/feature-grid.tsx`; and the
-   two outbound calls to action, `landing.navbar.ctaHref` and
-   `landing.cta.primaryActionHref`/`.secondaryActionHref`, which leave the page and so
-   cannot break a section link. A translation layer reads `id`, `icon` and every `*Href` as
-   non-message data.
+   and `ctaHref`s included); every `icon`, held as a registry *name* like `"zap"` and
+   resolved to a component by `packages/ui/src/lib/icons.ts`, and every logo `mark`,
+   resolved by `blocks/logo-cloud.tsx`; every outbound link (`*Href`), which leaves the
+   page and so cannot break a section link; and the code the page quotes (terminal
+   commands, module names, file paths). A translation layer reads `id`, `icon`, `mark`,
+   every `*Href` and the quoted code as non-message data. A pair of backticks inside a
+   message renders as `<code>` through `inlineCode()` from `@repo/ui/lib/inline-code`.
+
+**No copy that goes stale.** Do not write a version number, a release date or a count into a message. Say something general and link to where the current value lives: the hero pill says "See what's new" and links to the changelog, so it stays true across every release.
 
 Two consequences worth knowing. Blanking a navbar or footer link's label in content drops
 that link, which is how a removed section loses its nav entry without editing a block. And
 the theme toggle's labels deliberately stay in `packages/ui/src/lib/theme.ts`: that file is
 inlined verbatim into a pre-paint `<script>` and is import-free on purpose.
 
+**The default copy is Saasaloy's own.** A fresh project's page describes Saasaloy, and
+`siteName` in `packages/ui/src/index.ts` defaults to `"Saasaloy"`, so the brand and the
+words agree until you replace both. The two skills below replace them in one pass.
+
 **Making this project yours.** Three skills ship with the base (linked at
 `.claude/skills/`, real files in `.agents/skills/`). The first two run in order:
 
@@ -356,12 +479,12 @@ inlined verbatim into a pre-paint `<script>` and is import-free on purpose.
 
 The third has no place in that order, because it runs whenever the UI moves:
 
-3. **`saasaloy-design`** keeps `DESIGN.md` true. Its `theme` flow swaps the preset and
-   re-derives the contract; `update` re-derives after you change `globals.css` or add
-   components; `audit` reports where the code and the contract disagree. It reads the
+3. **`saasaloy-design`** keeps `apps/web/DESIGN.md` true. Its `theme` flow swaps the
+   preset and re-derives the contract; `update` re-derives after you change `web.css` or
+   add components; `audit` reports where the code and the contract disagree. It reads the
    product brief when one exists and never writes it.
 
-Invoke them rather than editing eight blocks by hand — and if you do edit by hand, keep the
+Invoke them rather than editing thirteen blocks by hand — and if you do edit by hand, keep the
 strings in the content module so the next pass finds them.
 
 ### Naming Conventions
@@ -418,13 +541,15 @@ hook (which is also how you keep hooks out of CI).
 - Run type checking: `pnpm typecheck` (must pass before commits)
 - Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes)
 - Check formatting: `pnpm format:check`, or `pnpm format` to rewrite
-- There is no `pnpm test` at the root, and no workspace declares a `test` script. The base ships no test runner: pick one and add it per workspace when you have something to test.
+- Run the tests: `pnpm test`. It runs `turbo run test` (each workspace's own `test` script), then `vitest run` from the root, whose `vitest.config.ts` treats every workspace under `apps/*` and `packages/*` as a project. Write new tests for Vitest: put a `*.test.ts` file beside the code, and give the workspace a `vitest.config.ts` only when it needs setup of its own. Do not add a per-workspace `test` script that calls Vitest, or the file runs twice. `packages/env` is the exception: its tests run on `node --test` through its own `test` script, and the root config leaves it out.
+- Before you hand over UI work, run `pnpm dev`, load the pages you changed, and read the dev server's terminal output. Fix every error and warning it prints. A clean build does not prove a clean dev server.
 
 ## Boundaries
 
 ### ✅ Always Do
 
-- Read `DESIGN.md` before writing or changing UI
+- Read the app's `DESIGN.md` (`apps/web/DESIGN.md` for the web app) before writing or
+  changing UI
 - Run `pnpm typecheck` before committing code changes
 - Run `pnpm lint` and fix all errors
 - Give every new app or package a `clean` script backed by `rimraf` (see above)
@@ -434,6 +559,7 @@ hook (which is also how you keep hooks out of CI).
 ### ⚠️ Ask First
 
 - Adding new dependencies (especially to root `package.json`)
+- Building new UI before the owner has approved a mockup. Show screenshots of the mockup first and get approval. A change after approval gets a new mockup, not a fix after the work lands
 - Modifying Turborepo configuration (`turbo.json`)
 - Changing TypeScript strictness settings
 - Modifying the husky hooks (`.husky/`), `lint-staged.config.js`, or `commitlint.config.js`
@@ -447,11 +573,12 @@ hook (which is also how you keep hooks out of CI).
 
 - Never use `npm` or `npx`, instead use `pnpm` & `pnpm dlx`
 - Never use `rm -rf` in a package script — it breaks on Windows; use `rimraf`
-- Commit secrets, API keys, or environment variables
+- Commit secrets or API keys. `packages/env/.env` is gitignored; `packages/env/.env.example`
+  is tracked and holds local defaults only
 - Modify `node_modules/` or `pnpm-lock.yaml` manually (use `pnpm install`)
 - Remove or disable TypeScript strict mode
 - Remove or disable the lint-staged or commitlint hooks, or commit with `--no-verify`
   as a habit rather than an emergency
 - Use `any` type without explicit `@ts-expect-error` or `@ts-ignore` with justification
-- Break the workspace structure (don't move packages outside `apps/*`, `packages/*`, or `infra`)
+- Break the workspace structure (don't move packages outside `apps/*` or `packages/*`)
 - Commit without running type checks and linting

package/templates/base/README.md

@@ -30,7 +30,7 @@ saasaloy list               # what the registry offers, and what you already hav
 
 ## UI components
 
-`DESIGN.md` records the project's design tokens and UI rules for people and agents.
+`apps/web/DESIGN.md` records the web app's design tokens and UI rules for people and agents.
 
 `packages/ui` ships a Tailwind 4 theme, a small set of [shadcn](https://ui.shadcn.com)
 primitives, and the marketing blocks the landing page is built from. Import primitives and
@@ -54,14 +54,26 @@ Components land in `packages/ui/src/components/` as source you own and can edit.
 
 ## Landing page
 
-`apps/web/src/pages/index.astro` composes the blocks in `packages/ui/src/blocks/` —
-`navbar`, `hero`, `feature-grid`, `pricing-table`, `faq`, `cta`, `footer`. Each is one
-self-contained `.tsx` with its copy as in-file defaults, so editing the file is how you
-change the page.
+`apps/web/src/pages/index.astro` composes thirteen blocks from `packages/ui/src/blocks/`: `navbar`, `hero`, `logo-cloud`, `pain-points`, `how-it-works`, `feature-grid`, `showcase`, `audience`, `testimonials`, `pricing-table`, `faq`, `cta` and `footer`. The page ships describing Saasaloy itself, so it reads as a finished product on day one. You make it yours with two edits and no others:
 
-Blocks render to static HTML by default. Only the three that need browser state carry a
-client directive (`Navbar` is `client:idle`; `PricingTable` and `Faq` are
-`client:visible`) — the rest ship no JavaScript at all. Don't reach for `client:load`.
+1. **Rewrite the words** in `packages/ui/src/content/landing.ts`: every heading, link, price and icon name. The `saasaloy-landing-copy` skill drafts it from your product brief. The brand is `siteName` in `packages/ui/src/index.ts`, which `saasaloy-setup` sets.
+2. **Choose the sections** in `index.astro`. Each section is one import and one line.
+
+### The section recipe
+
+- **Remove a section:** delete its line and its import in `index.astro`, then delete its file in `packages/ui/src/blocks/`. Blank its navbar and footer labels in `landing.ts` so no link points at a section that is gone.
+- **Reorder:** move the lines. Every block uses the same container and spacing utilities, so any order keeps one rhythm.
+- **Bring one back:** copy the block file in from a fresh `saasaloy init`, then add the import and the line.
+
+### The logo recipe
+
+The logo row names each logo in `landing.logos.items` as `{ id, name, mark }`. `mark` is a key in the `LOGO_MARKS` registry at the top of `packages/ui/src/blocks/logo-cloud.tsx`. To add a customer's logo, paste its SVG into that registry under a kebab-case key with `fill="currentColor"`, then put the key in the item's `mark`. A key the registry doesn't know renders the item's `name` as a text wordmark, which is what the default row does.
+
+### What the page promises
+
+Blocks render to static HTML by default. Only two carry a client directive: `Navbar` (`client:idle`) and `PricingTable` (`client:visible`). The FAQ and the pain points open with native `<details>`, all motion is CSS and stops under reduced motion, and the footer adds one inline script that writes the current year. Don't reach for `client:load`.
+
+The page is checked against a written rubric: no axe violation at WCAG 2.1 AA in either theme, no sideways scroll from 360px up, a skip link on every page, and link-preview metadata on `/`. Keep those true when you change a block.
 
 The page composes itself from explicit imports, and nothing discovers a file behind your
 back. A module that ships UI writes its block into `packages/ui/src/blocks/` like every

package/templates/base/_agents/skills/saasaloy-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: saasaloy-design
-description: Keep DESIGN.md true of the Saasaloy design layer. Use theme to choose and apply a registry style, update after packages/ui changes, or audit the design contract for token drift.
+description: Keep apps/web/DESIGN.md true of the Saasaloy design layer. Use theme to choose and apply a registry style, update after packages/ui changes, or audit the design contract for token drift.
 derived-from: "designkit (MIT), narrowed 2026-08-09"
 ---
 
@@ -8,7 +8,9 @@ derived-from: "designkit (MIT), narrowed 2026-08-09"
 
 This skill records the design system that the project already uses. It writes no components and no pages. Use `uikit` for that work.
 
-The token home is `packages/ui/src/styles/globals.css`. The design contract is `DESIGN.md` at the project root.
+The token home is `packages/ui/src/styles/web.css`. The design contract is `apps/web/DESIGN.md`. `web.css` imports `packages/ui/src/styles/globals.css`, which holds the shared Tailwind setup and no token values.
+
+This skill covers the web app only. Another app's theme file, such as the admin module's `packages/ui/src/styles/admin.css`, is out of scope. Do not read its tokens into this contract, and do not edit it.
 
 The grounding rule controls every mode. Every token value must exist in the project code or in the Tailwind utility that the project uses. Do not choose a nearby value because it looks cleaner.
 
@@ -24,15 +26,15 @@ If the user does not name a mode, ask which mode to use. Do not choose between a
 
 | Mode | Files |
 |------|-------|
-| `theme` | `packages/ui/src/styles/globals.css`, `DESIGN.md`, and `docs/product-brief.md` only when the brief is absent |
-| `update` | `DESIGN.md` only |
+| `theme` | `packages/ui/src/styles/web.css`, `apps/web/DESIGN.md`, and `docs/product-brief.md` only when the brief is absent |
+| `update` | `apps/web/DESIGN.md` only |
 | `audit` | none |
 
 Do not edit `components.json` during a theme change. Do not add a dependency, script, component, page, or Tailwind class.
 
 ## Shared rules
 
-Read `DESIGN.md`, `packages/ui/src/styles/globals.css`, and all files under `packages/ui/src/` before you derive tokens. Read the application files that use `@repo/ui` when you need to confirm usage.
+Read `apps/web/DESIGN.md`, `packages/ui/src/styles/web.css`, `packages/ui/src/styles/globals.css`, and all files under `packages/ui/src/` before you derive tokens. Read the application files that use `@repo/ui` when you need to confirm usage.
 
 Find the system in this order. Stop at the first match.
 
@@ -50,6 +52,15 @@ Write elevation as prose under `## Elevation & Depth`. Never add `elevation` to
 
 Write motion as prose under `## Motion`. The alpha schema has no motion token group and no component transition token.
 
+The landing page's layout, type and motion vocabulary lives at the end of `web.css`, after the colour tokens, and `DESIGN.md` must name all of it:
+
+- The type ramp in `@theme`: `--text-display`, `--text-section-title` and `--text-lead`. Record the largest size of each fluid `clamp()` step as the token's `fontSize`, and describe the fluid range in the Typography prose.
+- The container widths in `@theme` (`--container-page`, `--container-narrow`, `--container-wide`) and the `section-container*` and `section-y` utilities. Describe them under `## Layout`. Spacing stays omitted, because these are named widths and one section rhythm, not a spacing scale.
+- The motion utilities: `blur-in`, `beam-in`, `reveal`, `marquee`, `shine-text`, `nav-float` and `hover-lift`. Describe each under `## Motion`, and say that each one stops under reduced motion.
+- The decoration utility `grid-pattern`. Describe it under `## Components` with the landing blocks it decorates.
+
+A theme preset replaces the colour tokens and leaves this vocabulary alone. After a `theme` run, check that the vocabulary survived and that `DESIGN.md` still describes it.
+
 Use only these component token keys: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, and `width`.
 
 Keep the sections in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts, Motion, Dark Mode.
@@ -58,24 +69,24 @@ The seed is a one-time base file. ADR 0022 means Saasaloy has no update path for
 
 ## Fingerprint
 
-The fingerprint covers only `packages/ui/src/styles/globals.css`. It does not cover components, blocks, or other files.
+The fingerprint covers only `packages/ui/src/styles/web.css`. It does not cover `globals.css`, components, blocks, or other files.
 
 Compute the fingerprint from the file bytes. Use the first 12 lowercase hexadecimal characters of SHA-256.
 
 ```sh
-node --input-type=module -e "import { createHash } from 'node:crypto'; import { readFileSync } from 'node:fs'; process.stdout.write(createHash('sha256').update(readFileSync('packages/ui/src/styles/globals.css')).digest('hex').slice(0, 12))"
+node --input-type=module -e "import { createHash } from 'node:crypto'; import { readFileSync } from 'node:fs'; process.stdout.write(createHash('sha256').update(readFileSync('packages/ui/src/styles/web.css')).digest('hex').slice(0, 12))"
 ```
 
 The scaffold seed ends with this stamp.
 
 ```markdown
-_Seeded from the saasaloy base template · CLI <version> · tokens sha256:<12 hex> of packages/ui/src/styles/globals.css_
+_Seeded from the saasaloy base template · CLI <version> · tokens sha256:<12 hex> of packages/ui/src/styles/web.css_
 ```
 
 After `theme` or `update`, replace the seed stamp with this stamp.
 
 ```markdown
-_Updated from packages/ui on YYYY-MM-DD · tokens sha256:<12 hex> of packages/ui/src/styles/globals.css_
+_Updated from packages/ui on YYYY-MM-DD · tokens sha256:<12 hex> of packages/ui/src/styles/web.css_
 ```
 
 Do not change the fingerprint during `audit`.
@@ -85,7 +96,7 @@ Do not change the fingerprint during `audit`.
 Run the official linter after each write.
 
 ```sh
-pnpm dlx @google/design.md lint DESIGN.md
+pnpm dlx @google/design.md lint apps/web/DESIGN.md
 ```
 
 The format is alpha. Read the current schema when a lint finding conflicts with this skill.
@@ -126,13 +137,13 @@ Use the package-local executable from the project root.
 pnpm --filter @repo/ui exec shadcn add <registry-style-url>
 ```
 
-Confirm that the `@source` rules, `@custom-variant dark`, and `@layer base` remain in `globals.css`. Confirm that `components.json` did not change.
+`components.json` points shadcn at `web.css`, so the preset merges into the `:root`, `.dark` and `@theme inline` blocks there. Confirm that `globals.css` did not change and still holds the `@source` rules and `@layer base`. Confirm that `web.css` and `globals.css` hold one `@theme inline` and one `@custom-variant dark` between them. Confirm that `components.json` did not change.
 
 Stop and report the failure when the preset removes a required rule or changes `components.json`. Do not repair an unknown preset merge without approval.
 
 ### 4. Re-derive the contract
 
-Run the shared extraction process against the merged `globals.css` and its usage. Update the token front matter and only the prose sections that the new tokens affect.
+Run the shared extraction process against the merged `web.css` and its usage. Update the token front matter and only the prose sections that the new tokens affect.
 
 Use the product brief to update Overview and Do's and Don'ts. Do not add product claims that the brief does not support.
 
@@ -168,7 +179,7 @@ Audit is read-only. Do not edit or format any file.
 
 ### 1. Check the fingerprint offline
 
-Read the recorded 12-character fingerprint from the final stamp. Compute the current fingerprint from `globals.css`.
+Read the recorded 12-character fingerprint from the final stamp. Compute the current fingerprint from `web.css`.
 
 - `current` means the two fingerprints match.
 - `stale` means they differ.
@@ -182,7 +193,7 @@ Use `orphaned` for a documented token with no current source. Use `uncovered` fo
 
 ### 3. Lint when possible
 
-Run `pnpm dlx @google/design.md lint DESIGN.md` when the tool and network are available. If it cannot run, state that the fingerprint check ran offline and structural lint did not run.
+Run `pnpm dlx @google/design.md lint apps/web/DESIGN.md` when the tool and network are available. If it cannot run, state that the fingerprint check ran offline and structural lint did not run.
 
 ### 4. Report
 
@@ -192,7 +203,7 @@ Open with the file count that the audit scanned. Give one verdict for the finger
 
 - Never write a component or a page. Use `uikit` for that work.
 - Never add a token value that the project does not contain.
-- Never change `globals.css` in `update` or `audit`.
+- Never change `globals.css` in any mode, or `web.css` in `update` or `audit`.
 - Never write during `audit`.
 - Never claim that lint passed when the linter did not run.
 - Never treat a matching fingerprint as proof that component usage has no drift.