saasaloy 0.5.2 → 0.6.0

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.*"
   ]

package/templates/base/{DESIGN.md → apps/web/DESIGN.md}

@@ -32,10 +32,16 @@ colors:
 typography:
   headline-display:
     fontFamily: "ui-sans-serif, system-ui, sans-serif"
-    fontSize: 3.75rem
+    fontSize: 4.5rem
+    fontWeight: 500
+    lineHeight: 1.05
+    letterSpacing: -0.035em
+  headline-section:
+    fontFamily: "ui-sans-serif, system-ui, sans-serif"
+    fontSize: 3rem
     fontWeight: 600
-    lineHeight: 1
-    letterSpacing: -0.025em
+    lineHeight: 1.1
+    letterSpacing: -0.03em
   headline-lg:
     fontFamily: "ui-sans-serif, system-ui, sans-serif"
     fontSize: 2.25rem
@@ -53,6 +59,11 @@ typography:
     fontSize: 1.125rem
     fontWeight: 400
     lineHeight: 1.75rem
+  lead:
+    fontFamily: "ui-sans-serif, system-ui, sans-serif"
+    fontSize: 1.125rem
+    fontWeight: 400
+    lineHeight: 1.75rem
   body-md:
     fontFamily: "ui-sans-serif, system-ui, sans-serif"
     fontSize: 1rem
@@ -93,7 +104,10 @@ components:
     typography: "{typography.headline-display}"
   section-title:
     textColor: "{colors.foreground}"
-    typography: "{typography.headline-lg}"
+    typography: "{typography.headline-section}"
+  section-lead:
+    textColor: "{colors.muted-foreground}"
+    typography: "{typography.lead}"
   legal-title:
     textColor: "{colors.foreground}"
     typography: "{typography.headline-md}"
@@ -162,25 +176,25 @@ The base uses a neutral, content-first system. It gives a new product a clear st
 
 ## Apps
 
-An app may carry its own token set in its own stylesheet on top of these tokens, importing `packages/ui/src/styles/globals.css` first and reassigning the semantic custom properties after it. The admin app does that, and its skill documents the values.
+This file covers the web app. Each app has its own theme file in `packages/ui/src/styles/` and its own `DESIGN.md` in its own folder. `web.css` holds the tokens recorded here, and `globals.css` holds the shared Tailwind setup with no token values. Another app's theme file imports `globals.css` and declares its own tokens, mapping and radius scale, so a change here never reaches it.
 
 ## Colors
 
 The light theme uses white surfaces, near-black text, and a dark neutral primary action. The dark theme reverses that relationship with near-black surfaces and near-white text. Muted neutrals separate supporting content. The destructive color is the only chromatic semantic token in the seed.
 
-Use the semantic custom properties in `packages/ui/src/styles/globals.css`. Do not copy their current `oklch()` values into components.
+Use the semantic custom properties in `packages/ui/src/styles/web.css`. Do not copy their current `oklch()` values into components.
 
 ## Typography
 
-The template uses Tailwind's system sans stack. Marketing headings use semibold weight, tight tracking, and the `text-3xl` through `text-6xl` scale. Body copy uses the `text-sm` through `text-lg` scale. Controls use medium weight at `text-xs` or `text-sm`.
+The template uses Tailwind's system sans stack, with no web font. Three named sizes in `web.css` carry the landing page's ramp. `text-display` is the hero's one `h1`: medium weight, very tight tracking, and fluid from `2.5rem` to `4.5rem`. `text-section-title` is every section's `h2`: semibold, tight, fluid from `2rem` to `3rem`. `text-lead` is the paragraph under either. The token map records the largest size of each fluid step. Body copy uses the `text-sm` through `text-lg` scale. Controls use medium weight at `text-xs` or `text-sm`. Code the page quotes (commands, module names, paths) uses the mono face at `text-xs` or the surrounding size.
 
 ## Layout
 
-Pages use centered maximum-width containers. Sections use responsive horizontal padding and large vertical gaps. Components use Tailwind's default spacing scale, which stays omitted from the token map because the project does not define a custom scale.
+Three container widths live in `web.css`. `section-container` is every section's frame at `64rem`. `section-container-narrow` is a deliberate `48rem` reading measure for the FAQ and the closing CTA. `section-container-wide` is `80rem`, for the navbar and the hero's product frame. All three share a `1.5rem` gutter. The sticky navbar floats: a gap holds it off the top of the viewport, and it overlays the first section instead of pushing it down. The hero's background, grid and light beams start at the top of the page, behind the bar, so no band of plain background shows above the hero. `section-y` is the one vertical rhythm between sections: `5rem` on small screens and `8rem` from `48rem` up. A block uses these names and sets no width or section padding of its own, so sections can be added, removed and reordered without the spacing drifting. Components use Tailwind's default spacing scale, which stays omitted from the token map because the project does not define a custom scale.
 
 ## Elevation & Depth
 
-Surfaces use borders, rings, and tonal contrast instead of a shadow scale. The small shadow on the input is a component detail. Do not infer a project shadow scale from it.
+Surfaces use borders, rings, and tonal contrast instead of a shadow scale. Landing cards add a hairline `shadow-xs`. Two elements carry a soft drop shadow tinted from `foreground`: the hero's product frame and the featured pricing tier. Those are the page's only raised surfaces. The small shadow on the input is a component detail. Do not infer a project shadow scale from any of them.
 
 ## Shapes
 
@@ -188,26 +202,36 @@ The base radius is `0.625rem`. Controls use the `lg` radius. Cards use `xl`. Lar
 
 ## Components
 
+The landing page is thirteen blocks in `packages/ui/src/blocks/`, composed by explicit imports in `apps/web/src/pages/index.astro`: navbar, hero, logo-cloud, pain-points, how-it-works, feature-grid, showcase, audience, testimonials, pricing-table, faq, cta and footer. They share one vocabulary. A section opens with a centred `section-title` and `lead`. Cards are bordered at the `xl` radius. A product visual sits in a double frame: an outer bordered shell at `1.25rem` and an inner surface at `0.875rem`. Primary calls to action sit in a thin ringed wrapper beside a ghost button. Decoration is drawn from tokens: the `grid-pattern` utility under a radial mask, and a dashed rule for dividers inside a card and above the footer.
+
 Primary buttons use the primary pair. Secondary buttons use the secondary pair. Destructive actions use the destructive token with restrained tint states. Inputs and buttons share a `2rem` default height and the `lg` radius. Cards use the card pair and a border-strength ring.
 
+Cards in one row share one height. The grid stretches its cards, so it carries no `items-start`, and sibling cards hold the same number of one-line items. The pricing tiers are the worked example: five one-line bullets each. A card's primary action sits inside that card, on the primary button, never below or beside it.
+
+A value that waits on a request shows the `Skeleton` primitive in its place, at the size the value will take, until the response arrives. It never shows a blank gap or a spinner. Add the primitive with `pnpm --filter @repo/ui exec shadcn add skeleton` the first time a page needs it.
+
 The `error-state` block is the one screen for a failure: a wrong path, a failed render, a server error. It is a single centered card holding a muted icon, a status label in the mono face at the smallest size, a title at `body-lg`, a description in `muted-foreground`, and one or two actions on the button scale. It carries no destructive token and no alert tint, because a mistyped address is not a danger state. Every app renders this block rather than its own error markup, so a theme change reaches all three at once.
 
 ## Do's and Don'ts
 
-- Read this file and `packages/ui/src/styles/globals.css` before you write UI.
+- Read this file and `packages/ui/src/styles/web.css` before you write UI.
 - Use semantic token utilities such as `bg-primary` and `text-muted-foreground`.
 - Keep light and dark token pairs together when you change a semantic role.
 - Keep new pages within the established type scale and radius vocabulary.
 - Do not add a color, radius, shadow, or type size that the code does not define.
 - Do not use a shadow when a border or tonal surface provides the needed separation.
 - Keep UI copy direct and specific. Use the product brief for product language.
+- Do not put a value in copy that goes stale: a version number, a release date, a count. Say something general and link to where the current value lives, the way the hero pill says "See what's new" and links to the changelog.
+- Open every link that leaves the site in a new tab. Spread `externalLinkProps(href)` from `@repo/ui/lib/external-link` onto the anchor and render `newTabHint(href)` inside it. A path on this site or a same-page anchor stays in the tab.
 
 ## Motion
 
-The template uses short Tailwind transitions for color and state changes. Accordion motion uses the animation supplied by the vendored primitive. Motion stays in prose because the DESIGN.md alpha schema has no motion token group.
+Motion is CSS only and additive. With reduced motion requested, or in a browser that lacks the feature, every element sits in its final state. The named utilities in `web.css` are the whole vocabulary: `blur-in` (the hero's load-time cascade, staggered with `--blur-in-delay`), `beam-in` (the hero's two light beams, which show from their top-left end and widen just after the cascade starts, staggered with `--beam-in-delay`), `reveal` (a scroll-tied entrance below the fold), `marquee` (the logo row), `shine-text` (the announcement pill), `nav-float` (the navbar frosting once the page scrolls) and `hover-lift`. Blocks use these names and write no keyframes. Color and state changes use short Tailwind transitions. Motion stays in prose because the DESIGN.md alpha schema has no motion token group. A theme toggle press reveals the new theme as a circle that grows from the button, through a view transition whose animation lives in `globals.css`. The script only starts it, and reduced motion skips it.
 
 ## Dark Mode
 
 The `.dark` class selects the dark token set. The pre-paint theme script applies the class before rendering and records the resolved mode in `data-theme`. Components must use semantic tokens so both themes stay aligned.
 
-_Seeded from the saasaloy base template · CLI {{CLI_VERSION}} · tokens sha256:101fd7fd684f of packages/ui/src/styles/globals.css_
+The theme toggle has two states, light and dark. `system` is only the starting state: a visitor who never pressed the toggle follows the OS. A press flips the resolved mode and stores the choice, and no press steps back to `system`. Do not add a third state or a light/dark/system menu to the toggle.
+
+_Seeded from the saasaloy base template · CLI {{CLI_VERSION}} · tokens sha256:e25d78b57596 of packages/ui/src/styles/web.css_

package/templates/base/apps/web/astro.config.mjs

@@ -5,6 +5,31 @@ import react from "@astrojs/react";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "astro/config";
 
+// `astro build` gets its own Vite cache. Both commands keep pre-bundled dependencies under
+// node_modules/.vite, each stamped with a hash of the config that made them. The two
+// hashes always differ, and Vite deletes a cache whose hash does not match. So a build
+// run beside a live `astro dev` deletes the dev server's deps_ssr folder, and the next
+// module the dev server loads from it fails with "The file does not exist at
+// .../deps_ssr/<dep>.js which is in the optimize deps directory". A separate folder for
+// the build keeps the two apart; dev keeps the default.
+/** @returns {import("astro").AstroIntegration} the integration that moves the build cache */
+function separateBuildCache() {
+  return {
+    name: "separate-build-cache",
+    hooks: {
+      "astro:config:setup": ({ command, updateConfig }) => {
+        if (command === "build") {
+          updateConfig({ vite: { cacheDir: "node_modules/.vite-build" } });
+        }
+      },
+    },
+  };
+}
+
+// Every React component the dev server can render, for Vite's dependency scan. See the
+// `optimizeDeps` notes in `vite` below.
+const COMPONENT_ENTRIES = ["src/**/*.tsx", "../../packages/ui/src/**/*.tsx"];
+
 // Static output — the marketing site is content-first, and every page here is
 // prerendered at build time. `output: "static"` is written out rather than left to the
 // default so the next person changing this file has to mean it.
@@ -44,7 +69,7 @@ export default defineConfig({
   // makes pnpm install the same plugin for the adapter. Move it and `wrangler` together:
   // they release as a pair, and apps/api (once added) pins the same two versions.
   adapter: cloudflare({ imageService: "compile" }),
-  integrations: [react()],
+  integrations: [react(), separateBuildCache()],
   // Fixed dev port. Every cross-origin consumer in this repo — the api Worker's CORS
   // allowlist, auth's `trustedOrigins`, the waitlist form's `PUBLIC_API_URL` fallback —
   // hardcodes the localhost dev origins, so the port cannot be allowed to drift.
@@ -53,8 +78,9 @@ export default defineConfig({
   server: { port: 3000 },
   vite: {
     // Tailwind 4 is a Vite plugin, not an Astro integration — `@astrojs/tailwind` is EOL
-    // and never supported v4. The theme itself (tokens, @source globs) lives in
-    // packages/ui/src/styles/globals.css, which Layout.astro imports via @repo/ui.
+    // and never supported v4. The theme lives in packages/ui: the @source globs in
+    // src/styles/globals.css, the tokens in src/styles/web.css, which Layout.astro
+    // imports via `@repo/ui/styles/web.css`.
     plugins: [tailwindcss()],
     server: { strictPort: true },
     // Dev only: pre-bundle every dependency the React components import before the
@@ -67,10 +93,14 @@ export default defineConfig({
     // A glob, not an include list, so a component a module adds is covered with no edit
     // here.
     ssr: {
-      optimizeDeps: {
-        entries: ["src/**/*.tsx", "../../packages/ui/src/**/*.tsx"],
-      },
+      optimizeDeps: { entries: COMPONENT_ENTRIES },
     },
+    // The browser needs the same entries. Its scan reads an .astro page's <script> tags but
+    // not the frontmatter that imports an island, so the islands' own dependencies arrive
+    // mid-request. Vite re-bundles, renames the shared chunks, and deletes the ones the
+    // page already asked for: "The file does not exist at .../deps/react-dom-<hash>.js
+    // which is in the optimize deps directory", then a full reload.
+    optimizeDeps: { entries: COMPONENT_ENTRIES },
     resolve: {
       // `@web` mirrors saasaloy.json's alias of the same name (apps/web/src) — that
       // alias only drives the CLI's file-placement when a module's files[] target

package/templates/base/apps/web/package.json

@@ -8,7 +8,7 @@
     "build": "astro build",
     "clean": "rimraf dist .astro .wrangler",
     "preview": "astro preview",
-    "deploy": "wrangler deploy"
+    "deploy": "env-deploy web"
   },
   "dependencies": {
     "astro": "7.3.5",
@@ -16,6 +16,7 @@
     "@astrojs/react": "7.0.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
+    "@repo/env": "workspace:*",
     "@repo/ui": "workspace:*"
   },
   "devDependencies": {