saasaloy 0.5.2 → 0.6.1

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, and apps/admin/DESIGN.md when the admin app is installed, true of the Saasaloy design layer. Use theme to choose and apply a registry style to the web app, update after packages/ui changes, or audit a design contract for token drift.
 derived-from: "designkit (MIT), narrowed 2026-08-09"
 ---
 
@@ -8,7 +8,16 @@ 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.
+Each app has its own token home and its own contract:
+
+| App | Token home | Contract |
+|-----|------------|----------|
+| web | `packages/ui/src/styles/web.css` | `apps/web/DESIGN.md` |
+| admin, when installed | `packages/ui/src/styles/admin.css` | `apps/admin/DESIGN.md` |
+
+Both theme files import `packages/ui/src/styles/globals.css`, which holds the shared Tailwind setup and no token values. Ask which app when the user does not say, and work on one contract at a time. Never read one app's tokens into the other app's contract.
+
+The admin contract also covers the admin primitive set in `packages/ui/src/components/admin/`, its blocks in `packages/ui/src/blocks/admin/` and its containers in `packages/ui/src/containers/admin/`. The web contract covers the base `components/`, the other `blocks/` and the web app.
 
 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 +33,17 @@ 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` | web only: `packages/ui/src/styles/web.css`, `apps/web/DESIGN.md`, and `docs/product-brief.md` only when the brief is absent |
+| `update` | the chosen app's `DESIGN.md` only |
 | `audit` | none |
 
+`theme` never runs for the admin app. A preset targets `web.css` through `components.json`, and nothing writes to `admin.css` but a person. When the user asks to restyle the admin app, say so, and offer `update` after they edit `admin.css`.
+
 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 the chosen app's `DESIGN.md` and theme file, `packages/ui/src/styles/globals.css`, and the files under `packages/ui/src/` that the app renders 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,42 +61,52 @@ 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.
 
-The seed is a one-time base file. ADR 0022 means Saasaloy has no update path for it. The fingerprint detects drift, and this skill repairs the contract.
+The web contract is a one-time base seed. ADR 0022 means Saasaloy has no update path for it. The admin contract is an admin module file, so `saasaloy update` lists an edited copy in its merge plan. In both cases the fingerprint detects drift, and this skill repairs the contract.
 
 ## Fingerprint
 
-The fingerprint covers only `packages/ui/src/styles/globals.css`. It does not cover components, blocks, or other files.
+The fingerprint covers only the chosen app's theme file: `packages/ui/src/styles/web.css` for the web contract, `packages/ui/src/styles/admin.css` for the admin contract. It does not cover `globals.css`, components, blocks, or other files. The commands and stamps below name `web.css`; substitute `admin.css` for the admin contract.
 
 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`.
 
 ## Official linter
 
-Run the official linter after each write.
+Run the official linter after each write, on the contract you wrote.
 
 ```sh
-pnpm dlx @google/design.md lint DESIGN.md
+pnpm dlx @google/design.md lint apps/web/DESIGN.md
+pnpm dlx @google/design.md lint apps/admin/DESIGN.md
 ```
 
 The format is alpha. Read the current schema when a lint finding conflicts with this skill.
@@ -126,13 +147,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 +189,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 the chosen app's theme file, `web.css` or `admin.css`.
 
 - `current` means the two fingerprints match.
 - `stale` means they differ.
@@ -182,7 +203,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/<app>/DESIGN.md` for the chosen app 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 +213,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.

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

@@ -0,0 +1,130 @@
+---
+name: saasaloy-env
+description: Runbook for the env capability in packages/env — the one tracked key list, the pnpm env:setup distribution command, the pnpm deploy:production deploy with env-deploy, and the typed createEnv gate each service reads its values through. Use when deploying to Cloudflare, when a deploy stops naming a blank production key, adding an environment key, when a build or a request fails naming an unset key, when choosing which services read a key, when a value must stay blank, when a key is checkout-owned, when picking a value source, or when a leftover .dev.vars is hiding .env from wrangler.
+---
+
+# env — one key list, one command, one typed gate
+
+`packages/env` (`@repo/env`) owns both halves of this project's environment story.
+
+The **node half** is a tracked key list (`packages/env/.env.example`), a gitignored value file (`packages/env/.env`), and `pnpm env:setup`, which writes every service's own `.env` from the two. The **runtime half** is `createEnv`, which validates the values a service actually got and hands back typed ones.
+
+A *service* is a workspace that reads a `.env`: `api`, `web`, `admin`. The name is the workspace directory. `packages/env/src/services.ts` holds the table, and `saasaloy add api` appends a row to it. One row has no workspace and no file: `deploy` holds `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`, which a deploy loads in memory.
+
+## Adding a key, in two steps
+
+**1. Add its line to `packages/env/.env.example`**, under the `# @services` section naming every service that reads it. Write a comment above it saying where the value comes from and what unset looks like. Put the local development default on the line.
+
+```
+# @services api
+
+# Sender address every outbound message uses. The domain must be one the selected
+# provider may send from. Unset, the first send throws naming this key.
+EMAIL_FROM=dev@localhost
+```
+
+A key with no `# @services` line above it fails `pnpm env:setup`. That is deliberate: a key that reaches no service is a key the Worker throws on, and failing here is the cheaper place to find out.
+
+**2. Declare it in the preset** of the package that reads it, so `createEnv` validates it and the type reaches the calling code.
+
+```ts
+// packages/email/src/env-preset.ts
+export const emailPreset = definePreset({
+  module: "@repo/email",
+  extends: [],
+  server: {
+    EMAIL_FROM: z.string().min(1).describe("Sender address every message uses."),
+  },
+});
+```
+
+The `.describe()` text is what the aggregate error prints, so write it for the person reading a failed deploy.
+
+## Reading a key
+
+On the server, pass the Worker's `env`:
+
+```ts
+import { apiEnv } from "@api/env";
+
+app.get("/x", (c) => {
+  const { EMAIL_FROM } = apiEnv(c.env);
+});
+```
+
+In a frontend, call it with nothing — the values are inlined at build time:
+
+```ts
+import { webEnv } from "@web/env";
+
+const base = webEnv().PUBLIC_API_URL;
+```
+
+`createEnv` validates on the **first call per `env` object** and memoizes the result in a `WeakMap`. A Worker cannot see its `env` at module scope, so the first request is the earliest honest point to check. One throw then names every failing key at once, with the module that declared it and that module's own wording, so a deploy with three unset keys takes one round trip to fix.
+
+## Server, client, shared
+
+- `server` — read only where `isServer` is true. A Worker, a build script.
+- `client` — inlined into a public bundle. **Must** start with `PUBLIC_`, and the type system says so: a mis-prefixed key does not compile.
+- `shared` — read on both sides.
+
+`apps/web/src/env.ts` and `apps/admin/src/env.ts` set `isServer: false`, which arms a Proxy: reading a server key from client code throws by name. `typeof window === "undefined"` is not used, because it is true in a Worker *and* in a browser bundle before hydration.
+
+The `runtimeEnvStrict` map in those files is hand-written, one literal `import.meta.env.PUBLIC_X` per key. Vite inlines a literal member expression and nothing else, so a spread, a loop or a computed key compiles to `undefined` in the built bundle and fails only in production. **Add the line by hand when you add a client key.**
+
+## Blank on purpose
+
+`pnpm env:setup` fails on a key the list carries with no value. When a key is meant to stay empty, say so in its comment block:
+
+```
+# Blank on purpose: unset means no proxy origin, and a link is root-relative.
+STORAGE_PROXY_URL=
+```
+
+## Checkout-owned keys
+
+`CHECKOUT_OWNED_KEYS` in `packages/env/src/services.ts` lists keys this checkout sets for itself. A key named there keeps whatever value is already on disk, whoever wrote it, so a per-branch `DATABASE_URL` survives every `pnpm env:setup`. `packages/env` never learns what a database is — only that some key is the checkout's to set.
+
+## Value sources
+
+`pnpm env:setup` reads its values from a source, selected by `ENV_SOURCE`:
+
+- **`local`** (the default, always installed) reads the gitignored `packages/env/.env`. `saasaloy env` prompts for each unset key and writes that file, so a project develops with no vendor account and no network.
+- **`infisical`** arrives with `saasaloy add env-infisical`.
+
+A source that does not answer at all — no CLI, no network — is treated as offline: `env:setup` keeps every service file that is already complete and warns, and fails writing nothing when one is incomplete. A refusal the source *answered* with, such as no access, always fails.
+
+## Production and `--env prod`
+
+Each service row declares `dev` or `prod`. `pnpm env:setup --env prod` refuses to act without `--only <service>`, and refuses outright to write production values into a workspace under `apps/`. Two independent guards on the one command that can put a live credential on disk.
+
+`saasaloy env` prints the `wrangler secret put` lines for a deploy. It never runs them, and `pnpm deploy:production` makes them unnecessary.
+
+## Deploying: `pnpm deploy:production` and `env-deploy`
+
+`pnpm deploy:production` deploys every Worker in the project with wrangler. It runs in two steps:
+
+1. `node packages/env/src/deploy.ts --check` loads every service's `prod` values from the selected source and exits non-zero, naming each blank key, when one is missing. It also stops when `CLOUDFLARE_API_TOKEN` is blank and wrangler holds no `wrangler login` session. Nothing builds before this passes.
+2. `turbo run deploy` runs each workspace's `deploy` script, which is `env-deploy <service>`. A workspace whose package depends on `@repo/db` waits for `db:migrate:prod` first.
+
+`env-deploy <service>` loads that service's `prod` values and the `deploy` credentials, runs `pnpm run build` with them in the environment, and runs `wrangler deploy --secrets-file <file>`. Code and secrets land in one Worker version, so a Worker that throws at module scope on a missing secret deploys cleanly the first time. The secrets file is JSON, mode `0600`, under the OS temp directory, and deleted when the deploy ends, passed or failed. It holds the service's values minus every `CLOUDFLARE_*` key, minus each key the Worker's `wrangler.jsonc` already sets in `vars`, minus empty values. An assets-only Worker, one with no `main`, gets no secrets file.
+
+**Where the production values come from.** The `local` source reads the gitignored `packages/env/.env.prod`, never `packages/env/.env`, so a deploy cannot ship a `localhost` URL by accident. Copy the keys from `packages/env/.env.example` into it and set each one. `env-infisical` reads its `prod` environment. A variable the shell already exports wins over both, which is how CI passes values. The base `turbo.json` sets `passThroughEnv` on `deploy`, because turbo's strict env mode would drop the exported variables otherwise.
+
+**Why the dev `.env` stays out of the build.** Vite gives the environment priority over a `.env` file, but the Cloudflare adapters prerender inside workerd, and wrangler hands workerd the `.env` beside the workspace as its vars. So `env-deploy` builds with `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false`, and it sets a key the source leaves out to an empty string rather than leaving it unset. `apps/web/.env` keeps its dev values, and nothing writes a production value under `apps/`.
+
+Three more forms:
+
+- `pnpm --filter @repo/api run deploy` deploys one Worker. Pass wrangler flags after `--`: `pnpm --filter @repo/web run deploy -- --dry-run` builds with the production values and uploads nothing.
+- `env-deploy --run <service> -- <command> [args...]` runs one command with that service's `prod` values and the credentials. `database-d1`'s `db:migrate:prod` uses it.
+- `env-deploy --check` is step 1 on its own.
+
+Two things the flow does not do. `--secrets-file` only adds: a secret you removed from the value source stays on the Worker until you run `wrangler secret delete <KEY>` in its workspace. And a key marked `# Blank on purpose` passes the check even where production needs it, such as `BETTER_AUTH_SECRET`; the Worker's own `createEnv` gate is what refuses it.
+
+## `.dev.vars` is gone
+
+This project writes `.env` and nothing else. A leftover `.dev.vars` **hides** `.env` from wrangler — wrangler loads `.env` only while no `.dev.vars` sits beside it, and it does not warn — so `saasaloy doctor` reports one and `pnpm env:setup` carries its values across and deletes it.
+
+## `process.env`
+
+No file a Worker imports reads it. The Worker's `env` is the only source, and it arrives through `createEnv`. Node tooling — `scripts/`, `env-deploy`, a value source — reads it freely.

package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: saasaloy-landing-copy
-description: Write the scaffolded landing page's copy from docs/product-brief.md — as a markdown draft the owner reviews first, then into the content module. Use when the landing page still says "Acme" or "The SaaS you meant to build", when the owner asks to write, rewrite, improve or update the landing copy, headline, features, pricing or FAQ, and when re-running after the brief changed. Needs docs/product-brief.md; run saasaloy-setup first if there isn't one.
+description: Write the scaffolded landing page's copy from docs/product-brief.md — as a markdown draft the owner reviews first, then into the content module. Use when the landing page still describes Saasaloy ("Ship the SaaS, not the scaffolding"), when the owner asks to write, rewrite, improve or update the landing copy, headline, features, pricing or FAQ, and when re-running after the brief changed. Needs docs/product-brief.md; run saasaloy-setup first if there isn't one.
 ---
 
 # saasaloy-landing-copy — draft it in markdown, then write the page
@@ -41,12 +41,12 @@ says what to do when they disagree with the brief.
    an owner ends up answering the same thing twice and getting two different pages.
 2. **Read `packages/ui/src/content/landing.ts`.** You need the current copy to diff against,
    and its comments carry the shape rules you have to keep.
-3. **Read the icon registry** at the top of `packages/ui/src/blocks/feature-grid.tsx`.
+3. **Read the icon registry** in `packages/ui/src/lib/icons.ts`.
    Reading a block is fine; editing one is not. Its keys are the whole vocabulary available
    to `landing.features.items[].icon`, and they are the actual list rather than one copied
    into this file that went stale.
 4. **Check the two facts you do not own.** If `siteName` in `packages/ui/src/index.ts` is
-   still the scaffold's directory slug, or `lang` in `apps/web/src/layouts/Layout.astro` is
+   still the shipped `"Saasaloy"` or a directory slug, or `lang` in `apps/web/src/layouts/Layout.astro` is
    `en` while the brief names another language, say so now and carry both into the draft's
    **Not mine to fix** list. Writing Bangla copy into a page that declares itself English is
    a real defect, and one attribute long. Do not fix it yourself.
@@ -113,29 +113,29 @@ This file is deleted once the copy lands in `packages/ui/src/content/landing.ts`
 ## Hero
 | Key | Now | Proposed |
 |-----|-----|----------|
-| `hero.eyebrow` | Now in early access | In beta with two firms |
+| `hero.announcement` | See what's new | In beta with two firms |
 | `hero.primaryActionLabel` | Get started | Join the beta |
 
 `hero.title`:
-> ~~The SaaS you meant to build, already scaffolded.~~
+> ~~Ship the SaaS, not the scaffolding.~~
 > **Close the month without four spreadsheets per client.**
 
 *From the brief: the problem line, and "Excel plus a shared Dropbox folder" as the
-alternative. The eyebrow uses the two named beta firms rather than a stage name.*
+alternative. The announcement uses the two named beta firms rather than a stage name.*
 
 ## Features
 | # | Icon | Title | About |
 |---|------|-------|-------|
-| 1 | `list-checks` (was `zap`) | One close, one checklist | … |
+| 1 | `list-checks` (was `terminal`) | One close, one checklist | … |
 
 ## Where the buttons go
 | Key | Now | Proposed |
 |-----|-----|----------|
-| `navbar.ctaHref` | `#cta` | https://ledgerly.com.bd/waitlist |
-| `cta.primaryActionHref` | `/` | https://ledgerly.com.bd/waitlist |
+| `navbar.ctaHref` | Saasaloy's getting started guide | https://ledgerly.com.bd/waitlist |
+| `cta.primaryActionHref` | Saasaloy's getting started guide | https://ledgerly.com.bd/waitlist |
 
 ## Least sure about
-- The eyebrow names your two beta firms. Fine to say publicly?
+- The announcement names your two beta firms. Fine to say publicly?
 - FAQ 4 says data exports as CSV. The brief doesn't mention exports; I inferred it.
 
 ## Not mine to fix
@@ -170,57 +170,70 @@ than doubling it.
 
 | Key | What goes there |
 |-----|-----------------|
-| `meta.title` | Browser tab. `{siteName} — <what it does>`, under 60 characters. |
+| `meta.title` | Browser tab and link preview. `{siteName}: <what it does>`, under 60 characters. |
 | `meta.description` | Search result and link preview. One sentence, under 155 characters. |
-| `navbar.linkFeatures` `.linkPricing` `.linkFaq` | Nav labels. One or two words. They point at the sections of the same name — keep the meaning, or the anchor lies. |
+| `navbar.linkFeatures` `.linkHowItWorks` `.linkShowcase` `.linkPricing` `.linkFaq` | Nav labels. One or two words. They point at the sections of the same name — keep the meaning, or the anchor lies. An empty label hides the link. |
+| `navbar.secondaryLabel` `.secondaryHref` | The outline button beside the main one, usually docs, source or sign-in. Empty `secondaryHref` hides it. See [Destinations](#destinations). |
 | `navbar.ctaLabel` `.ctaHref` | Two or three words, a verb first, and where it goes. See [Destinations](#destinations). |
-| `hero.eyebrow` | The one-line status above the headline ("Now in early access"). Empty string hides it. |
+| `hero.announcement` `.announcementHref` | The pill above the headline ("Now in early access") and where it links, usually a changelog or launch post. Empty `announcement` hides it. |
 | `hero.title` | The headline. Under ten words, one idea, concrete. This is the sentence the whole page is judged on. |
 | `hero.description` | One or two sentences saying what it does for whom. |
-| `hero.primaryActionLabel` `.secondaryActionLabel` | Button labels, a verb first. Both scroll down the page; their hrefs are anchors and stay in the block. |
+| `hero.primaryActionLabel` `.primaryActionHref` `.secondaryActionLabel` `.secondaryActionHref` | Button labels, a verb first, and where each goes. See [Destinations](#destinations). |
+| `hero.terminalLabel` `.terminalTitle` `.terminalLines[]` `.treeTitle` `.tree[]` | The hero's product visual: a terminal and a file tree. For a product that is not a developer tool, keep the shipped lines and tell the owner in the draft to replace the visual with a screenshot (the block's header comment shows how). Command lines and paths are code, not prose. |
+| `logos.label` `.items[]` | One line beside the logo row, and `{ id, name, mark }` per logo. `name` is the accessible label; `mark` names an SVG the owner adds to `logo-cloud.tsx`, and an empty `mark` renders `name` as text. Never invent a customer: no logos in the brief means offer to drop the block. |
+| `painPoints.title` `.description` `.intro` `.items[]` | The problem the product solves. Four items by default: `{ id, icon, title, description }`, each a pain the brief's customer actually has. See [Icons](#icons). |
+| `howItWorks.title` `.description` `.steps[]` | Three ordered steps: `{ id, title, description }`. Only for a real sequence a customer follows. |
 | `features.title` `.description` | The section's heading and one supporting line. |
 | `features.items[]` | Six by default: `{ id, icon, title, description }`. Title 2–4 words; description one sentence about what the owner can *do*, not about the technology. See [Icons](#icons). |
+| `showcase.title` `.description` `.rows[]` | Alternating rows: `{ id, title, description, points[], visual, imageSrc, imageAlt }`. With real screenshots in `apps/web/public`, set `imageSrc` and a real `imageAlt`; otherwise keep `visual` and its lists, or offer to drop the block. |
+| `audience.title` `.description` `.items[]` | Who it is for. Four items: `{ id, icon, title, description }`, from the brief's customer section. |
+| `testimonials.title` `.description` `.items[]` | `{ id, quote, name, role }`. **Real quotes only**, with the person's permission. With none in the brief, keep the shipped placeholders and offer to drop the block. Never write a quote. |
 | `pricing.title` `.description` | Heading plus one line. |
 | `pricing.annualNote` `.currencySymbol` | See [Pricing](#pricing). |
-| `pricing.tiers[]` | `{ id, name, description, monthlyPrice, annualPrice, features, ctaLabel, ctaHref }`. Prices are whole units; `null` renders "Custom". Set `featured` on at most one. A tier's `ctaHref` stays `#cta` unless the brief gives that tier its own destination. |
+| `pricing.tiers[]` | `{ id, name, description, monthlyPrice, annualPrice, priceSuffix, features, ctaLabel, ctaHref }`, plus `featured` and `badge` on at most one. Prices are whole units; `null` renders "Custom". An empty `priceSuffix` shows "/month". |
 | `faq.items[]` | Five by default: `{ id, question, answer }`. Write the questions a buyer asks before paying — pricing, migration, lock-in, data, what happens when they outgrow it. One to three sentences, and answer the question. |
+| `faq.moreLabel` `.moreLinkLabel` `.moreLinkHref` | The line under the list. Empty `moreLinkHref` hides it. |
 | `cta.title` `.description` | The closing ask, plus one line removing a reason to hesitate. |
-| `cta.primaryActionHref` `.secondaryActionHref` | See [Destinations](#destinations). |
+| `cta.command` | A command shown as a code chip. Empty for a product that is not installed from a terminal. |
+| `cta.primaryActionLabel` `.primaryActionHref` `.secondaryActionLabel` `.secondaryActionHref` | See [Destinations](#destinations). |
 | `footer.tagline` | One line under the brand. |
-| `footer.groupProduct` `.groupLegal` `.link*` | Footer labels. One or two words each. |
+| `footer.links[]` `.linkTerms` `.linkPrivacy` | `{ id, label, href }` per outbound link, then the two legal labels. Empty drops a link. |
+| `footer.githubHref` `.xHref` | Social profiles. Empty hides the icon. |
+| `footer.copyright` | Keep `{year}` and `{siteName}` in it. |
 
 Three mechanical rules the code depends on:
 
-- **`{siteName}` is the only placeholder, and it works in exactly four strings**:
-  `meta.title`, `meta.description`, `hero.description`, `cta.description`. Anywhere else it
-  renders as the literal text `{siteName}`. Never a template literal — copy is data.
-- **Feature and FAQ `id`s are stable keys**, not positions. Rewriting a `title` under an
+- **`{siteName}` is the placeholder**, and the blocks fill it in titles, descriptions,
+  answers and tier names. Never a template literal — copy is data. `{year}` works only in
+  `footer.copyright`. A pair of backticks in a description or answer renders as `<code>`.
+- **Every list item's `id` is a stable key**, not a position. Rewriting a `title` under an
   existing id is free. Renaming an id is allowed but it is a new string to a translation
   layer, so do it only when the item genuinely became a different item.
-- **Deleting an item is fine**, in any of the three lists. Fewer than six features and fewer
-  than five questions both lay out correctly.
+- **Deleting an item is fine**, in any list. Fewer features, questions, steps or quotes all
+  lay out correctly.
 
 ### Icons
 
-Each feature carries an `icon` naming a glyph from the registry at the top of
-`packages/ui/src/blocks/feature-grid.tsx`. Rewrite what a feature is about and move its
-icon in the same edit — that is the whole reason the name lives in content. A page whose
-"practice all four modules" card renders a terminal prompt reads as machine-assembled,
-because it was.
+Feature, pain point and audience items carry an `icon` naming a glyph from the registry in
+`packages/ui/src/lib/icons.ts`. Rewrite what an item is about and move its icon in the same
+edit — that is the whole reason the name lives in content. A page whose "practice all four
+modules" card renders a terminal prompt reads as machine-assembled, because it was.
 
 - Use a key the registry actually has. Read the map; do not guess from memory. An unknown
   name silently renders the fallback sparkle, which looks like a choice and is not.
 - If nothing in the registry fits, say so in the draft and name the lucide icon you would
-  want. Widening the map is a two-line edit **the owner makes**, in a block, which is not
-  yours.
+  want. Widening the map is a two-line edit **the owner makes**, in a library file, which is
+  not yours.
 
 ### Destinations
 
-Three of the page's hrefs are content, and they are the ones that leave the page:
-`navbar.ctaHref`, `cta.primaryActionHref`, `cta.secondaryActionHref`. The brief's
-**Where "sign up" goes** section is where the answer lives.
+Every href that leaves the page is content: the navbar's two buttons, the hero's two
+actions and its announcement, the CTA's two actions, each tier's `ctaHref`, the FAQ's
+contact link and the footer's links and social profiles. The brief's **Where "sign up"
+goes** section is where the main answer lives.
 
-- **A URL in the brief.** Write it into `navbar.ctaHref` and `cta.primaryActionHref`.
+- **A URL in the brief.** Write it into `navbar.ctaHref`, `hero.primaryActionHref` and
+  `cta.primaryActionHref`.
 - **Nothing yet.** Leave them as shipped (`#cta` and `/`) and write labels the page can
   honestly satisfy — "See how it works" rather than "Start your free trial". Note it in the
   draft and in the brief's **Known gaps**. A primary button that reloads the page is the
@@ -229,8 +242,12 @@ Three of the page's hrefs are content, and they are the ones that leave the page
 - **`cta.secondaryActionHref`** is usually docs or an about page. `/` is honest for a
   one-page site; a label promising docs that do not exist is not.
 
-Everything else stays put. `#features`, `#pricing`, `#faq` and `#cta` are anchors matching
-section ids, they live in the blocks, and changing one breaks a link.
+- **The shipped values point at Saasaloy's own repo and docs.** Replace every one. An href
+  you cannot fill gets an empty string where the key allows it, which hides the link.
+
+Everything else stays put. `#features`, `#how-it-works`, `#showcase`, `#pricing` and
+`#faq` are anchors matching section ids, they live in the blocks, and changing one breaks a
+link.
 
 ### Pricing
 
@@ -324,22 +341,22 @@ sure about, and anything still on the **Not mine to fix** list.
 
 ### Dropping a block is its own confirmation
 
-When the brief yields nothing a block can honestly carry — no pricing, no proof for the FAQ
-— you may propose removing that block. **Separately.** Never bundled into the copy write,
+When the brief yields nothing a block can honestly carry — no pricing, no customer quotes,
+no customer logos, no screenshots for the showcase, no real sequence for how it works — you
+may propose removing that block. **Separately.** Never bundled into the copy write,
 never silent.
 
 It is three edits, and all three are allowed:
 
-1. Delete that block's line from `apps/web/src/pages/index.astro`.
+1. Delete that block's line and its import from `apps/web/src/pages/index.astro`. Tell
+   the owner they can delete the block file in `packages/ui/src/blocks/` too; that file is
+   not yours to delete.
 2. Blank the matching label in content (`landing.navbar.linkPricing = ""`,
    `landing.footer.linkPricing = ""`). A blank label drops the link, so the page keeps no
    nav entry pointing at a section that is gone.
-3. **Retarget or drop any hero action pointing at the removed section.** A blank label
-   does not save you here: the hero's `href` lives in the block, so it survives an empty
-   label and the button still points at nothing. The hero's secondary action ships as
-   `href: "#pricing"`, so when you remove the pricing block, pass `secondaryAction={null}`
-   to `<Hero>` in `index.astro` to drop the button, or pass a whole action pointing at a
-   section that still exists. Confirm which one with the owner along with the removal.
+3. **Retarget any action pointing at the removed section.** The hero's and the CTA's
+   hrefs are content, so check each one in `landing.ts` and point it somewhere that still
+   exists. Confirm the new target with the owner along with the removal.
 
 Removing a block is not redesigning one. You are editing lines in a page, not editing
 `packages/ui/src/blocks/`.
@@ -371,7 +388,7 @@ Copy on disk plus a brief means this has run before.
 - **Never edit a block.** `packages/ui/src/blocks/*.tsx` is off limits: no markup, no
   classes, no structure, no widening the icon registry. Read them freely. If copy will not
   fit a block, say so and let the owner decide.
-- **Never touch the design layer** — `packages/ui/src/styles/globals.css`,
+- **Never touch the design layer** — `packages/ui/src/styles/*`,
   `components.json`, `packages/ui/src/components/*`, or any Tailwind class anywhere.
 - **Never rewrite `ui.*`**, in any language. Translate it or leave it.
 - **Leave anchors alone.** `#features`, `#pricing`, `#faq`, `#cta` and a tier's default

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

@@ -262,7 +262,7 @@ can see:
 - **Never write landing copy.** Not into `packages/ui/src/content/landing.ts`, not into a
   block, not "just the headline while we're here". The brief is your output.
 - **Never edit a block or the design layer** — `packages/ui/src/blocks/*`,
-  `packages/ui/src/styles/globals.css`, `packages/ui/src/components/*`, `components.json`, or a Tailwind class
+  `packages/ui/src/styles/*`, `packages/ui/src/components/*`, `components.json`, or a Tailwind class
   anywhere.
 - **Never invent pricing, proof, a customer name, or a URL.** Not in the brief, and not in
   a sample answer.

package/templates/base/_gitignore

@@ -14,9 +14,6 @@ pnpm-debug.log*
 .env
 .env.*
 !.env.example
-.dev.vars
-.dev.vars.*
-!.dev.vars.example
 *.pem
 
 # OS / editor

package/templates/base/_saasaloy-base.json

@@ -1,18 +1,25 @@
 {
   "seedFiles": [
-    "DESIGN.md",
+    "apps/web/DESIGN.md",
     "README.md",
     "saasaloy.json",
     "apps/web/src/pages/index.astro",
     "packages/ui/src/content/landing.ts"
   ],
+  "retiredSeedFiles": ["DESIGN.md"],
   "ownedFiles": [
+    "packages/env/.env.example",
+    "packages/env/src/services.ts",
+    "packages/env/src/sources.ts",
+    "apps/web/src/env.ts",
     "packages/ui/src/styles/globals.css",
+    "packages/ui/src/styles/web.css",
     "packages/ui/src/blocks/**",
     "packages/ui/src/components/**",
     "packages/ui/src/containers/**",
     "packages/ui/src/content/**",
     "packages/ui/src/index.ts",
+    "packages/ui/src/lib/icons.ts",
     "apps/web/src/layouts/Layout.astro",
     "apps/web/public/favicon.*"
   ]