saasaloy 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,36 +11,30 @@ Every installed module ships a skill in `.agents/skills/<name>/SKILL.md`, linked
11
11
  This is a **pnpm workspace monorepo** managed by **Turborepo**.
12
12
 
13
13
  - **Root**: Configuration files only. Repository tooling lives in `packages/tooling` (see "Code at the Root")
14
- - **`apps/*`**: Applications (Next.js, Astro apps - currently empty, will be added)
14
+ - **`apps/*`**: Applications. The base ships `apps/web` (Astro). `saasaloy add` writes the others: `admin` and `app` (TanStack Router SPAs) and `api` (Hono on Workers)
15
15
  - **`packages/*`**: Shared packages
16
16
 
17
17
  ### Dev Port Map
18
18
 
19
- Every dev port in this repo is pinned, not assigned on the fly. The api Worker's CORS
20
- allow-list and the auth module's trusted origins hardcode the localhost origins, so a
21
- drifting port turns into an unexplained CORS rejection.
19
+ Every dev port in this repo is pinned, not assigned on the fly. The api Worker's CORS allow-list and the auth module's trusted origins hardcode the localhost origins, so a drifting port turns into an unexplained CORS rejection.
22
20
 
23
21
  | Workspace | Port | Dev URL | Pinned in |
24
22
  | --- | --- | --- | --- |
25
23
  | `apps/web` (Astro) | 3000 | `http://localhost:3000` | `apps/web/astro.config.mjs` (`server.port`) |
26
- | `apps/admin` (TanStack Start) | 3001 | `http://localhost:3001` | `apps/admin/vite.config.ts` (`server.port`, `strictPort`) |
24
+ | `apps/admin` (TanStack Router) | 3001 | `http://localhost:3001` | `apps/admin/vite.config.ts` (`server.port`, `strictPort`) |
25
+ | `apps/app` (TanStack Router) | 3002 | `http://localhost:3002` | `apps/app/vite.config.ts` (`server.port`, `strictPort`) |
26
+ | `packages/email-react` preview | 3003 | `http://localhost:3003` | `packages/email-react/package.json` (`dev`, `--port`) |
27
27
  | `apps/api` (Hono on Workers) | 4000 | `http://localhost:4000` | `apps/api/wrangler.jsonc` (`dev.port`) |
28
28
  | Postgres (local, `database-postgres`) | 5432 | `postgres://postgres:postgres@127.0.0.1:5432/app` | `DATABASE_URL` in `packages/env/.env.example` |
29
29
 
30
- The `apps/admin` and `apps/api` rows apply once you run `saasaloy add admin` or
31
- `saasaloy add api`.
30
+ The `apps/admin`, `apps/app`, preview and `apps/api` rows apply once you run `saasaloy add` for `admin`, `app`, `email-react` or `api`.
32
31
 
33
32
  Rules for a new app or service:
34
33
 
35
- - **Take the next free port in the block** — `apps/*` count up from 3000, backend services
36
- from 4000. Add a row to this table in the same change.
37
- - **Set `strictPort` (or the framework's equivalent).** A busy port must fail loudly. A
38
- silent `+1` moves the app to an origin nothing allows.
39
- - **Name the origin, don't infer it.** A browser-side caller reads `PUBLIC_API_URL`
40
- through `webEnv()` or `adminEnv()`, with no fallback — an unset key fails the build
41
- naming the key. A server-side caller reads its own key through `apiEnv(c.env)`.
42
- - **Update both allow-lists when you add a browser origin**: `DEV_ORIGINS` in
43
- `apps/api/src/index.ts` and `DEV_ORIGINS` in `packages/auth/src/auth.ts`.
34
+ - **Take the next free port in the block** — `apps/*` count up from 3000, backend services from 4000. Add a row to this table in the same change.
35
+ - **Set `strictPort` (or the framework's equivalent).** A busy port must fail loudly. A silent `+1` moves the app to an origin nothing allows.
36
+ - **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)`.
37
+ - **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`.
44
38
 
45
39
  ### Code at the Root
46
40
 
@@ -50,28 +44,17 @@ No code lives at the repository root. The root holds configuration only: `packag
50
44
 
51
45
  ### Workspace Commands
52
46
 
53
- - Filter to specific package: `pnpm --filter <package-name> <command>`
54
- - Example: `pnpm --filter @repo/ui build`
55
- - Use `pnpm turbo run <task> --filter <package-name>` for Turborepo tasks
47
+ Run a command in one package with `pnpm --filter <package-name> <command>` (`pnpm --filter @repo/ui build`), and a Turborepo task with `pnpm turbo run <task> --filter <package-name>`.
56
48
 
57
49
  ### The `clean` Script — Required in Every Workspace
58
50
 
59
- `pnpm clean` at the root wipes the repo back to a fresh-clone state: it runs
60
- `turbo run clean` across every workspace, then deletes all `node_modules` and `.turbo`
61
- directories. Recover with `pnpm install`.
51
+ `pnpm clean` at the root wipes the repo back to a fresh-clone state: it runs `turbo run clean` across every workspace, then deletes all `node_modules` and `.turbo` directories. Recover with `pnpm install`.
62
52
 
63
- **Every app and package you create MUST declare its own `clean` script.** A workspace
64
- without one is silently skipped by `turbo run clean` and leaves stale build output behind.
53
+ **Every app and package you create MUST declare its own `clean` script.** A workspace without one is silently skipped by `turbo run clean` and leaves stale build output behind.
65
54
 
66
- - Use **`rimraf`** (added as an exact-pinned `devDependency` of that workspace) — never
67
- `rm -rf`, which does not exist on Windows. Pass `-g` when any argument is a glob;
68
- without it rimraf treats arguments as literal paths.
69
- - Delete only what the workspace **generates**: `dist`, `.astro`, `.wrangler`,
70
- `*.tsbuildinfo`. Never delete committed source or generated-then-committed files
71
- (e.g. Drizzle migrations).
72
- - Do **not** delete `node_modules` or `.turbo` from a workspace-level `clean` — the root
73
- script removes those in one pass after Turborepo has finished. Deleting `.turbo` while
74
- Turborepo is still streaming its task log into it fails on Windows.
55
+ - Use **`rimraf`** (added as an exact-pinned `devDependency` of that workspace) — never `rm -rf`, which does not exist on Windows. Pass `-g` when any argument is a glob; without it rimraf treats arguments as literal paths.
56
+ - Delete only what the workspace **generates**: `dist`, `.astro`, `.wrangler`, `*.tsbuildinfo`. Never delete committed source or generated-then-committed files (e.g. Drizzle migrations).
57
+ - Do **not** delete `node_modules` or `.turbo` from a workspace-level `clean` — the root script removes those in one pass after Turborepo has finished. Deleting `.turbo` while Turborepo is still streaming its task log into it fails on Windows.
75
58
 
76
59
  ```jsonc
77
60
  // apps/<name>/package.json
@@ -85,51 +68,28 @@ without one is silently skipped by `turbo run clean` and leaves stale build outp
85
68
 
86
69
  ## Tech & Tools
87
70
 
88
- - **pnpm** — non-auth settings live in `pnpm-workspace.yaml` (camelCase), never `.npmrc`.
89
- Exact versions are pinned (`saveExact`).
71
+ - **pnpm** — non-auth settings live in `pnpm-workspace.yaml` (camelCase), never `.npmrc`. Exact versions are pinned (`saveExact`).
90
72
  - **TypeScript + ESM.** Internal packages are consumed JIT (no build step) via `workspace:*`.
91
- - **Add features, don't hand-wire them.** Prefer `saasaloy add <module>` over manually
92
- creating routes/schema/auth. Most of what a module contributes is a file dropped at a
93
- convention-based extension point; the rest is a small reversible patch on a file that has
94
- to name its entries statically. An api route is the second kind — `saasaloy add` edits
95
- `apps/api/src/index.ts` to add one `.route()` link and its import, and `saasaloy remove`
96
- takes both out again. Do not add a route by dropping a file into `apps/api/src/routes/`
97
- and expecting it to mount: nothing globs that folder, and the entry file's `AppType` is
98
- what the typed `hc` client reads.
73
+ - **Add features, don't hand-wire them.** Prefer `saasaloy add <module>` over manually creating routes/schema/auth. Most of what a module contributes is a file dropped at a convention-based extension point; the rest is a small reversible patch on a file that has to name its entries statically. An api route is the second kind — `saasaloy add` edits `apps/api/src/index.ts` to add one `.route()` link and its import, and `saasaloy remove` takes both out again. Do not add a route by dropping a file into `apps/api/src/routes/` and expecting it to mount: nothing globs that folder, and the entry file's `AppType` is what the typed `hc` client reads.
99
74
 
100
75
  ### The `@repo/env` Environment Layer
101
76
 
102
- `packages/env` owns every environment value this project reads. One tracked key list, one
103
- command that distributes it, one typed gate in front of the capabilities.
104
-
105
- - **`packages/env/.env.example` is the key list**, and it is the only example file. It is
106
- tracked, and `saasaloy add` regenerates it from the installed modules' own descriptions.
107
- A value you type in it survives that, and nothing is ever removed.
108
- - **`packages/env/.env` holds the values**, and it is gitignored. `saasaloy env` prompts
109
- for each unset key and writes it.
110
- - **`pnpm env:setup` writes every service's own `.env`** from those two files. A *service*
111
- is a workspace that reads a `.env` — `api`, `web`, `admin` — and
112
- `packages/env/src/services.ts` is the table. The `deploy` row has no file: it holds the
113
- Cloudflare credentials a deploy loads in memory.
77
+ `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.
78
+
79
+ - **`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.
80
+ - **`packages/env/.env` holds the values**, and it is gitignored. `saasaloy env` prompts for each unset key and writes it.
81
+ - **`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.
114
82
  - **`pnpm deploy:production` deploys every Worker.** It checks the git gates and every service's production values first, then deploys each Worker one at a time in the order `packages/tooling/src/targets.ts` gives. Each Worker runs its own `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/`. The `saasaloy-deploy` skill covers the gates, the flags and the rollback.
115
- - **`createEnv` is the gate.** `apiEnv(c.env)` on the server, `webEnv()` in a frontend.
116
- It validates on the first call and throws once naming every failing key, its module and
117
- what the key is for.
118
- - **A `client` key must start with `PUBLIC_`**, and the type system enforces it. Client
119
- code reading a server key throws by name.
120
- - **There is no `.dev.vars`.** Every runtime here reads `.env`. A leftover `.dev.vars`
121
- hides `.env` from wrangler without warning, so `saasaloy doctor` reports one and
122
- `pnpm env:setup` carries its values across and deletes it.
83
+ - **`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.
84
+ - **A `client` key must start with `PUBLIC_`**, and the type system enforces it. Client code reading a server key throws by name.
85
+ - **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.
123
86
  - **Never read `process.env`** in a file a Worker imports. Node tooling reads it freely.
124
87
 
125
- The `saasaloy-env` skill is the runbook: adding a key, the section rule, the server/client
126
- split, blank-on-purpose keys, and the offline rule.
88
+ 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.
127
89
 
128
90
  ### The `@repo/config` Value Layer
129
91
 
130
- `packages/config` (`@repo/config`) owns the values this project checks into its repo and ships
131
- identically to every environment: the product name, the locale, the legal paths, and each
132
- installed module's section. Read it with a plain import, from any app or package:
92
+ `packages/config` (`@repo/config`) owns the values this project checks into its repo and ships identically to every environment: the product name, the locale, the legal paths, and each installed module's section. Read it with a plain import, from any app or package:
133
93
 
134
94
  ```ts
135
95
  import { config } from "@repo/config";
@@ -138,15 +98,11 @@ config.app.name; // `siteName` in @repo/ui re-exports this
138
98
  config.app.locale; // the shared layout's <html lang>
139
99
  ```
140
100
 
141
- It is a frozen plain object, built once at module load. It has **zero runtime dependencies and
142
- imports nothing**, which is what lets every app, every package and every browser bundle import it.
101
+ It is a frozen plain object, built once at module load. It has **zero runtime dependencies and imports nothing**, which is what lets every app, every package and every browser bundle import it.
143
102
 
144
- **config or `.env`?** Two deployments of *this* project — production and staging. If the value can
145
- differ between them it is an env var, secret or not. If it cannot, it is config. A database URL is
146
- env; the product's name is config.
103
+ **config or `.env`?** Two deployments of *this* project — production and staging. If the value can differ between them it is an env var, secret or not. If it cannot, it is config. A database URL is env; the product's name is config.
147
104
 
148
- **The landing copy is not config.** Prices, tier ids and every sentence on the page stay in
149
- `@repo/ui/content/landing.ts`.
105
+ **The landing copy is not config.** Prices, tier ids and every sentence on the page stay in `@repo/ui/content/landing.ts`.
150
106
 
151
107
  Four files, and only one is yours:
152
108
 
@@ -157,418 +113,62 @@ Four files, and only one is yours:
157
113
  | `src/sections/<key>.ts` | The module that installed it (`app` is the base's). |
158
114
  | `src/define.ts` | The base template. The composition core. |
159
115
 
160
- The merge goes **one level below the section**: `app: { name: "..." }` replaces the name and keeps
161
- the rest of `app`, while a nested record or an array is replaced whole. A key no installed section
162
- defines is a `typecheck` error, which is the only validation there is — the values are literals in
163
- this repo. Run `/saasaloy-config` for the whole runbook.
116
+ The merge goes **one level below the section**: `app: { name: "..." }` replaces the name and keeps the rest of `app`, while a nested record or an array is replaced whole. A key no installed section defines is a `typecheck` error, which is the only validation there is — the values are literals in this repo. Run `/saasaloy-config` for the whole runbook.
164
117
 
165
118
  ### The `@repo/ui` Design Layer
166
119
 
167
- `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/`.
168
-
169
- 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/`).
170
-
171
- The theme is one shared file plus one theme file per app:
172
-
173
- - **`src/styles/globals.css`** is the shared layer: the Tailwind imports, the `@source`
174
- globs and the base layer. It holds no token values, and no app imports it directly.
175
- - **`src/styles/web.css`** is the web app's theme: the `dark` custom variant, its `:root`
176
- and `.dark` token values, its `@theme inline` colour mapping and its radius scale. It
177
- imports `globals.css`, and `apps/web` pulls it in once, through the shared layout that
178
- imports `@repo/ui/styles/web.css`. `components.json` points here, so a shadcn preset
179
- lands here. The landing page's layout, type and motion utilities sit at the end of the
180
- file, after the colour tokens, and a preset leaves them alone.
181
- - **`src/styles/admin.css`** is the admin app's theme, in the same shape, written by
182
- `saasaloy add admin`.
183
-
184
- Each theme file repeats the `dark` variant and the `@theme inline` mapping on purpose.
185
- shadcn merges a preset in place only when the target file itself holds them, and it does
186
- not look through an `@import`. Move either one into `globals.css` and a preset appends a
187
- duplicate to `web.css` instead.
188
-
189
- **Each app has its own `DESIGN.md`, in its own folder.** `apps/web/DESIGN.md` records the
190
- web tokens in `web.css` and the rules behind them, and fingerprints `web.css`. An app
191
- that carries its own theme file gets its own `apps/<app>/DESIGN.md`, which fingerprints
192
- that file. There is no `DESIGN.md` at the repository root. Read the document for the app
193
- you are changing before you add or change UI.
120
+ `packages/ui` owns the design layer: the Tailwind theme in `src/styles/`, the vendored shadcn primitives, the blocks, the containers and the copy. Its own guide is `packages/ui/AGENTS.md`. Read it before you add or change UI in any app. These are the rules that reach past the package:
194
121
 
195
- 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.
122
+ - **Read the app's `DESIGN.md` first.** `apps/web/DESIGN.md` covers the web app, and `apps/admin/DESIGN.md` covers the admin app when it is installed. There is no `DESIGN.md` at the repository root.
123
+ - **No IO in `@repo/ui`.** A block or a container takes its data, its links and its callbacks as props. The app owns fetch, auth, the router and the stores, and passes in what the block needs.
124
+ - **Import by subpath.** `import { Button } from "@repo/ui/components/button"`. The package root exports project-wide constants only (`siteName`).
125
+ - **The signed-in apps use the `shell` set.** `apps/admin` and `apps/app` import from `@repo/ui/{components,blocks,containers}/shell/*`, and a lint rule makes a base primitive there an error.
126
+ - **Words live in `packages/ui/src/content/`**, never in a block, so a copy pass and a later translation find them.
127
+ - **No UI kit as a dependency.** Copy a kit's component into `src/components/` or `src/blocks/` as source this project owns.
196
128
 
197
- Primitives, blocks and containers are reached by subpath — none is re-exported from the
198
- package root, so importing one never drags in the rest. The root export is project-wide
199
- constants only (`siteName`, which re-exports `config.app.name`):
129
+ ### The Base Skills
200
130
 
201
- ```ts
202
- import { siteName } from "@repo/ui";
203
- import { Button } from "@repo/ui/components/button";
204
- import { PricingTable } from "@repo/ui/blocks/pricing-table";
205
- import { landing, ui } from "@repo/ui/content/landing";
206
- import { cn } from "@repo/ui/lib/utils";
207
- ```
208
-
209
- **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:
210
-
211
- ```ts
212
- import { Button } from "@repo/ui/components/admin/button";
213
- import { DataTable } from "@repo/ui/blocks/admin/data-table";
214
- import { PageHeader } from "@repo/ui/blocks/admin/page-header";
215
- import { PageLayout } from "@repo/ui/containers/admin/page-layout";
216
- ```
131
+ Seven skills ship with the base, as real files in `.agents/skills/` linked into `.claude/skills/`. Two run in order when you make the project yours:
217
132
 
218
- The `saasaloy-admin` skill lists the whole set and how a page composes it.
133
+ 1. **`saasaloy-setup`** interviews the owner once and writes `docs/product-brief.md`, then sets `config.app.name` and `config.app.locale`. Other skills read the brief rather than ask again.
134
+ 2. **`saasaloy-landing-copy`** writes `packages/ui/src/content/landing.ts` from the brief.
219
135
 
220
- **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.
136
+ The other five run when the thing they own moves:
221
137
 
222
- 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.
223
- 2. **`src/components/`** holds the vendored shadcn primitives, official and custom. No stores, no copy.
224
- 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.
225
- 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.
226
- 5. **`src/content/`** holds copy, in one place for later translation.
227
- 6. **`src/lib/`** holds utilities and the client-state stores.
228
- 7. **`src/styles/`** holds the CSS files with the token variables.
229
-
230
- **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.
231
-
232
- **Adding a primitive the base doesn't vendor.** `shadcn` is already an exact-pinned
233
- dependency of `@repo/ui`, so reach it with `--filter … exec` — that runs in the package
234
- directory, where `components.json` lives:
235
-
236
- ```sh
237
- pnpm --filter @repo/ui exec shadcn add dialog
238
- ```
239
-
240
- - **Not `pnpm -C packages/ui dlx …`.** `-C` scopes pnpm's own workspace resolution; it
241
- does *not* change the directory `dlx` spawns the command in. shadcn then looks for
242
- `components.json` wherever your shell happens to be and dies at `Verifying framework`.
243
- If you must use `dlx`, pass shadcn's own flag: `--cwd packages/ui`.
244
- - Never `npx` (see Never Do).
245
- - The CLI writes into `src/components/`. Anything it appends to `package.json` arrives
246
- as a range — **re-pin it to an exact version**.
247
- - **Add the primitive to a `@source` list, or it renders unstyled.** `globals.css` names
248
- the components it scans one file at a time, because Tailwind scans content rather than
249
- imports and a blanket glob charges every app for every primitive. A primitive the
250
- landing page or `src/blocks/` renders gets an `@source "../components/<name>.tsx";` line
251
- in `globals.css`; a primitive only one app renders gets its `@source` line in that app's
252
- own theme file, the way `src/styles/admin.css` takes the whole directory.
253
- Nothing errors when you skip this — the classes just never reach the CSS.
254
- - `style` is `base-nova` (Base UI) and is fixed at init — the CLI cannot change it later.
255
- - `rsc` is `false`, so the CLI strips the `"use client"` directive for you. It means
256
- nothing in Astro, and the vendored primitives don't carry it.
257
-
258
- Primitives are source you own. Edit them in place rather than wrapping them.
259
-
260
- **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.
261
-
262
- **Swapping the whole theme for a preset.** The token set in
263
- `packages/ui/src/styles/web.css` is shadcn's `neutral` with `cssVariables: true`, and
264
- any shadcn **`registry:style`** item is a drop-in replacement for it. The same
265
- `--filter … exec` form applies — there is no separate theme command:
266
-
267
- ```sh
268
- pnpm --filter @repo/ui exec shadcn add https://tweakcn.com/r/themes/modern-minimal.json
269
- ```
270
-
271
- The CLI merges the preset's `:root`, `.dark` and `@theme inline` blocks **into** the
272
- existing ones in `web.css` and keeps its `@custom-variant dark`, so the hand-written
273
- parts in `globals.css` — the `@source` rules and the `@layer base` rules — stay put, and
274
- `components.json` is not touched. The preset reaches the web app only; the admin theme
275
- in `admin.css` keeps its own values. It usually *extends* `@theme inline` with mappings
276
- the base does not carry (fonts, tracking, shadows); that is expected.
277
-
278
- Two places to get an item from:
279
-
280
- 1. **[`https://ui.shadcn.com/create`](https://ui.shadcn.com/create)** — first-party.
281
- Describe or dial in a theme and it hands you a URL.
282
- 2. **[`https://tweakcn.com`](https://tweakcn.com)** — a much larger preset library,
283
- serving items at `https://tweakcn.com/r/themes/<name>.json`.
284
-
285
- Neither is special: the mechanism is the `registry:style` shape, so any URL that serves
286
- one works.
287
-
288
- **This edits a file the project owns.** `web.css` is an owned base file: `saasaloy
289
- update` never overwrites it, and a later template change to it reaches you only through
290
- the merge plan. A swapped theme is yours to maintain, including re-applying anything you
291
- had customised in `web.css` that the preset overwrote. Diff the file after running the
292
- command rather than assuming.
293
-
294
- 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.
295
-
296
- 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.
297
-
298
- **A project made before the theme split.** Older projects kept the web tokens in
299
- `globals.css` and the design document at the repository root. `saasaloy update` creates
300
- `packages/ui/src/styles/web.css` and lists `globals.css` and `Layout.astro` in the merge
301
- plan, because the project owns both; it never moves your tokens for you. Finish the split
302
- by hand, in this order:
303
-
304
- 1. Move the `@custom-variant dark` line, the `:root` block, the `.dark` block and the
305
- `@theme inline` block from `globals.css` into `web.css`, replacing the template's
306
- copies there, below its `@import "./globals.css";`. Keep your own values, not the
307
- template's.
308
- 2. Add `"./styles/*": "./src/styles/*"` to the `exports` of `packages/ui/package.json`,
309
- if the update did not.
310
- 3. In `apps/web/src/layouts/Layout.astro`, import `@repo/ui/styles/web.css` in place of
311
- `@repo/ui/globals.css`.
312
- 4. Set `tailwind.css` in `packages/ui/components.json` to `src/styles/web.css`, if the
313
- update did not.
314
- 5. Move `DESIGN.md` to `apps/web/DESIGN.md`, and run the `saasaloy-design` skill's
315
- `update` flow so its fingerprint names `web.css`.
316
- 6. Run `pnpm build` and check that `globals.css` and `web.css` hold one `@theme inline`
317
- and one `@custom-variant dark` between them.
318
-
319
- With the admin app installed, `saasaloy update` also moves its theme: it creates
320
- `packages/ui/src/styles/admin.css` and deletes `apps/admin/src/styles/admin.css`, or
321
- keeps it with a warning when you edited it. Carry any edit across to the new file, then
322
- delete the old one. The new admin app imports `@repo/ui/styles/admin.css`, so its build
323
- fails until step 2 adds the `./styles/*` export. Update the base and finish step 2 before
324
- you build admin, and before you run `saasaloy add admin` on a project made before the
325
- split.
326
-
327
- **Blocks — the page-level compositions.** `src/blocks/` holds the thirteen marketing
328
- blocks the landing page is built from: `navbar`, `hero`, `logo-cloud`, `pain-points`,
329
- `how-it-works`, `feature-grid`, `showcase`, `audience`, `testimonials`, `pricing-table`,
330
- `faq`, `cta` and `footer`. `logo-cloud`, `pain-points`, `how-it-works`, `showcase`,
331
- `audience` and `testimonials` are new; a project scaffolded before them gets the files
332
- through `saasaloy update`, and adds each to its own `index.astro` by hand, since the page
333
- is the owner's. The blocks need the landing utilities at the end of `web.css`. `web.css`
334
- is an owned file, so `update` lists it in the merge plan and never adds them for you.
335
- Copy the template's block, from the comment that opens "The landing page's layout" to
336
- the `stylelint-enable` line, to the end of your `web.css`. A project made before the
337
- theme split skips this: `update` creates its `web.css` from the template, block included.
338
-
339
- **The section recipe.** `index.astro` composes the page from explicit imports, one line
340
- per section. To remove a section, delete its line and its import, delete its file in
341
- `src/blocks/`, and blank its navbar and footer labels in `landing.ts`. To reorder, move
342
- the lines. Every block uses the same container (`section-container`, `-narrow`, `-wide`)
343
- and spacing (`section-y`) utilities from `src/styles/web.css`, so any order keeps one
344
- rhythm. A block sets no width, no section padding and no keyframes of its own; motion
345
- comes from the named utilities there (`blur-in`, `beam-in`, `reveal`, `marquee`,
346
- `shine-text`, `nav-float`, `hover-lift`), and every one stops under reduced motion.
347
-
348
- **The logo recipe.** `landing.logos.items[]` is `{ id, name, mark }`. `mark` is a key in
349
- `LOGO_MARKS` at the top of `blocks/logo-cloud.tsx`. Paste a customer's SVG there under a
350
- kebab-case key with `fill="currentColor"`, then name the key in content. An unknown key
351
- renders `name` as a text wordmark.
352
-
353
- **The production bar.** The page holds to a rubric: no axe violation at WCAG 2.1 AA in
354
- either theme, no sideways scroll from 360px up, nothing animating under reduced motion, a
355
- skip link to `<main>` on every page, link-preview metadata on `/`, and exactly two islands
356
- (`Navbar`, `PricingTable`). Keep each true when you change a block: a new section with
357
- state is a third island and needs a reason.
358
-
359
- The rules below are not stylistic — each one prevents a real failure:
360
-
361
- - **One block, one file, one component export (plus its prop types).**
362
- `pricing-table.tsx` exports `PricingTable` alongside `PricingTier` and
363
- `PricingTableProps`, and nothing else — no second component, no default export, no
364
- `blocks/index.ts` barrel. Astro gives every `client:*` component its own React root, so
365
- a compound primitive (accordion, dialog, dropdown) split across an `.astro` file throws
366
- "must be used within" at runtime. Keep the whole composition inside the block.
367
- - **Props-driven, with every default read from the content module.** Every prop is still
368
- optional and still carries a default — but the *words* come from
369
- `packages/ui/src/content/landing.ts`, not from the block. `hero.tsx` has
370
- `title = landing.hero.title`; `pricing-table.tsx` holds no tier data at all. Keep the
371
- props for the cases a page really varies (a second landing page can override any of
372
- them); change the copy by editing the content module. See below.
373
- - **Never pass a component or a function as a prop from `.astro`.** Astro serializes
374
- island props, so icons live *inside* the block. Swap one by editing the block.
375
- - **Semantic kebab-case filenames** (`feature-grid.tsx`), never shadcn's registry-style
376
- `{category}-{NN}` numbering — that disambiguates variants in a public registry, and
377
- this project has neither.
378
- - **Static by default.** A block with no state renders to HTML and ships zero JS. Add a
379
- client directive only to the block that actually needs the browser, and pick the
380
- cheapest one: `client:idle` above the fold, `client:visible` below it. A blanket
381
- `client:load` on the page hydrates everything and throws away the reason this is a
382
- static site — see `apps/web/src/pages/index.astro` for the worked example.
383
- - **`theme-toggle` is the exception that proves the rule.** It sits in `src/blocks/`
384
- beside the marketing blocks but is chrome, not copy: `navbar.tsx` renders it inside the
385
- bar, and it needs **no** client directive of its own despite being interactive. It has
386
- no `onClick` and no state — the pre-paint inline script the shared layout emits
387
- (`THEME_INIT_SCRIPT`, from `packages/ui/src/lib/theme.ts`) drives every
388
- `[data-theme-toggle]` on the page through one delegated listener, and CSS picks the
389
- icon off `<html data-theme>`. Move it, restyle it via its `className`, or delete the
390
- one line in `navbar.tsx` to drop it. Do **not** "fix" it by adding `client:*` or an
391
- `onClick`, and do not paste a second copy of the boot script into a page: any document
392
- that renders the block must inline that one constant in its `<head>`, or the control
393
- stays hidden.
394
- - **`error-state` is the only error screen, and every app renders it.** An app that adds
395
- a route surface answers a miss with `ErrorState` — `apps/web` through
396
- `src/pages/404.astro`, the admin SPA through the root route's `notFoundComponent` and
397
- its error boundary, and `apps/api` through `base.notFound(...)`, which answers the same
398
- `{ error: { code, message } }` envelope as every other failure. Do **not** write a
399
- second error screen in an app: one block means one restyle when the theme moves, and a
400
- bespoke copy drifts out of the token vocabulary the day nobody is looking. Change the
401
- words in `packages/ui/src/content/errors.ts`, the markup in
402
- `packages/ui/src/blocks/error-state.tsx`.
403
- - **A `prerender = false` page inherits `500.astro`.** `apps/web` registers
404
- `@astrojs/cloudflare` while staying on `output: "static"`, so `src/pages/500.astro` is
405
- built ahead of time and carries no detail from the failed request. The day a page opts
406
- into on-demand rendering, a throw inside it lands on that page for free — nothing to
407
- add. Two things move on that day and only that day: `wrangler.jsonc` gains a `main`
408
- pointing at the server entry the adapter now writes, and `dist/server` stops being
409
- empty. Setting `main` before then breaks the build, which is why the comment in
410
- `wrangler.jsonc` says to wait.
411
- - **A block never reaches the network; the app injects the behaviour.** A block that needs
412
- to send something takes a function prop (`onSubmit`) and calls it. It does not import an
413
- api package, an http client, or `import.meta.env`. Two reasons, both concrete.
414
- `packages/ui` has a `typecheck` script and consumes workspaces as source, so one
415
- `import type { AppType } from "@repo/api/client"` here makes `tsc` compile the entire
416
- Worker source tree under this package's tsconfig. And a block that hardcodes an endpoint
417
- is a block you cannot reuse on a second page. The counterpart lives in the app: a small
418
- React file under `apps/web/src/components/` builds the client and passes the function
419
- down. Astro serializes island props, so the page renders **that** file, never the block
420
- directly.
421
- - **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.
422
- - **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.
423
- - **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`.
424
- - **A module's UI arrives here too, and you wire it up by hand.** `saasaloy add <module>`
425
- writes a UI-bearing module's block into `src/blocks/` exactly like the base blocks, adds
426
- the app-side island that feeds it, and then stops: nothing globs a folder, and no command
427
- edits `index.astro`. The command prints a pointer to the module's skill, and that skill's
428
- **Wire-up** section carries the import line, the component to render, the client
429
- directive, and a suggested spot on the page. Put it where you want it. `saasaloy remove`
430
- deletes the files it wrote and leaves your import alone, so take that line out yourself.
431
-
432
- Blocks, like primitives, are source you own — they are meant to be edited, not wrapped.
433
-
434
- **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/`.
435
-
436
- - **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.
437
- - **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.
438
- - **Still no IO.** A container does not fetch, persist, or authenticate.
439
- - **Same file rules as blocks:** one container per file, semantic kebab-case filename, no barrel.
440
-
441
- **The content module — where the words live.** `packages/ui/src/content/landing.ts` holds
442
- every user-visible string on the landing page, in two namespaces:
443
-
444
- - **`landing.*`** — marketing copy. What the product is, who it is for, what it costs.
445
- This is the whole surface a copy rewrite touches. The brand itself is not here: it is
446
- `config.app.name` in `packages/config/src/project.ts`, is not translated, and is set once
447
- by `saasaloy-setup`. The currency symbol and the tier ids and names are read from
448
- `@repo/config` for the same reason — they are ids and numbers, and `packages/billing`
449
- charges against the same ids.
450
- - **`ui.*`** — chrome and accessibility labels (`Monthly`, `Most popular`, `Close menu`,
451
- `Billing period`). Nothing here says anything about the product, so a copy pass never
452
- rewrites it. It does get translated, key for key, when `landing.*` is written in some
453
- language other than English — no translation layer ships in the base, so that pass is the
454
- only one these strings get.
455
-
456
- Blocks import it **directly** — `import { landing, ui } from "@repo/ui/content/landing"` —
457
- never as props from `index.astro`. Astro serializes island props, so passing content into
458
- `<PricingTable client:visible />` would write every string into the HTML payload *and*
459
- still ship the defaults inside the island's bundle. Direct import keeps the static blocks
460
- at zero JavaScript.
461
-
462
- Five rules keep that file mechanically translatable — a translation layer reads a keyed
463
- record and nothing else. Follow them when you add a block or a key:
464
-
465
- 1. **Max three levels below a namespace** (`landing.features.title`). Compiler-based i18n
466
- libraries emit one flat identifier per message and cannot see deeper nesting.
467
- 2. **Position is never the key.** Lists are arrays whose items carry a stable `id`, so
468
- reordering the feature grid cannot silently reattach the wrong translation. One list is
469
- exempt — a tier's `features` bullets stay a plain `string[]`, because nothing reads them
470
- individually (a feature id and an FAQ id both anchor an item that outlives its wording)
471
- and a tier's bullets are rewritten with that tier. The content file states the trade-off
472
- in full.
473
- 3. **Single-brace `{token}` placeholders, never a template literal.** Copy is data; a
474
- template literal is a function, which no extraction tool can read. Render with
475
- `interpolate()` from `@repo/ui/lib/interpolate`.
476
- 4. **No runtime concatenation.** `/month` plus `", billed annually"` is two whole
477
- messages (`ui.pricing.perMonth`, `ui.pricing.perMonthAnnual`) — word order does not
478
- survive the seam in every language.
479
- 5. **Only user-visible strings move.** Section `id`s and the same-page anchors pointing at
480
- them are structure and stay in the block. A few things break the rule, all because a
481
- thing rewritten *with* the copy belongs *near* the copy: the whole `tiers` array (prices
482
- and `ctaHref`s included); every `icon`, held as a registry *name* like `"zap"` and
483
- resolved to a component by `packages/ui/src/lib/icons.ts`, and every logo `mark`,
484
- resolved by `blocks/logo-cloud.tsx`; every outbound link (`*Href`), which leaves the
485
- page and so cannot break a section link; and the code the page quotes (terminal
486
- commands, module names, file paths). A translation layer reads `id`, `icon`, `mark`,
487
- every `*Href` and the quoted code as non-message data. A pair of backticks inside a
488
- message renders as `<code>` through `inlineCode()` from `@repo/ui/lib/inline-code`.
489
-
490
- **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.
491
-
492
- Two consequences worth knowing. Blanking a navbar or footer link's label in content drops
493
- that link, which is how a removed section loses its nav entry without editing a block. And
494
- the theme toggle's labels deliberately stay in `packages/ui/src/lib/theme.ts`: that file is
495
- inlined verbatim into a pre-paint `<script>` and is import-free on purpose.
496
-
497
- **The default copy is Saasaloy's own.** A fresh project's page describes Saasaloy, and
498
- `config.app.name` in `packages/config/src/sections/app.ts` defaults to `"Saasaloy"`, so the brand and the
499
- words agree until you replace both. The two skills below replace them in one pass.
500
-
501
- **Making this project yours.** Four skills ship with the base (linked at
502
- `.claude/skills/`, real files in `.agents/skills/`). The first two run in order:
503
-
504
- 1. **`saasaloy-setup`** asks ten questions about the product — starting with its name — and
505
- writes the answers to `docs/product-brief.md`. Every question carries sample answers you
506
- can take, edit, or ignore. It also sets `config.app.name` and `config.app.locale`. Nothing else
507
- reads your product knowledge out of your head, so run it first; other skills read the
508
- brief rather than interviewing you again.
509
- 2. **`saasaloy-landing-copy`** turns that brief into the landing page's words. It drafts
510
- into `docs/landing-copy-draft.md` for you to review and edit, then writes
511
- `packages/ui/src/content/landing.ts` once you approve, then deletes the draft.
512
-
513
- The other two have no place in that order, because they run whenever the thing they own moves:
514
-
515
- 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
516
- preset and re-derives the contract; `update` re-derives after you change `web.css` or
517
- add components; `audit` reports where the code and the contract disagree. It reads the
518
- product brief when one exists and never writes it.
519
- 4. **`saasaloy-config`** covers `@repo/config`: the config-versus-`.env` rule, adding a
520
- section, the merge rule, and why an override is not taking effect.
521
-
522
- Invoke them rather than editing thirteen blocks by hand — and if you do edit by hand, keep the
523
- strings in the content module so the next pass finds them.
138
+ - **`saasaloy-design`** keeps each app's `DESIGN.md` true, and swaps the web theme for a shadcn preset.
139
+ - **`saasaloy-config`** covers `@repo/config`: a section, the merge rule, config versus `.env`.
140
+ - **`saasaloy-env`** covers `packages/env`: adding a key, the server and client split, `pnpm env:setup`.
141
+ - **`saasaloy-testing`** says which test a change needs under this project's testing mode.
142
+ - **`saasaloy-deploy`** covers `pnpm deploy:production`, its gates and the rollback.
524
143
 
525
144
  ### Naming Conventions
526
145
 
527
- - **Functions**: camelCase (`fetchUserData`, `calculateTotal`)
528
- - **Components**: PascalCase (`UserProfile`, `DataTable`)
529
- - **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`, `MAX_RETRIES`)
530
- - **Types/Interfaces**: PascalCase (`User`, `ApiResponse`)
146
+ - **Code**: camelCase functions (`fetchUserData`), PascalCase components and types (`UserProfile`, `ApiResponse`), UPPER_SNAKE_CASE constants (`MAX_RETRIES`)
531
147
  - **Files**: kebab-case for components (`user-profile.tsx`), camelCase for utilities (`utils.ts`)
532
148
 
533
149
  ## Linting, Formatting, and Commit Hooks
534
150
 
535
- The linter is **[oxlint](https://oxc.rs)** configured from
536
- **[Ultracite](https://www.ultracite.ai)**'s presets, with **Prettier** and **Stylelint**
537
- owning formatting. All four run from `oxlint.config.mjs`, `prettier.config.js` and
538
- `stylelint.config.js` at the root — there is no shared config package, because oxlint
539
- cannot consume one (`extends` takes file paths, JSON only).
151
+ The linter is **[oxlint](https://oxc.rs)** configured from **[Ultracite](https://www.ultracite.ai)**'s presets, with **Prettier** and **Stylelint** owning formatting. All four run from `oxlint.config.mjs`, `prettier.config.js` and `stylelint.config.js` at the root — there is no shared config package, because oxlint cannot consume one (`extends` takes file paths, JSON only).
540
152
 
541
153
  - `pnpm lint` — the gate. Four passes, in order:
542
- 1. `lint:types` — oxlint with `--type-aware` over `packages/env/src`, `packages/tooling/src` and `packages/ui/src`
154
+ 1. `lint:types` — oxlint with `--type-aware` over `packages/config/src`, `packages/env/src`, `packages/tooling/src` and `packages/ui/src`
543
155
  2. `lint:code` — oxlint over everything, no type information
544
156
  3. `lint:css` — Stylelint over `**/*.css`
545
157
  4. `format:check` — `prettier --check .`
546
- - `pnpm lint:fix` — passes 1-3 with `--fix`: the type-aware oxlint invocation over
547
- the same three folders, the plain one over everything, then Stylelint. **Never** add
548
- `--fix-suggestions`: it rewrites `a[i++]` to `a[i += 1]`, which is a different program.
158
+ - `pnpm lint:fix` — passes 1-3 with `--fix`: the type-aware oxlint invocation over the same four folders, the plain one over everything, then Stylelint. **Never** add `--fix-suggestions`: it rewrites `a[i++]` to `a[i += 1]`, which is a different program.
549
159
  - `pnpm format` — `prettier --write .`
550
- - `pnpm typecheck` — `tsc`, and it must pass before you commit.
160
+ - `pnpm typecheck` — `turbo run typecheck`, which runs `tsc` in each workspace, and it must pass before you commit.
551
161
 
552
- **Why the type-aware pass is scoped and the plain one is not.** `--type-aware` is a
553
- global CLI switch, so the split is by invocation rather than by config. It stays off
554
- `.astro` because `apps/web/tsconfig.json` includes the build-generated
555
- `.astro/types.d.ts`, which would make `astro sync` a prerequisite of every `pnpm lint`,
556
- including on a fresh clone. Do not merge the two passes.
162
+ **Why the type-aware pass is scoped and the plain one is not.** `--type-aware` is a global CLI switch, so the split is by invocation rather than by config. It stays off `.astro` because `apps/web/tsconfig.json` includes the build-generated `.astro/types.d.ts`, which would make `astro sync` a prerequisite of every `pnpm lint`, including on a fresh clone. Do not merge the two passes.
557
163
 
558
- **Markdown is not formatted.** `.prettierignore` excludes `**/*.md` because Ultracite's
559
- Prettier config sets `proseWrap: "never"`, which would collapse every hand-wrapped
560
- paragraph — this file included — into a single line.
164
+ **Markdown is not formatted.** `.prettierignore` excludes `**/*.md` because Ultracite's Prettier config sets `proseWrap: "never"`, which would collapse every hand-wrapped paragraph into a single line.
561
165
 
562
166
  **Commit hooks are installed by husky** on your first `pnpm install`, and they need a `.git` directory, which `saasaloy init` creates for you. The root `prepare` script is `husky && node packages/tooling/src/link-skills.ts`, so the same install also links every folder in `.agents/skills/` into `.claude/skills/`. pnpm skips `prepare` when an install changes nothing, so after you add a skill folder to a checkout that is already installed, run `pnpm skills:link`. The hooks:
563
167
 
564
- - `pre-commit` runs **lint-staged** over staged files only — oxlint `--fix`, Stylelint
565
- `--fix`, Prettier `--write`. It skips the type-aware pass on purpose: that one needs the
566
- whole project graph, which defeats staged-file scoping.
567
- - `commit-msg` runs **commitlint** with `@commitlint/config-conventional`, so messages
568
- must read `type(scope): subject` — `feat:`, `fix(api):`, `chore(deps):`.
168
+ - `pre-commit` runs **lint-staged** over staged files only — oxlint `--fix`, Stylelint `--fix`, Prettier `--write`. It skips the type-aware pass on purpose: that one needs the whole project graph, which defeats staged-file scoping.
169
+ - `commit-msg` runs **commitlint** with `@commitlint/config-conventional`, so messages must read `type(scope): subject` — `feat:`, `fix(api):`, `chore(deps):`.
569
170
 
570
- Bypass in a genuine emergency with `git commit --no-verify`, or `HUSKY=0` to skip every
571
- hook (which is also how you keep hooks out of CI).
171
+ Bypass in a genuine emergency with `git commit --no-verify`, or `HUSKY=0` to skip every hook (which is also how you keep hooks out of CI).
572
172
 
573
173
  ## Testing Instructions
574
174
 
@@ -580,9 +180,9 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
580
180
  - Turn module tests on with `saasaloy testing tests-after`, or `saasaloy testing tdd` to work test-first.
581
181
  <!-- /saasaloy:testing -->
582
182
 
183
+ - Run every gate at once: `pnpm check`. It runs `typecheck`, `lint`, `test` and `build` in that order, stops at the first failure, and edits no file. Run `pnpm lint:fix` and `pnpm format` first.
583
184
  - Run type checking: `pnpm typecheck` (must pass before commits)
584
- - Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes)
585
- - Check formatting: `pnpm format:check`, or `pnpm format` to rewrite
185
+ - Run linting: `pnpm lint` (see above — it reports, `pnpm lint:fix` fixes, and `pnpm format` rewrites the formatting)
586
186
  - 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.
587
187
  - Run the browser suite: `pnpm e2e`, once `saasaloy add e2e` is installed. It is Playwright against the running apps, in `packages/e2e`. Run `pnpm e2e:install` once per machine first to download Chromium. The root `vitest.config.ts` leaves `packages/e2e` out, so `pnpm test` never collects a Playwright spec. The `saasaloy-e2e` skill covers adding a flow and reading a red run.
588
188
  - `packages/tooling` tests run on Vitest through the root `vitest.config.ts`, like every other workspace. The workspace has a `typecheck` script and no `test` script, so `pnpm test` runs each file once.
@@ -598,6 +198,18 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
598
198
  - **Merge a hotfix branch into `main`, never rebase it.** A rebase rewrites the commit its release tag names.
599
199
  - **An agent deploys only after the owner says so in the same session.** It runs `pnpm deploy:production --dry-run` and reports first. The `saasaloy-deploy` skill is the procedure, and `docs/runbook-deploy.md` holds this project's own deploy steps.
600
200
 
201
+ ## Unattended work
202
+
203
+ An agent may build this project with no person at the keyboard. These rules apply only then, and they override "Ask First" where they say so.
204
+
205
+ - **The signal is `autonomy: afk`** in the YAML frontmatter of `docs/product-brief.md`. Only a person sets it: `saasaloy-setup` asks "Run the build unattended?" as its last question. With no such field, every skill keeps its attended path and asks.
206
+ - **A person supplies the two inputs**: the env values in `packages/env/.env`, and the brief, written through the attended `saasaloy-setup` interview. The person also runs `pnpm env:setup` before the first build. The brief is complete when all ten answers are filled (Name, Language, Audience, Problem, Current alternative, Differentiator, Proof, Tone, Pricing, Where "sign up" goes) and none is tagged `weak:`. With an incomplete brief, stop before the first module and list each missing or weak section under `## Blocked` in `docs/build-log.md`.
207
+ - **`pnpm check` is the gate.** Run `pnpm lint:fix` and `pnpm format`, then `pnpm check`. A stage is not done until it passes.
208
+ - **Commit once per stage on `build/mvp`.** Create the branch if it does not exist, and continue on it when it does. Commit through the Husky and commitlint hooks, never with `--no-verify`. Never push.
209
+ - **`docs/build-log.md` is the output.** Give each stage a `## <stage>` section with what it did and its commit hash. Put what stopped the run under `## Blocked`, and each step you leave for a person under `## Left for a human`. A new session reads the log first and continues from the last stage with a commit.
210
+ - **Allowed without asking:** database schema changes and migrations, new dependencies (exact-pinned), and new workspace packages (with a `clean` script).
211
+ - **Still forbidden:** a deploy (`pnpm deploy:production`, `wrangler deploy`), anything that spends money or creates a vendor account, editing a secret (`packages/env/.env`, `.env.prod`, a dashboard), deleting data outside the local dev database, and `git push`. Every other "Ask First" item stays forbidden too. Log the step under `## Left for a human` and carry on.
212
+
601
213
  ## Boundaries
602
214
 
603
215
  ### ✅ Always Do
@@ -608,19 +220,19 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
608
220
  - Give every new app or package a `clean` script backed by `rimraf` (see above)
609
221
  - Use TypeScript strict mode (no `any` without explicit reason)
610
222
  - Use workspace package names (`@repo/ui`, `@repo/config`, `@repo/tsconfig`) for imports
611
- - Put a value you would otherwise write twice in `@repo/config`, and a per-deployment value in
612
- `.env`/`.dev.vars` — see above
223
+ - Put a value you would otherwise write twice in `@repo/config`, and a per-deployment value in `packages/env/.env` — see above
613
224
 
614
225
  ### ⚠️ Ask First
615
226
 
227
+ Under `autonomy: afk`, "Unattended work" above decides these instead.
228
+
616
229
  - Adding new dependencies (especially to root `package.json`)
617
230
  - 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
618
231
  - Modifying Turborepo configuration (`turbo.json`)
619
232
  - Changing TypeScript strictness settings
620
233
  - Modifying the husky hooks (`.husky/`), `lint-staged.config.js`, or `commitlint.config.js`
621
234
  - Creating new workspace packages
622
- - Changing `oxlint.config.mjs`, `prettier.config.js`, or `stylelint.config.js` — including
623
- turning a rule off. Suppress the one occurrence with a comment that says why instead
235
+ - Changing `oxlint.config.mjs`, `prettier.config.js`, or `stylelint.config.js` — including turning a rule off. Suppress the one occurrence with a comment that says why instead
624
236
  - Database schema changes or migrations
625
237
  - CI/CD workflow modifications (`.github/workflows/`)
626
238
 
@@ -628,12 +240,10 @@ Testing mode: `off`. This project ships no module tests, and `saasaloy add` writ
628
240
 
629
241
  - Never use `npm` or `npx`, instead use `pnpm` & `pnpm dlx`
630
242
  - Never use `rm -rf` in a package script — it breaks on Windows; use `rimraf`
631
- - Commit secrets or API keys. `packages/env/.env` is gitignored; `packages/env/.env.example`
632
- is tracked and holds local defaults only
243
+ - Commit secrets or API keys. `packages/env/.env` is gitignored; `packages/env/.env.example` is tracked and holds local defaults only
633
244
  - Modify `node_modules/` or `pnpm-lock.yaml` manually (use `pnpm install`)
634
245
  - Remove or disable TypeScript strict mode
635
- - Remove or disable the lint-staged or commitlint hooks, or commit with `--no-verify`
636
- as a habit rather than an emergency
246
+ - Remove or disable the lint-staged or commitlint hooks, or commit with `--no-verify` as a habit rather than an emergency
637
247
  - Use `any` type without explicit `@ts-expect-error` or `@ts-ignore` with justification
638
248
  - Break the workspace structure (don't move packages outside `apps/*` or `packages/*`)
639
- - Commit without running type checks and linting
249
+ - Commit without running type checks and linting