saasaloy 0.5.2 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasaloy",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "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,69 @@ 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/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.
+
 ### The `@repo/ui` Design Layer
 
-`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`.
+`packages/ui` owns the design layer: the Tailwind 4 theme in `src/styles/`, the `cn()` helper and the client-state stores in `src/lib/`, the vendored [shadcn](https://ui.shadcn.com) primitives in `src/components/`, the **blocks** in `src/blocks/`, the shells and layouts in `src/containers/`, and the 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.
 
-`DESIGN.md` at the repository root records the token values and the rules behind them. Read it before you add or change UI.
+**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.
+
+With the admin app installed, `apps/admin/DESIGN.md` records the admin tokens in `packages/ui/src/styles/admin.css` and fingerprints that file. A preset never targets `admin.css`; the admin theme changes by hand.
 
 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
@@ -109,28 +160,32 @@ constants only (`siteName`):
 import { siteName } from "@repo/ui";
 import { Button } from "@repo/ui/components/button";
 import { PricingTable } from "@repo/ui/blocks/pricing-table";
-import { CartSummary } from "@repo/ui/containers/cart-summary";
 import { landing, ui } from "@repo/ui/content/landing";
 import { cn } from "@repo/ui/lib/utils";
 ```
 
-**Three layers, split by state scope — not by "has state".**
+**The admin app has its own primitive set.** `saasaloy add admin` writes it into `src/components/admin/`, with its blocks in `src/blocks/admin/` and its shell and layouts in `src/containers/admin/`. Admin code imports only those, and a lint rule makes a base primitive under `apps/admin/**` an error, because both sets have a `button` and the wrong one renders with no complaint:
+
+```ts
+import { Button } from "@repo/ui/components/admin/button";
+import { DataTable } from "@repo/ui/blocks/admin/data-table";
+import { PageHeader } from "@repo/ui/blocks/admin/page-header";
+import { PageLayout } from "@repo/ui/containers/admin/page-layout";
+```
+
+The `saasaloy-admin` skill lists the whole set and how a page composes it.
+
+**Seven top-level folders, and no app folder at the root of `src/`.** A folder may hold `admin/`, `web/` or `shared/` children where one app owns the files, for example `src/blocks/admin/` or `src/containers/admin/`, which `saasaloy add admin` writes. A project without that app carries none of them.
 
-1. **`src/components/`** — vendored shadcn primitives. No stores, no copy.
-2. **`src/blocks/`** — compositions of primitives plus copy from the content module. Local
-   state is allowed (an open accordion, a ticking clock). Importing a shared store is
-   forbidden: a block takes its data as props and reports changes through callbacks, so
-   every app — the Astro site, a React SPA's panels — can drive the same block from its own
-   data source.
-3. **`src/containers/`** — compositions that bind a shared store or cross-island state. A
-   container subscribes, then wires data and callbacks into pure blocks. Containers are
-   thin, app-flavored wiring; the visual weight stays in the blocks.
+1. **`src/assets/`** holds images, SVGs and icons. The base ships no asset, so the folder does not exist until the first one lands, together with an `assets.d.ts` that types its imports.
+2. **`src/components/`** holds the vendored shadcn primitives, official and custom. No stores, no copy.
+3. **`src/blocks/`** holds compositions of primitives plus copy from the content module. Local state is allowed (an open accordion, a ticking clock). Importing a shared store is forbidden: a block takes its data as props and reports changes through callbacks, so every app can drive the same block from its own data source.
+4. **`src/containers/`** holds the shells and layouts that hold blocks and components on a page: an app shell, a page layout, a page frame. A container takes its data, its links and its callbacks as props. It imports no router and no session, so the app that owns them passes them in.
+5. **`src/content/`** holds copy, in one place for later translation.
+6. **`src/lib/`** holds utilities and the client-state stores.
+7. **`src/styles/`** holds the CSS files with the token variables.
 
-**One rule covers the whole package: no IO in `@repo/ui`.** No fetch, no persistence, no
-auth, in any of the three layers. Client-state stores (nanostores) live in `src/lib/` and
-are bound **only** in containers; the app that owns the data hydrates the store. When a
-store-shaped need shows up in a block, move the binding up to a container instead of
-importing the store in place.
+**One rule covers the whole package: no IO in `@repo/ui`.** No fetch, no persistence, no auth, no router, in any layer. Client-state stores (nanostores) live in `src/lib/`; the app that owns the data hydrates the store and passes what a block needs as props. When a store-shaped need shows up in a block, move the binding up into the app instead of importing the store in place.
 
 **Adding a primitive the base doesn't vendor.** `shadcn` is already an exact-pinned
 dependency of `@repo/ui`, so reach it with `--filter … exec` — that runs in the package
@@ -152,7 +207,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 +215,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 +227,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 +243,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 +339,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,8 +376,9 @@ 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 block never imports a store either.** Local state is fine; shared state is not. See
-  the containers section below.
+- **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. The app-side island reads the store and passes the values and the handlers down, the same pattern it uses for `onSubmit`.
 - **A module's UI arrives here too, and you wire it up by hand.** `saasaloy add <module>`
   writes a UI-bearing module's block into `src/blocks/` exactly like the base blocks, adds
   the app-side island that feeds it, and then stops: nothing globs a folder, and no command
@@ -271,25 +389,12 @@ landing page is built from: `navbar`, `hero`, `feature-grid`, `pricing-table`, `
 
 Blocks, like primitives, are source you own — they are meant to be edited, not wrapped.
 
-**Containers — the store bindings.** `src/containers/` holds the compositions that read
-shared state. The base ships none; the folder carries a note until you add your first.
-
-- **A container subscribes, a block renders.** The container reads the store, passes the
-  values down as props, and passes handlers that write back to the store. It adds no markup
-  a block could hold. If a container grows layout and copy, that part belongs in a block.
-- **The store lives in `src/lib/`, and only a container imports it.** A block that imports
-  a store is a block a second app cannot reuse, because the store now decides where its data
-  comes from. Move the binding up.
-- **Still no IO.** A container reads client state; it does not fetch, persist, or
-  authenticate. The app hydrates the store — the same app-side island pattern the blocks use
-  for `onSubmit`.
-- **Same file rules as blocks:** one container, one file, one component export, semantic
-  kebab-case filename, no barrel. Astro gives every `client:*` component its own React root,
-  so a container that a page hydrates must hold the whole composition.
-- **A container almost always needs a client directive.** It subscribes at runtime, so it
-  ships JavaScript by definition. Pick the cheapest one that works (`client:idle` above the
-  fold, `client:visible` below it), and keep the blocks it renders static in every page that
-  does not need the store.
+**Containers — the shells and the layouts.** `src/containers/` holds the compositions that place blocks and components on a page: an app shell, a page layout, a page frame. The base ships none; `saasaloy add admin` writes the admin app's into `src/containers/admin/`.
+
+- **A container places, a block renders.** It decides where the panels, the header and the detail view go, and it adds no copy a block could hold.
+- **No router, no session.** A container takes the nav data, the current area, a link component and the account as props. The app reads its router and its session and passes them in, so a container never depends on one app's routes.
+- **Still no IO.** A container does not fetch, persist, or authenticate.
+- **Same file rules as blocks:** one container per file, semantic kebab-case filename, no barrel.
 
 **The content module — where the words live.** `packages/ui/src/content/landing.ts` holds
 every user-visible string on the landing page, in two namespaces:
@@ -328,20 +433,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 +468,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, and `apps/admin/DESIGN.md` when the admin app is installed. 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 +530,14 @@ 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, `apps/admin/DESIGN.md` for the admin 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 +547,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 +561,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