[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79GGS6DPV7S0334CXS0961V":3,"skill-same:01M79GGS6DPV7S0334CXS0961V":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M79GGS6DPV7S0334CXS0961V","saasaloy-app",null,"Runbook for the app capability — the customer SPA at apps\u002Fapp on port 3002, where every signed-in user lands. Use when adding a product screen (a list or a form) to apps\u002Fapp, putting a screen in the sidebar, protecting a screen by session or by role, calling the api from the app with the typed hc client and TanStack Query, wiring the sign-in and sign-up routes, changing the app's canvas in app.css, debugging the :3002 → :4000 cookie and CORS flow (including COOKIE_DOMAIN and the workers.dev case), deploying the static bundle to Workers, or removing the module.","mimukit\u002Fsaasaloy","mimukit","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F11677026?v=4","01M79GFSERAQQ77QPQMC1N0Y6M","Mukitul Islam Mukit","01M79GFSFA4WMGEEBHA68N59WV",4,"MIT","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fmodules\u002Fapp\u002Fskills\u002Fsaasaloy-app\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: saasaloy-app\ndescription: Runbook for the app capability — the customer SPA at apps\u002Fapp on port 3002, where every signed-in user lands. Use when adding a product screen (a list or a form) to apps\u002Fapp, putting a screen in the sidebar, protecting a screen by session or by role, calling the api from the app with the typed hc client and TanStack Query, wiring the sign-in and sign-up routes, changing the app's canvas in app.css, debugging the :3002 → :4000 cookie and CORS flow (including COOKIE_DOMAIN and the workers.dev case), deploying the static bundle to Workers, or removing the module.\n---\n\n# app — the customer SPA\n\n`apps\u002Fapp` is the product a signed-in user sees: a TanStack Router + Vite SPA on port 3002, built on the `shell` frame with the web brand tokens, light first. `apps\u002Fweb` keeps the public pages; `apps\u002Fadmin` is the backoffice for the admin group. Any signed-in account may open `app`. See ADR 0047 for why the product lives here and not in `web` or `admin`.\n\n`saasaloy add app` installs `api`, `auth` and `shell` first, and needs no `admin`. It writes:\n\n| Path | What it is |\n|---|---|\n| `apps\u002Fapp\u002F` | the SPA: `vite.config.ts` (port 3002, `strictPort`), `wrangler.jsonc` (assets only), `src\u002Fenv.ts` |\n| `apps\u002Fapp\u002Fsrc\u002Froutes\u002F__root.tsx` | the one guard: no session sends the visitor to `\u002Fsign-in?redirect=…` |\n| `apps\u002Fapp\u002Fsrc\u002Froutes\u002Fsign-in.tsx`, `sign-up.tsx` | the `auth` module's `SignInCard` and `SignUpCard`, with the calls to the client instance |\n| `apps\u002Fapp\u002Fsrc\u002Froutes\u002Findex.tsx` | the home screen: a welcome card and an empty state that points at `saasaloy-feature` |\n| `apps\u002Fapp\u002Fsrc\u002Fcomponents\u002Fnav.ts` | the sidebar's nav data |\n| `apps\u002Fapp\u002Fsrc\u002Fcomponents\u002Fnav-counts.ts` | the sidebar's live counts, `NAV_COUNTS`, empty until a module adds a row |\n| `apps\u002Fapp\u002Fsrc\u002Flib\u002Fauth.ts`, `api.ts`, `redirect.ts` | the auth client and session cache, the typed api client, the safe-destination check |\n| `packages\u002Fui\u002Fsrc\u002Fstyles\u002Fapp.css` | the app's one stylesheet: `brand.css`, `shell.css`, two canvas values |\n\nIt also appends an `app` row to `packages\u002Fenv\u002Fsrc\u002Fservices.ts`, a deploy target and a smoke check to `packages\u002Ftooling\u002Fsrc\u002Ftargets.ts`, and a `PUBLIC_API_URL` entry for `app` to `packages\u002Fenv\u002F.env.example`. The `auth` module's blocks under `packages\u002Fui\u002Fsrc\u002Fblocks\u002Fauth\u002F` arrive in the same run: `auth` ships them with `when: { installed: [\"shell\"] }`, so the `shell` this module brings writes them.\n\n## Wire-up\n\nAfter `saasaloy add app`:\n\n1. Run `pnpm install`.\n2. Run `saasaloy env`, then `pnpm env:setup`. `apps\u002Fapp\u002F.env` gets `PUBLIC_API_URL` (`http:\u002F\u002Flocalhost:4000` in dev).\n3. Run `pnpm db:seed` if the database is empty, then `pnpm dev`. Open `http:\u002F\u002Flocalhost:3002` and sign in as `member@example.test` with the password `saasaloy-dev-password`, or create an account on `\u002Fsign-up`.\n4. **A project made before the `app` release** has no `http:\u002F\u002Flocalhost:3002` in `DEV_ORIGINS`, in `apps\u002Fapi\u002Fsrc\u002Findex.ts` and in `packages\u002Fauth\u002Fsrc\u002Fauth.ts`. Run `saasaloy update api auth` first, or every call from :3002 fails CORS (see Failure modes).\n5. **In production**, add the app's origin to `CORS_ORIGINS`, the one list the api CORS spine and `auth`'s `trustedOrigins` both read: `CORS_ORIGINS=https:\u002F\u002Fx.com,https:\u002F\u002Fapp.x.com,https:\u002F\u002Fadmin.x.com`. A set value replaces the localhost list, so name every frontend. Put the app and the api on sibling subdomains of one domain you own, and set `COOKIE_DOMAIN=.x.com` when the derived one does not match. Set `PUBLIC_API_URL` for the `app` service to the api's origin.\n\n## Add a screen\n\nDrop `src\u002Froutes\u002F\u003Cscreen>.tsx` with a `createFileRoute` whose id matches the file path. The file is a child of `src\u002Froutes\u002F__root.tsx`, so it gets the shell and the session guard with no work of its own. `@tanstack\u002Frouter-plugin` rewrites `src\u002FrouteTree.gen.ts` on the next `pnpm dev` or `pnpm build`, and `pnpm typecheck` runs `tsr generate` first, so a new route typechecks before Vite has run. Both read the generator options in `tsr.config.json`. Never edit `src\u002FrouteTree.gen.ts` by hand.\n\nThen put it in the sidebar: add a row to `NAV_AREAS` in `src\u002Fcomponents\u002Fnav.ts`. The `to` is checked against the route tree, so a typo fails `pnpm typecheck`. A row takes an optional `shortcut`, `G` then a letter written as `\"G P\"`; pick the letter by hand and keep it unique, because the tool repo's `commands.test.ts` fails on two rows with one shortcut. Every row becomes a \"Go to \u003Clabel>\" command in `src\u002Fcomponents\u002Fcommands.ts`, which `AppShell` declares next to sign out and the three theme choices. A screen declares its own with `useCommands(commands, { scope: \"route\", label })`. They do nothing until the `command` module is installed, which appends itself to `src\u002Fcomponents\u002Fshell-extensions.ts`.\n\n```ts\nitems: [\n  { to: \"\u002F\", label: \"Home\", icon: HouseIcon, shortcut: \"G H\" },\n  { to: \"\u002Fprojects\", label: \"Projects\", icon: FolderIcon, shortcut: \"G P\" },\n],\n```\n\n### Add a live count to a nav row\n\nA static `count` in `NAV_AREAS` is a number fixed at build time. A number that changes, such as how many notifications are unread, is a live count. `NAV_COUNTS` in `src\u002Fcomponents\u002Fnav-counts.ts` lists them, one `{ to, path }` per row. `to` is the row's `to` in `NAV_AREAS`. `path` is an api path that answers `{ count: number }` behind the user's session.\n\nA module adds its entry with a `const-array` patch keyed on `to`:\n\n```json\n{\n  \"file\": \"apps\u002Fapp\u002Fsrc\u002Fcomponents\u002Fnav-counts.ts\",\n  \"kind\": \"const-array\",\n  \"constName\": \"NAV_COUNTS\",\n  \"key\": \"to\",\n  \"entry\": { \"to\": \"\u002Fnotifications\", \"path\": \"\u002Fnotifications\u002Funread-count\" }\n}\n```\n\n`AppShell` runs one TanStack query per entry under the key `[\"nav-count\", to]` and passes the numbers to `ShellLayout` as `counts`. Each query fetches `PUBLIC_API_URL` plus `path` with the session cookie. It refetches every 60 s while the tab is visible, on every window focus (`refetchOnWindowFocus: \"always\"`, so a count fetched inside the 30 s `staleTime` still refetches), and on a `pageshow` with `persisted` set, which is a back-forward cache restore. A live count replaces the row's static `count`, and a live 0 hides the badge.\n\nA failed fetch (a network error, a non-OK answer or a body without a numeric `count`) throws, so TanStack Query keeps the last count it read. The badge never drops to 0 or disappears because of a failure. Before the first success the row keeps its static `count`. A screen whose action changes a count invalidates the key after the mutation, so the badge follows with no reload:\n\n```ts\nawait queryClient.invalidateQueries({ queryKey: [\"nav-count\", \"\u002Fnotifications\"] });\n```\n\nEvery screen renders inside the shell's page frame, which owns the width, the background and the gutter. Never set a page's own `max-w-*`, padding or background. Compose from the `shell` set only: `@repo\u002Fui\u002Fcomponents\u002Fshell\u002F*`, `@repo\u002Fui\u002Fblocks\u002Fshell\u002F*`, `@repo\u002Fui\u002Fcontainers\u002Fshell\u002F*`. The base `oxlint.config.mjs` makes a base primitive under `apps\u002Fapp\u002F**` a lint error. `saasaloy-shell` lists the blocks.\n\n### The list recipe\n\nA list reads the api through TanStack Query, and the loader fills the cache before the first paint. The route below assumes an api route `GET \u002Fprojects` that answers `{ projects, total }`; the `saasaloy-feature` skill builds one.\n\n```tsx\n\u002F\u002F src\u002Froutes\u002Fprojects.index.tsx  →  \u002Fprojects\nimport { queryOptions, useQuery } from \"@tanstack\u002Freact-query\";\nimport { Link, createFileRoute } from \"@tanstack\u002Freact-router\";\nimport { FolderIcon } from \"lucide-react\";\n\nimport { DataTable } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fdata-table\";\nimport type { DataTableColumn } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fdata-table\";\nimport { EmptyState } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fempty-state\";\nimport { PageHeader } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fpage-header\";\nimport { Button } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fbutton\";\nimport { StatusPill } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fstatus-pill\";\nimport { PageLayout } from \"@repo\u002Fui\u002Fcontainers\u002Fshell\u002Fpage-layout\";\n\nimport { api } from \"@app\u002Flib\u002Fapi\";\n\nconst projectsQuery = queryOptions({\n  queryKey: [\"projects\"],\n  queryFn: async () => {\n    const res = await api.projects.$get();\n    if (!res.ok) {\n      throw new Error(`The api answered ${res.status}.`);\n    }\n    return res.json();\n  },\n});\n\ntype Project = Awaited\u003CReturnType\u003CNonNullable\u003Ctypeof projectsQuery.queryFn>>>[\"projects\"][number];\n\nconst COLUMNS: readonly DataTableColumn\u003CProject>[] = [\n  { id: \"name\", header: \"Name\", value: (project) => project.name },\n  {\n    id: \"status\",\n    header: \"Status\",\n    value: (project) => project.status,\n    cell: (project) => \u003CStatusPill label={project.status} tone={project.status === \"active\" ? \"ok\" : \"neutral\"} \u002F>,\n  },\n  {\n    id: \"updated\",\n    header: \"Updated\",\n    value: (project) => project.updatedAt,\n    cell: (project) => new Date(project.updatedAt).toLocaleDateString(),\n  },\n];\n\nexport const Route = createFileRoute(\"\u002Fprojects\u002F\")({\n  loader: ({ context }) => context.queryClient.ensureQueryData(projectsQuery),\n  component: Projects,\n});\n\nfunction Projects() {\n  const { data } = useQuery(projectsQuery);\n  return (\n    \u003CPageLayout>\n      \u003CPageHeader\n        title=\"Projects\"\n        count={data?.total}\n        actions={\u003CButton render={\u003CLink to=\"\u002Fprojects\u002Fnew\" \u002F>}>New project\u003C\u002FButton>}\n      \u002F>\n      \u003CDataTable\n        caption=\"Projects\"\n        columns={COLUMNS}\n        rows={data?.projects ?? []}\n        rowId={(project) => project.id}\n        emptyState={\u003CEmptyState icon={FolderIcon} title=\"No projects yet\" description=\"Create the first one.\" \u002F>}\n      \u002F>\n    \u003C\u002FPageLayout>\n  );\n}\n```\n\n`value` is what a column sorts on and shows when it has no `cell`. Read `data` through `?.` even after the loader ran: `useQuery` types it as `T | undefined`, and the repo compiles with `strict`. Check `DataTableColumn`, `PageHeader` and `StatusPill` against their files under `packages\u002Fui\u002Fsrc\u002F` when a prop does not type-check; the shell owns them.\n\n### The form recipe\n\nA form posts through a TanStack Query mutation, then refreshes the list and navigates back. The server validates again; the form's checks are for the person typing.\n\n```tsx\n\u002F\u002F src\u002Froutes\u002Fprojects.new.tsx  →  \u002Fprojects\u002Fnew\nimport { useMutation, useQueryClient } from \"@tanstack\u002Freact-query\";\nimport { createFileRoute, useNavigate } from \"@tanstack\u002Freact-router\";\nimport type { SubmitEvent } from \"react\";\n\nimport { PageHeader } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fpage-header\";\nimport { Button } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fbutton\";\nimport { Field, FieldError, FieldLabel } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Ffield\";\nimport { Form } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fform\";\nimport { Input } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Finput\";\nimport { Textarea } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Ftextarea\";\nimport { toastManager } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Ftoast\";\nimport { PageBody } from \"@repo\u002Fui\u002Fcontainers\u002Fshell\u002Fpage-body\";\n\nimport { api } from \"@app\u002Flib\u002Fapi\";\n\nexport const Route = createFileRoute(\"\u002Fprojects\u002Fnew\")({ component: NewProject });\n\nfunction NewProject() {\n  const navigate = useNavigate();\n  const queryClient = useQueryClient();\n\n  const create = useMutation({\n    mutationFn: async (input: { name: string; description: string }) => {\n      const res = await api.projects.$post({ json: input });\n      if (!res.ok) {\n      throw new Error(`The api answered ${res.status}.`);\n    }\n      return res.json();\n    },\n    onSuccess: async () => {\n      await queryClient.invalidateQueries({ queryKey: [\"projects\"] });\n      toastManager.add({ type: \"success\", title: \"Project created\" });\n      await navigate({ to: \"\u002Fprojects\" });\n    },\n    onError: (error) => {\n      toastManager.add({ type: \"error\", title: \"The project was not created\", description: error.message });\n    },\n  });\n\n  function submit(event: SubmitEvent\u003CHTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const name = data.get(\"name\");\n    const description = data.get(\"description\");\n    create.mutate({\n      name: typeof name === \"string\" ? name : \"\",\n      description: typeof description === \"string\" ? description : \"\",\n    });\n  }\n\n  return (\n    \u003C>\n      \u003CPageHeader title=\"New project\" \u002F>\n      \u003CPageBody>\n        \u003CForm onSubmit={submit} className=\"flex max-w-xl flex-col gap-4\">\n          \u003CField>\n            \u003CFieldLabel>Name\u003C\u002FFieldLabel>\n            \u003CInput name=\"name\" required \u002F>\n            \u003CFieldError \u002F>\n          \u003C\u002FField>\n          \u003CField>\n            \u003CFieldLabel>Description\u003C\u002FFieldLabel>\n            \u003CTextarea name=\"description\" \u002F>\n          \u003C\u002FField>\n          \u003CButton type=\"submit\" loading={create.isPending} className=\"self-start\">\n            Create project\n          \u003C\u002FButton>\n        \u003C\u002FForm>\n      \u003C\u002FPageBody>\n    \u003C\u002F>\n  );\n}\n```\n\nA form's `max-w-*` is the field column's width inside the page, not the page's width, so it does not fight the frame.\n\n## Protect a screen\n\n**The session.** Every route under `__root.tsx` already needs one. The guard reads `loadSession()` once per page load; a visitor with none goes to `\u002Fsign-in?redirect=\u003Cthe page>`, and the sign-in screen sends them back after a sign-in. `src\u002Flib\u002Fredirect.ts` keeps that `redirect` on this origin and on a route this app has, or falls back to `\u002F`.\n\n**A role.** Ask the api, not the session object. The client session this app holds is not typed with `role`: `adminClient()` rides on the admin client only (see `saasaloy-auth`). So a role-gated screen calls a route the api guards with `requireRole`, in its `beforeLoad`, and sends the visitor home on a `403`:\n\n```tsx\nexport const Route = createFileRoute(\"\u002Fsubscription\")({\n  beforeLoad: async () => {\n    const res = await api.subscription.$get();\n    if (res.status === 403) {\n      throw redirect({ to: \"\u002F\" });\n    }\n  },\n  component: Subscription,\n});\n```\n\nAn organization role from the `teams` module is a different question with its own helper, `can()` from `@repo\u002Fauth\u002Fpermission-rules`; `saasaloy-teams` covers it.\n\n**The api is the real gate.** Hiding a screen protects nothing. Every api route the screen calls checks the session or the role itself, with `requireSession(c)` or `requireRole(c, …)` from `@repo\u002Fauth\u002Fserver` (see `saasaloy-auth`). A request from `app` carries the client session, because `src\u002Flib\u002Fapi.ts` sends no `x-auth-audience` header.\n\n## Call the api\n\n`src\u002Flib\u002Fapi.ts` exports `api`, an `hc\u003CAppType>` client: `api.\u003Croute>.$get()` returns the route's own response type, with no hand-written fetch. It sends the session cookie (`credentials: \"include\"`) to `PUBLIC_API_URL`. Wrap each call in `queryOptions` for a read and `useMutation` for a write, as the recipes above do.\n\nAn api route a screen calls is the `api` module's business: add it under `apps\u002Fapi\u002Fsrc\u002Froutes\u002F` and gate it there. `saasaloy-api` has the route recipe, and `saasaloy-feature` builds a table, a route and a screen together.\n\n## Theme and stylesheet\n\n`src\u002Fmain.tsx` imports `@repo\u002Fui\u002Fstyles\u002Fapp.css`, the app's one Tailwind entrypoint. It imports `brand.css` (the web brand tokens, which import `globals.css`), then `shell.css` (the shell primitives' `@source` line, status tokens and motion), then sets two canvas values per theme: `--sidebar` and `--sidebar-accent`. Those are the round 2 values the approved mockup settled on, so the white panel stands off the canvas. A shadcn preset applied to `brand.css` repaints `app` and the landing page together; `admin` keeps its own theme in `admin.css`.\n\nThe app starts light on a first visit and keeps the visitor's choice after that, `system` included. The theme menu sits in the shell's account menu.\n\n## Ports and CORS\n\n| Service | Port |\n|---|---|\n| `apps\u002Fweb` | 3000 |\n| `apps\u002Fadmin` | 3001 |\n| `apps\u002Fapp` (this app) | **3002**, with `strictPort` |\n| `email-react` preview | 3003 |\n| `apps\u002Fapi` | 4000 |\n\n`http:\u002F\u002Flocalhost:3002` is in the api's `DEV_ORIGINS` and in `auth`'s `trustedOrigins` fallback. `strictPort` makes a busy port fail at once rather than move to 3003, where nothing allows it. Cookies ignore the port, so the app at :3002 and the api at :4000 share the `localhost` jar, and the client cookie (`client.session_token`) never replaces the admin app's `admin.session_token`.\n\n## Deploy\n\n`apps\u002Fapp\u002Fwrangler.jsonc` serves `dist\u002F` as Workers static assets with `not_found_handling: \"single-page-application\"`, so a hard reload on `\u002Fprojects` gets `index.html` and the router takes over. `pnpm deploy:production` deploys it after the api and admin (`order: 25`) through the `deploy` script, `env-deploy app`, and smoke-checks `\u002F` when the Worker has a custom domain route. Set the production `PUBLIC_API_URL` for `app` and add the app's origin to `CORS_ORIGINS` first (step 5 of Wire-up). `saasaloy-deploy` has the full run.\n\n## Removing the module\n\n`saasaloy remove app` deletes `apps\u002Fapp`, `app.css` and the rows in `services.ts` and `targets.ts`, and leaves `shell` and `auth` installed. Take the app's origin out of `CORS_ORIGINS`, and run `pnpm install` so the lockfile drops the workspace. `saasaloy remove shell` then removes the auth blocks too, unless `admin` still needs `shell`.\n\n## Failure modes\n\n- **The browser console says the request was blocked by CORS, or sign-in answers `403` with `INVALID_ORIGIN`.** The origin is not in the list. In dev, the project predates the `app` release: run `saasaloy update api auth`, so `http:\u002F\u002Flocalhost:3002` joins `DEV_ORIGINS`. In production, add the app's origin to `CORS_ORIGINS` and redeploy the api; a set `CORS_ORIGINS` replaces the localhost list, so it has to name every frontend.\n- **Sign-in succeeds, then the guard sends the visitor straight back to `\u002Fsign-in`.** The browser did not keep the session cookie, or does not send it to the api. The app and the api must be same-site: sibling subdomains of one domain you own, such as `app.x.com` and `api.x.com`. Set `COOKIE_DOMAIN=.x.com` when the domain derived from `BETTER_AUTH_URL` is not the shared parent.\n- **The same loop on `*.workers.dev`.** `workers.dev` is on the public suffix list, so `app.\u003Caccount>.workers.dev` and `api.\u003Caccount>.workers.dev` are two different sites, and no `COOKIE_DOMAIN` can join them. Browsers treat the session cookie as third-party and drop it. Put both Workers on custom domains of one zone.\n- **The build fails naming `PUBLIC_API_URL`.** `apps\u002Fapp\u002F.env` lacks it. Run `saasaloy env` and `pnpm env:setup`; for a deploy, set it for the `app` service.\n- **`pnpm dev` fails with \"Port 3002 is already in use\".** Another process holds it, often an older `email-react` preview from before it moved to 3003. Stop that process; do not change the port, or CORS breaks.\n- **The pages render with no styles.** `src\u002Fmain.tsx` no longer imports `@repo\u002Fui\u002Fstyles\u002Fapp.css`, or `app.css` lost its `shell.css` import. Restore both.\n- **The sign-in card renders unstyled.** The blocks are missing: `packages\u002Fui\u002Fsrc\u002Fblocks\u002Fauth\u002F` is empty because `shell` was installed before `auth`'s blocks existed. Run `saasaloy update auth`.\n\n## Next\n\nRun `saasaloy-feature` to build the first product feature end to end: the table, the api route, the screen here, and its test.\n","# app — the customer SPA\n\n`apps\u002Fapp` is the product a signed-in user sees: a TanStack Router + Vite SPA on port 3002, built on the `shell` frame with the web brand tokens, light first. `apps\u002Fweb` keeps the public pages; `apps\u002Fadmin` is the backoffice for the admin group. Any signed-in account may open `app`. See ADR 0047 for why the product lives here and not in `web` or `admin`.\n\n`saasaloy add app` installs `api`, `auth` and `shell` first, and needs no `admin`. It writes:\n\n| Path | What it is |\n|---|---|\n| `apps\u002Fapp\u002F` | the SPA: `vite.config.ts` (port 3002, `strictPort`), `wrangler.jsonc` (assets only), `src\u002Fenv.ts` |\n| `apps\u002Fapp\u002Fsrc\u002Froutes\u002F__root.tsx` | the one guard: no session sends the visitor to `\u002Fsign-in?redirect=…` |\n| `apps\u002Fapp\u002Fsrc\u002Froutes\u002Fsign-in.tsx`, `sign-up.tsx` | the `auth` module's `SignInCard` and `SignUpCard`, with the calls to the client instance |\n| `apps\u002Fapp\u002Fsrc\u002Froutes\u002Findex.tsx` | the home screen: a welcome card and an empty state that points at `saasaloy-feature` |\n| `apps\u002Fapp\u002Fsrc\u002Fcomponents\u002Fnav.ts` | the sidebar's nav data |\n| `apps\u002Fapp\u002Fsrc\u002Fcomponents\u002Fnav-counts.ts` | the sidebar's live counts, `NAV_COUNTS`, empty until a module adds a row |\n| `apps\u002Fapp\u002Fsrc\u002Flib\u002Fauth.ts`, `api.ts`, `redirect.ts` | the auth client and session cache, the typed api client, the safe-destination check |\n| `packages\u002Fui\u002Fsrc\u002Fstyles\u002Fapp.css` | the app's one stylesheet: `brand.css`, `shell.css`, two canvas values |\n\nIt also appends an `app` row to `packages\u002Fenv\u002Fsrc\u002Fservices.ts`, a deploy target and a smoke check to `packages\u002Ftooling\u002Fsrc\u002Ftargets.ts`, and a `PUBLIC_API_URL` entry for `app` to `packages\u002Fenv\u002F.env.example`. The `auth` module's blocks under `packages\u002Fui\u002Fsrc\u002Fblocks\u002Fauth\u002F` arrive in the same run: `auth` ships them with `when: { installed: [\"shell\"] }`, so the `shell` this module brings writes them.\n\n## Wire-up\n\nAfter `saasaloy add app`:\n\n1. Run `pnpm install`.\n2. Run `saasaloy env`, then `pnpm env:setup`. `apps\u002Fapp\u002F.env` gets `PUBLIC_API_URL` (`http:\u002F\u002Flocalhost:4000` in dev).\n3. Run `pnpm db:seed` if the database is empty, then `pnpm dev`. Open `http:\u002F\u002Flocalhost:3002` and sign in as `member@example.test` with the password `saasaloy-dev-password`, or create an account on `\u002Fsign-up`.\n4. **A project made before the `app` release** has no `http:\u002F\u002Flocalhost:3002` in `DEV_ORIGINS`, in `apps\u002Fapi\u002Fsrc\u002Findex.ts` and in `packages\u002Fauth\u002Fsrc\u002Fauth.ts`. Run `saasaloy update api auth` first, or every call from :3002 fails CORS (see Failure modes).\n5. **In production**, add the app's origin to `CORS_ORIGINS`, the one list the api CORS spine and `auth`'s `trustedOrigins` both read: `CORS_ORIGINS=https:\u002F\u002Fx.com,https:\u002F\u002Fapp.x.com,https:\u002F\u002Fadmin.x.com`. A set value replaces the localhost list, so name every frontend. Put the app and the api on sibling subdomains of one domain you own, and set `COOKIE_DOMAIN=.x.com` when the derived one does not match. Set `PUBLIC_API_URL` for the `app` service to the api's origin.\n\n## Add a screen\n\nDrop `src\u002Froutes\u002F\u003Cscreen>.tsx` with a `createFileRoute` whose id matches the file path. The file is a child of `src\u002Froutes\u002F__root.tsx`, so it gets the shell and the session guard with no work of its own. `@tanstack\u002Frouter-plugin` rewrites `src\u002FrouteTree.gen.ts` on the next `pnpm dev` or `pnpm build`, and `pnpm typecheck` runs `tsr generate` first, so a new route typechecks before Vite has run. Both read the generator options in `tsr.config.json`. Never edit `src\u002FrouteTree.gen.ts` by hand.\n\nThen put it in the sidebar: add a row to `NAV_AREAS` in `src\u002Fcomponents\u002Fnav.ts`. The `to` is checked against the route tree, so a typo fails `pnpm typecheck`. A row takes an optional `shortcut`, `G` then a letter written as `\"G P\"`; pick the letter by hand and keep it unique, because the tool repo's `commands.test.ts` fails on two rows with one shortcut. Every row becomes a \"Go to \u003Clabel>\" command in `src\u002Fcomponents\u002Fcommands.ts`, which `AppShell` declares next to sign out and the three theme choices. A screen declares its own with `useCommands(commands, { scope: \"route\", label })`. They do nothing until the `command` module is installed, which appends itself to `src\u002Fcomponents\u002Fshell-extensions.ts`.\n\n```ts\nitems: [\n  { to: \"\u002F\", label: \"Home\", icon: HouseIcon, shortcut: \"G H\" },\n  { to: \"\u002Fprojects\", label: \"Projects\", icon: FolderIcon, shortcut: \"G P\" },\n],\n```\n\n### Add a live count to a nav row\n\nA static `count` in `NAV_AREAS` is a number fixed at build time. A number that changes, such as how many notifications are unread, is a live count. `NAV_COUNTS` in `src\u002Fcomponents\u002Fnav-counts.ts` lists them, one `{ to, path }` per row. `to` is the row's `to` in `NAV_AREAS`. `path` is an api path that answers `{ count: number }` behind the user's session.\n\nA module adds its entry with a `const-array` patch keyed on `to`:\n\n```json\n{\n  \"file\": \"apps\u002Fapp\u002Fsrc\u002Fcomponents\u002Fnav-counts.ts\",\n  \"kind\": \"const-array\",\n  \"constName\": \"NAV_COUNTS\",\n  \"key\": \"to\",\n  \"entry\": { \"to\": \"\u002Fnotifications\", \"path\": \"\u002Fnotifications\u002Funread-count\" }\n}\n```\n\n`AppShell` runs one TanStack query per entry under the key `[\"nav-count\", to]` and passes the numbers to `ShellLayout` as `counts`. Each query fetches `PUBLIC_API_URL` plus `path` with the session cookie. It refetches every 60 s while the tab is visible, on every window focus (`refetchOnWindowFocus: \"always\"`, so a count fetched inside the 30 s `staleTime` still refetches), and on a `pageshow` with `persisted` set, which is a back-forward cache restore. A live count replaces the row's static `count`, and a live 0 hides the badge.\n\nA failed fetch (a network error, a non-OK answer or a body without a numeric `count`) throws, so TanStack Query keeps the last count it read. The badge never drops to 0 or disappears because of a failure. Before the first success the row keeps its static `count`. A screen whose action changes a count invalidates the key after the mutation, so the badge follows with no reload:\n\n```ts\nawait queryClient.invalidateQueries({ queryKey: [\"nav-count\", \"\u002Fnotifications\"] });\n```\n\nEvery screen renders inside the shell's page frame, which owns the width, the background and the gutter. Never set a page's own `max-w-*`, padding or background. Compose from the `shell` set only: `@repo\u002Fui\u002Fcomponents\u002Fshell\u002F*`, `@repo\u002Fui\u002Fblocks\u002Fshell\u002F*`, `@repo\u002Fui\u002Fcontainers\u002Fshell\u002F*`. The base `oxlint.config.mjs` makes a base primitive under `apps\u002Fapp\u002F**` a lint error. `saasaloy-shell` lists the blocks.\n\n### The list recipe\n\nA list reads the api through TanStack Query, and the loader fills the cache before the first paint. The route below assumes an api route `GET \u002Fprojects` that answers `{ projects, total }`; the `saasaloy-feature` skill builds one.\n\n```tsx\n\u002F\u002F src\u002Froutes\u002Fprojects.index.tsx  →  \u002Fprojects\nimport { queryOptions, useQuery } from \"@tanstack\u002Freact-query\";\nimport { Link, createFileRoute } from \"@tanstack\u002Freact-router\";\nimport { FolderIcon } from \"lucide-react\";\n\nimport { DataTable } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fdata-table\";\nimport type { DataTableColumn } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fdata-table\";\nimport { EmptyState } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fempty-state\";\nimport { PageHeader } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fpage-header\";\nimport { Button } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fbutton\";\nimport { StatusPill } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fstatus-pill\";\nimport { PageLayout } from \"@repo\u002Fui\u002Fcontainers\u002Fshell\u002Fpage-layout\";\n\nimport { api } from \"@app\u002Flib\u002Fapi\";\n\nconst projectsQuery = queryOptions({\n  queryKey: [\"projects\"],\n  queryFn: async () => {\n    const res = await api.projects.$get();\n    if (!res.ok) {\n      throw new Error(`The api answered ${res.status}.`);\n    }\n    return res.json();\n  },\n});\n\ntype Project = Awaited\u003CReturnType\u003CNonNullable\u003Ctypeof projectsQuery.queryFn>>>[\"projects\"][number];\n\nconst COLUMNS: readonly DataTableColumn\u003CProject>[] = [\n  { id: \"name\", header: \"Name\", value: (project) => project.name },\n  {\n    id: \"status\",\n    header: \"Status\",\n    value: (project) => project.status,\n    cell: (project) => \u003CStatusPill label={project.status} tone={project.status === \"active\" ? \"ok\" : \"neutral\"} \u002F>,\n  },\n  {\n    id: \"updated\",\n    header: \"Updated\",\n    value: (project) => project.updatedAt,\n    cell: (project) => new Date(project.updatedAt).toLocaleDateString(),\n  },\n];\n\nexport const Route = createFileRoute(\"\u002Fprojects\u002F\")({\n  loader: ({ context }) => context.queryClient.ensureQueryData(projectsQuery),\n  component: Projects,\n});\n\nfunction Projects() {\n  const { data } = useQuery(projectsQuery);\n  return (\n    \u003CPageLayout>\n      \u003CPageHeader\n        title=\"Projects\"\n        count={data?.total}\n        actions={\u003CButton render={\u003CLink to=\"\u002Fprojects\u002Fnew\" \u002F>}>New project\u003C\u002FButton>}\n      \u002F>\n      \u003CDataTable\n        caption=\"Projects\"\n        columns={COLUMNS}\n        rows={data?.projects ?? []}\n        rowId={(project) => project.id}\n        emptyState={\u003CEmptyState icon={FolderIcon} title=\"No projects yet\" description=\"Create the first one.\" \u002F>}\n      \u002F>\n    \u003C\u002FPageLayout>\n  );\n}\n```\n\n`value` is what a column sorts on and shows when it has no `cell`. Read `data` through `?.` even after the loader ran: `useQuery` types it as `T | undefined`, and the repo compiles with `strict`. Check `DataTableColumn`, `PageHeader` and `StatusPill` against their files under `packages\u002Fui\u002Fsrc\u002F` when a prop does not type-check; the shell owns them.\n\n### The form recipe\n\nA form posts through a TanStack Query mutation, then refreshes the list and navigates back. The server validates again; the form's checks are for the person typing.\n\n```tsx\n\u002F\u002F src\u002Froutes\u002Fprojects.new.tsx  →  \u002Fprojects\u002Fnew\nimport { useMutation, useQueryClient } from \"@tanstack\u002Freact-query\";\nimport { createFileRoute, useNavigate } from \"@tanstack\u002Freact-router\";\nimport type { SubmitEvent } from \"react\";\n\nimport { PageHeader } from \"@repo\u002Fui\u002Fblocks\u002Fshell\u002Fpage-header\";\nimport { Button } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fbutton\";\nimport { Field, FieldError, FieldLabel } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Ffield\";\nimport { Form } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Fform\";\nimport { Input } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Finput\";\nimport { Textarea } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Ftextarea\";\nimport { toastManager } from \"@repo\u002Fui\u002Fcomponents\u002Fshell\u002Ftoast\";\nimport { PageBody } from \"@repo\u002Fui\u002Fcontainers\u002Fshell\u002Fpage-body\";\n\nimport { api } from \"@app\u002Flib\u002Fapi\";\n\nexport const Route = createFileRoute(\"\u002Fprojects\u002Fnew\")({ component: NewProject });\n\nfunction NewProject() {\n  const navigate = useNavigate();\n  const queryClient = useQueryClient();\n\n  const create = useMutation({\n    mutationFn: async (input: { name: string; description: string }) => {\n      const res = await api.projects.$post({ json: input });\n      if (!res.ok) {\n      throw new Error(`The api answered ${res.status}.`);\n    }\n      return res.json();\n    },\n    onSuccess: async () => {\n      await queryClient.invalidateQueries({ queryKey: [\"projects\"] });\n      toastManager.add({ type: \"success\", title: \"Project created\" });\n      await navigate({ to: \"\u002Fprojects\" });\n    },\n    onError: (error) => {\n      toastManager.add({ type: \"error\", title: \"The project was not created\", description: error.message });\n    },\n  });\n\n  function submit(event: SubmitEvent\u003CHTMLFormElement>) {\n    event.preventDefault();\n    const data = new FormData(event.currentTarget);\n    const name = data.get(\"name\");\n    const description = data.get(\"description\");\n    create.mutate({\n      name: typeof name === \"string\" ? name : \"\",\n      description: typeof description === \"string\" ? description : \"\",\n    });\n  }\n\n  return (\n    \u003C>\n      \u003CPageHeader title=\"New project\" \u002F>\n      \u003CPageBody>\n        \u003CForm onSubmit={submit} className=\"flex max-w-xl flex-col gap-4\">\n          \u003CField>\n            \u003CFieldLabel>Name\u003C\u002FFieldLabel>\n            \u003CInput name=\"name\" required \u002F>\n            \u003CFieldError \u002F>\n          \u003C\u002FField>\n          \u003CField>\n            \u003CFieldLabel>Description\u003C\u002FFieldLabel>\n            \u003CTextarea name=\"description\" \u002F>\n          \u003C\u002FField>\n          \u003CButton type=\"submit\" loading={create.isPending} className=\"self-start\">\n            Create project\n          \u003C\u002FButton>\n        \u003C\u002FForm>\n      \u003C\u002FPageBody>\n    \u003C\u002F>\n  );\n}\n```\n\nA form's `max-w-*` is the field column's width inside the page, not the page's width, so it does not fight the frame.\n\n## Protect a screen\n\n**The session.** Every route under `__root.tsx` already needs one. The guard reads `loadSession()` once per page load; a visitor with none goes to `\u002Fsign-in?redirect=\u003Cthe page>`, and the sign-in screen sends them back after a sign-in. `src\u002Flib\u002Fredirect.ts` keeps that `redirect` on this origin and on a route this app has, or falls back to `\u002F`.\n\n**A role.** Ask the api, not the session object. The client session this app holds is not typed with `role`: `adminClient()` rides on the admin client only (see `saasaloy-auth`). So a role-gated screen calls a route the api guards with `requireRole`, in its `beforeLoad`, and sends the visitor home on a `403`:\n\n```tsx\nexport const Route = createFileRoute(\"\u002Fsubscription\")({\n  beforeLoad: async () => {\n    const res = await api.subscription.$get();\n    if (res.status === 403) {\n      throw redirect({ to: \"\u002F\" });\n    }\n  },\n  component: Subscription,\n});\n```\n\nAn organization role from the `teams` module is a different question with its own helper, `can()` from `@repo\u002Fauth\u002Fpermission-rules`; `saasaloy-teams` covers it.\n\n**The api is the real gate.** Hiding a screen protects nothing. Every api route the screen calls checks the session or the role itself, with `requireSession(c)` or `requireRole(c, …)` from `@repo\u002Fauth\u002Fserver` (see `saasaloy-auth`). A request from `app` carries the client session, because `src\u002Flib\u002Fapi.ts` sends no `x-auth-audience` header.\n\n## Call the api\n\n`src\u002Flib\u002Fapi.ts` exports `api`, an `hc\u003CAppType>` client: `api.\u003Croute>.$get()` returns the route's own response type, with no hand-written fetch. It sends the session cookie (`credentials: \"include\"`) to `PUBLIC_API_URL`. Wrap each call in `queryOptions` for a read and `useMutation` for a write, as the recipes above do.\n\nAn api route a screen calls is the `api` module's business: add it under `apps\u002Fapi\u002Fsrc\u002Froutes\u002F` and gate it there. `saasaloy-api` has the route recipe, and `saasaloy-feature` builds a table, a route and a screen together.\n\n## Theme and stylesheet\n\n`src\u002Fmain.tsx` imports `@repo\u002Fui\u002Fstyles\u002Fapp.css`, the app's one Tailwind entrypoint. It imports `brand.css` (the web brand tokens, which import `globals.css`), then `shell.css` (the shell primitives' `@source` line, status tokens and motion), then sets two canvas values per theme: `--sidebar` and `--sidebar-accent`. Those are the round 2 values the approved mockup settled on, so the white panel stands off the canvas. A shadcn preset applied to `brand.css` repaints `app` and the landing page together; `admin` keeps its own theme in `admin.css`.\n\nThe app starts light on a first visit and keeps the visitor's choice after that, `system` included. The theme menu sits in the shell's account menu.\n\n## Ports and CORS\n\n| Service | Port |\n|---|---|\n| `apps\u002Fweb` | 3000 |\n| `apps\u002Fadmin` | 3001 |\n| `apps\u002Fapp` (this app) | **3002**, with `strictPort` |\n| `email-react` preview | 3003 |\n| `apps\u002Fapi` | 4000 |\n\n`http:\u002F\u002Flocalhost:3002` is in the api's `DEV_ORIGINS` and in `auth`'s `trustedOrigins` fallback. `strictPort` makes a busy port fail at once rather than move to 3003, where nothing allows it. Cookies ignore the port, so the app at :3002 and the api at :4000 share the `localhost` jar, and the client cookie (`client.session_token`) never replaces the admin app's `admin.session_token`.\n\n## Deploy\n\n`apps\u002Fapp\u002Fwrangler.jsonc` serves `dist\u002F` as Workers static assets with `not_found_handling: \"single-page-application\"`, so a hard reload on `\u002Fprojects` gets `index.html` and the router takes over. `pnpm deploy:production` deploys it after the api and admin (`order: 25`) through the `deploy` script, `env-deploy app`, and smoke-checks `\u002F` when the Worker has a custom domain route. Set the production `PUBLIC_API_URL` for `app` and add the app's origin to `CORS_ORIGINS` first (step 5 of Wire-up). `saasaloy-deploy` has the full run.\n\n## Removing the module\n\n`saasaloy remove app` deletes `apps\u002Fapp`, `app.css` and the rows in `services.ts` and `targets.ts`, and leaves `shell` and `auth` installed. Take the app's origin out of `CORS_ORIGINS`, and run `pnpm install` so the lockfile drops the workspace. `saasaloy remove shell` then removes the auth blocks too, unless `admin` still needs `shell`.\n\n## Failure modes\n\n- **The browser console says the request was blocked by CORS, or sign-in answers `403` with `INVALID_ORIGIN`.** The origin is not in the list. In dev, the project predates the `app` release: run `saasaloy update api auth`, so `http:\u002F\u002Flocalhost:3002` joins `DEV_ORIGINS`. In production, add the app's origin to `CORS_ORIGINS` and redeploy the api; a set `CORS_ORIGINS` replaces the localhost list, so it has to name every frontend.\n- **Sign-in succeeds, then the guard sends the visitor straight back to `\u002Fsign-in`.** The browser did not keep the session cookie, or does not send it to the api. The app and the api must be same-site: sibling subdomains of one domain you own, such as `app.x.com` and `api.x.com`. Set `COOKIE_DOMAIN=.x.com` when the domain derived from `BETTER_AUTH_URL` is not the shared parent.\n- **The same loop on `*.workers.dev`.** `workers.dev` is on the public suffix list, so `app.\u003Caccount>.workers.dev` and `api.\u003Caccount>.workers.dev` are two different sites, and no `COOKIE_DOMAIN` can join them. Browsers treat the session cookie as third-party and drop it. Put both Workers on custom domains of one zone.\n- **The build fails naming `PUBLIC_API_URL`.** `apps\u002Fapp\u002F.env` lacks it. Run `saasaloy env` and `pnpm env:setup`; for a deploy, set it for the `app` service.\n- **`pnpm dev` fails with \"Port 3002 is already in use\".** Another process holds it, often an older `email-react` preview from before it moved to 3003. Stop that process; do not change the port, or CORS breaks.\n- **The pages render with no styles.** `src\u002Fmain.tsx` no longer imports `@repo\u002Fui\u002Fstyles\u002Fapp.css`, or `app.css` lost its `shell.css` import. Restore both.\n- **The sign-in card renders unstyled.** The blocks are missing: `packages\u002Fui\u002Fsrc\u002Fblocks\u002Fauth\u002F` is empty because `shell` was installed before `auth`'s blocks existed. Run `saasaloy update auth`.\n\n## Next\n\nRun `saasaloy-feature` to build the first product feature end to end: the table, the api route, the screen here, and its test.\n",{"name":5,"description":7},"main","5ecf3d110b216ef678e06a1630f6b63a8e730bb5","modules\u002Fapp\u002Fskills\u002Fsaasaloy-app",0,"https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy","https:\u002F\u002Fsaasaloy.com","https:\u002F\u002Fgithub.com\u002Fmimukit","https:\u002F\u002Fmimukit.com","Senior Software Engineer · 9+ yrs Fullstack (TS\u002FNode\u002FReact) · AI integrations, distributed systems · Building @saasaloy & @codealoy · Bangladesh 🇧🇩 \u002F Remote","2026-11-13 20:39:28",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add mimukit\u002Fsaasaloy --skill saasaloy-app",{"tool":40,"command":41},"bunx","bunx skills add mimukit\u002Fsaasaloy --skill saasaloy-app",{"tool":43,"command":44},"pnpm","pnpm dlx skills add mimukit\u002Fsaasaloy --skill saasaloy-app","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fmodules\u002Fapp\u002Fskills\u002Fsaasaloy-app\u002FSKILL.md",true,[],[49,56,63,70,77,83],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7BE75C34XHSPVJNQC8FY4Q0","saasaloy-subscription","Runbook for the subscription capability — provider-agnostic subscriptions in packages\u002Fsubscription, with a plan file, a projection table, a billable-subject file, plan entitlements and per-provider modules. Use when adding a plan, adding a plan feature or a numeric limit, gating an API route with requireFeature or requireWithinLimit, reading the 402 it returns, working out why a subject resolves to the free plan, wiring a checkout or portal route, reading a SubscriptionError, choosing or switching SUBSCRIPTION_PROVIDER, registering a webhook in the vendor's dashboard, writing a third subscription provider, or upgrading a project that still has `billing` installed.","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fmodules\u002Fsubscription\u002Fskills\u002Fsaasaloy-subscription\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7BE68MJ8H47JZKTBDFYR6JD","saasaloy-notification","Runbook for the notification module, in-app notifications for apps\u002Fapp. It owns the notifications and notification_opt_outs tables, notify() in apps\u002Fapi\u002Fsrc\u002Flib\u002Fnotify.ts, the \u002Fnotifications api routes, the bell in the app header, the sidebar badge, the \u002Fnotifications page with Inbox and Preferences tabs, the notification config section, and the daily prune. Use when sending a notification from an api route, adding or changing a category, changing retention, debugging a badge or bell count that does not move, or removing the module.","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fmodules\u002Fnotification\u002Fskills\u002Fsaasaloy-notification\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7BE53PDQV0YDPG8RNVGTPEQ","saasaloy-cms","Runbook for the cms module, the in-house CMS behind apps\u002Fadmin. Covers code-defined collections, the Tiptap editor, drafts, revisions and redirects, the publish-time renderer, the public blog on apps\u002Fweb and its 60-second cache. Use when adding a collection or a field, rendering a stored body, reusing the editor, renderer or media field from another module, moving the blog to another path, re-rendering live posts after a renderer upgrade or a STORAGE_PUBLIC_URL change, or working out why a published post is not live yet.","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fmodules\u002Fcms\u002Fskills\u002Fsaasaloy-cms\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M79GQ03M63V5EKSST92B3S5X","saasaloy-beta","The beta module's own procedure.","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fpackages\u002Fcli\u002Ftest\u002Ffixtures\u002Fregistry-clean\u002Fbeta\u002Fsaasaloy-beta\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M79GPXV3K8YF3M4VA0KGVE0B","helper","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fpackages\u002Fcli\u002Ftest\u002Ffixtures\u002Fregistry-broken\u002Fbad-skill\u002Fhelper\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M79GPR8EVS1YX0W8X33Q9YD8","saasaloy-update","Runbook for an AI agent that updates this project to a newer Saasaloy CLI and newer module versions with saasaloy update. Use when the owner says \"update saasaloy\", \"upgrade the CLI\", \"pull the latest modules\", \"update the base template\", \"work the merge plan\", \"clear the update notes\", when saasaloy update or saasaloy outdated --check exits 3 or 2, when a merge plan or .saasaloy\u002Fmerge-plan.md is handed to you, or when an adopted project takes its first update. Covers the CLI upgrade, the preview, --out, the file merges, the update notes and \"Notes that may apply\", --resolved and --done, a file deleted locally and --restore, a three-way or two-way base, an update that skips releases, --from, the verify commands, and the exit codes.","https:\u002F\u002Fgithub.com\u002Fmimukit\u002Fsaasaloy\u002Fblob\u002Fmain\u002Fpackages\u002Fcli\u002Ftemplates\u002Fbase\u002F_agents\u002Fskills\u002Fsaasaloy-update\u002FSKILL.md",[],[]]