@stjoseph/prumo 0.0.1

package/.prumo-templates/mobile/storage.md

@@ -0,0 +1,84 @@
+# Storage
+
+## Rule
+
+Put in `expo-secure-store` anything that **grants access if stolen**: the session cookie and any token.
+Put everything else in MMKV.
+
+Do not use MMKV's own encryption.
+
+Persist the TanStack Query cache to MMKV with a maximum age.
+
+On logout, clear the session, the persisted cache, and every MMKV key holding that user's data. Leave
+device preferences (theme, language) untouched.
+
+Decide when writing each key whether it belongs to the user or to the device.
+
+## Rationale
+
+The criterion is *does this alone open somebody's account*. A token does. A name does not. A cached list
+of orders does not: it reveals information, and revealing is not granting.
+
+Secure storage could not hold more even if the rule wanted it to: iOS has historically refused values
+above roughly 2048 bytes, so a cached profile does not fit. Expo's own documentation also warns against
+relying on it as a single source of truth for irreplaceable data.
+
+MMKV's encryption is not used because its key has to live somewhere. Embedded in the bundle it is public;
+in secure storage, the secure store is being used anyway with one more step. The app sandbox already keeps
+other applications out of MMKV; its encryption defends against filesystem access, a rooted device or an
+extracted backup, not against the neighbouring app.
+
+Persisting the query cache is what separates an app that opens showing yesterday's list while it refreshes
+from one that opens blank with a spinner, which is what happens every time somebody opens it in a lift. A
+maximum age exists because a cache without one presents months-old data as current with no way for the
+user to tell.
+
+That persistence is also why logout must clear more than the session: switching users on one device would
+otherwise show the previous user's data. Wiping MMKV wholesale instead would take theme and language with
+it, so the same person returning finds the app as if it were new; security that punishes the common case
+gets switched off by somebody.
+
+## Applies to
+
+Every write to persistent storage, and the logout path.
+
+## Examples
+
+Choosing a store:
+
+```
+✅  SecureStore: the session cookie
+    MMKV:        theme, last opened tab, cached responses
+❌  MMKV:        the session token        // works perfectly, protects nothing
+```
+
+Opening MMKV (version 4):
+
+```
+✅  const storage = createMMKV({ id: 'app' });  storage.remove(key)
+❌  const storage = new MMKV();                  storage.delete(key)     // the version 3 API
+```
+
+Logout:
+
+```
+✅  clear session + query cache + user-scoped MMKV keys, kept as one list the logout walks
+❌  clear session only
+❌  MMKV.clearAll()          // takes theme and language too
+```
+
+## Enforcement
+
+**Review only, and one line carries the weight:** that nothing granting access was written to MMKV.
+Nothing breaks if it is: the app works exactly the same, which is what makes it the mistake worth
+naming.
+
+**Two facts worth knowing rather than discovering:**
+
+**On iOS, secure-store data survives uninstalling and reinstalling the app** with the same bundle ID.
+*Deleting the app to sign out* does not work, and a handed-on device stays signed in. Android deletes it
+on uninstall.
+
+**Clearing on logout does not address a lost device.** Nobody signs out of a phone that is gone:
+invalidating the session remotely is server-side work, and wiping local storage is not the answer to
+theft.

package/.prumo-templates/mobile/structure.md

@@ -0,0 +1,79 @@
+# Structure
+
+## Rule
+
+Organise by feature. Put a feature's components, hooks and queries together in `features/<name>/`.
+
+Keep files under `app/` thin: a route file renders a feature and holds no screen implementation. Let
+`app/` carry only navigation: route files, `_layout.tsx`, and groups such as `(tabs)` and `(auth)`.
+
+**Do not organise by type.** There is no root `components/`, `hooks/` or `screens/` holding every feature's
+files.
+
+Put shared code in one of four places and nowhere else:
+
+- `components/ui/`: visual primitives, written by hand
+- `api-contract/`: the wire contract with the API, as `client/data.md` describes
+- `lib/`: pure functions, with no state and no React
+- a named feature: anything with behaviour
+
+Do not create a `shared/` or `common/` folder.
+
+Keep client state in React context, one context per subject, living in the feature that owns it. Do not
+create a single application context.
+
+Resolve `@/` to the app's own `src/`.
+
+## Rationale
+
+`app/` is a URL namespace: everything in it has a public path attached. Putting a screen's implementation
+there mixes *how you reach this screen* with *what this screen does*, and the first changes for navigation
+reasons while the second changes for product reasons. Keeping route files thin also matches the web area,
+which matters in a monorepo: the same feature exists in two apps, and if one puts the screen in the route
+while the other puts it in the feature, comparing them becomes translation.
+
+`components/ui/` exists here for the same reason it does on the web, holding the same kind of thing. Only
+its origin differs: on the web those files come from the shadcn CLI, and here they are written by hand
+from the start. Dropping the folder would force naming a button as a feature, and a feature is a slice of
+product: a button can be named, it simply is not one.
+
+A `shared/` folder has no admission criterion: *is this shared?* answers yes for anything used twice, so
+it only grows. Not everything shared is a component either: formatting a date is a function in a file.
+**If it uses React, it does not belong in `lib/`.**
+
+One context per subject exists because context re-renders **every** consumer when its value changes. A
+context bundling theme, session and the current tab makes a theme toggle re-render the whole tree:
+invisible with three components, expensive when the app grows, and never an error.
+
+## Applies to
+
+Every file under `src/` and `app/`.
+
+## Examples
+
+A screen:
+
+```
+✅  app/orders.tsx            → renders <OrderList/>
+    features/orders/order-list.tsx
+❌  app/orders.tsx            → the whole screen, 200 lines
+```
+
+Shared code:
+
+```
+✅  components/ui/button.tsx
+    lib/format-currency.ts
+    features/notifications/
+❌  shared/components/button.tsx
+    features/button/
+```
+
+## Enforcement
+
+**Review only.** Nothing prevents a screen from growing inside `app/`, a `shared/` folder from appearing,
+or two contexts from being merged for tidiness.
+
+**Worth knowing rather than discovering:** the web area's `components/ui/` is maintained by the shadcn
+CLI, which overwrites on reinstall. Here there is no CLI, so nothing overwrites, and equally nothing
+brings improvements from upstream.

package/.prumo-templates/monorepo/dependencies.md

@@ -0,0 +1,84 @@
+# Dependencies
+
+## Rule
+
+Declare every external dependency's version once, in the catalog. Reference it as `catalog:` in each
+`package.json`.
+
+Where two apps genuinely need different majors of one package, put the odd one in a **named** catalog and reference
+it as `catalog:<name>`. Name the catalog after the version it holds (`tailwind3`), and write beside it the condition
+that removes it.
+
+Depend on a workspace package with `workspace:*`.
+
+Declare in each package every dependency that package imports. Keep the root `package.json` for workspace
+tooling only: nothing application code imports.
+
+Let an app depend on packages. **Never let an app depend on another app**, not even for a type.
+
+Never let a package depend on an app.
+
+## Rationale
+
+One catalog entry per dependency means *which version of X do we use* has a single place to look, with no
+exception to check first. Restricting the catalog to what more than one package uses would require a
+judgement that ages: when a second package adopts something, somebody has to remember to move the version,
+nothing prompts them, and the project ends up running two versions of one library until one breaks.
+
+A named catalog is the one exception, and it is visible by construction: it has a name, it sits in one file, and
+every other conflict still fails. It exists because the stable NativeWind requires Tailwind 3 while the web uses
+Tailwind 4; refusing any exception would have made a workspace holding both web and mobile impossible to generate.
+
+`workspace:*` rather than a range, because nothing here is published. A range on an internal package would
+describe a choice that does not exist; `*` states what is true: the copy sitting next to it.
+
+Declaring per package is what keeps **phantom dependencies** out. With `react` only at the root, an app
+imports it and works without declaring it, harmless until somebody extracts that app, or removes `react`
+elsewhere, and an import breaks with nothing having changed. The repetition this seems to cost is not real:
+every entry is the identical line `"react": "catalog:"`, not a version to keep in sync.
+
+An app depending on another app is tempting (importing a type from the API looks like the way to stop
+duplicating the contract), and it is wrong twice. **The type is the wrong one:** a response is an entity
+passed through `ClassSerializerInterceptor`, so every excluded property is absent from the JSON and present
+on the type, promising fields the payload never carries. **And an app is deployable:** the dependency means
+building one requires the other, CI needs both for either, and the boundary between two things with
+separate lifecycles stops existing.
+
+`import type` does not rescue it. It is erased at runtime and needed everywhere else (by `tsc`, by the
+editor, by CI), and nothing stops somebody swapping it for a value import when the type later becomes a
+constant.
+
+If two apps need the same thing, it belongs in the package.
+
+## Applies to
+
+Every `package.json` in the workspace, and the catalog.
+
+## Examples
+
+Declaring:
+
+```
+✅  "react": "catalog:"            "@app/api-contract": "workspace:*"
+❌  "react": "^19.0.0"             "@app/api-contract": "^1.0.0"
+```
+
+Direction:
+
+```
+✅  apps/web  → packages/api-contract
+❌  apps/web  → apps/api
+❌  apps/web  → import type { User } from '../../api/src/…'
+```
+
+## Enforcement
+
+**The installer.** pnpm's strict isolation rejects importing what a package did not declare, in every
+workspace, including one holding `mobile`. Expo does **not** need `nodeLinker: hoisted`: a workspace with `api`,
+`web` and `mobile` on the default isolated linker bundles iOS and Android, verified with Expo SDK 57.
+
+**One import nobody writes still counts.** NativeWind's Babel JSX runtime injects `react-native-css-interop` into
+the app's source, so the app declares that package; without the declaration the bundle fails to resolve it.
+
+**Review only.** That no app imports from another app, and that the root `package.json` gained nothing an
+app imports.

package/.prumo-templates/monorepo/layout.md

@@ -0,0 +1,89 @@
+# Layout
+
+## Rule
+
+Put deployable things in `apps/` and shared code in `packages/`.
+
+Name an app directory after its type (`apps/api`, `apps/web`, `apps/mobile`, `apps/site`), never after
+the product.
+
+Keep one package from the start: the integration layer between the clients and the API. It holds URL
+construction, the `ApiError` parsing, the hand-written contract types and the query factories.
+
+**Let each app inject its own transport.** The package does not perform the fetch.
+
+Ship the package as TypeScript source. Do not build it to `dist/`, and do not give it a build step.
+
+Create a second package only when **two apps consume it**. While one app uses it, keep it inside that app.
+
+Name a package for what it does. **Never `shared`, `common` or `utils`.**
+
+Resolve `@/` to each app's own `src/`. Import a package by its name.
+
+## Rationale
+
+An app and a package have different lives. An app has a deploy, environment variables, a version in a
+store; a package has none of that and exists because something imports it. One directory for both erases a
+distinction that reappears in every later decision: what CI builds, what a filter reaches, what has a
+Dockerfile.
+
+The integration package exists because the rest of the sharing was already refused: contract types are
+hand-written rather than generated, validation differs on each side, and shadcn copies components rather
+than sharing them. What genuinely repeats across clients is how a URL is built, how an error body becomes
+an `ApiError`, and what the contract's shapes are. Only transport differs (the web sends its cookie
+automatically, mobile attaches it from secure storage, a site's server calls anonymously), so transport
+comes from outside.
+
+**This is also what recovers most of what hand-written types gave up.** That decision accepted, as its
+cost, that a renamed field leaves each client compiling against its own copy. One copy instead of three
+does not remove drift from the server; it stops it multiplying, and makes fixing it one place. The package
+describes the **wire shape** (what the JSON carries), not an entity whose excluded fields are absent from
+it.
+
+Source rather than a build, because a built package needs a mandatory build order and, without a watcher,
+produces the standard monorepo failure: changing the package and not seeing the effect. Editing a type and
+seeing the error immediately is what makes sharing better than copying.
+
+Two consumers, because one is evidence of nothing, and extracting early into a package costs more than
+extracting early into a component. A name, because `shared` cannot grow wrongly only by never being able to
+grow rightly: anything fits inside it.
+
+## Applies to
+
+The workspace root and everything under it.
+
+## Examples
+
+Layout:
+
+```
+✅  apps/api  apps/web  packages/api-contract
+❌  apps/acme-backend  packages/shared
+```
+
+The package's boundary:
+
+```
+✅  createClient({ fetch: myTransport })
+❌  the package calling fetch and reading a cookie itself
+```
+
+## Enforcement
+
+**Review only.** That a new package has two consumers and a real name, and that nothing crept into a
+`shared` directory under another spelling.
+
+**Two things worth knowing:**
+
+**Moving a file between apps calls for checking its imports.** `@/` means something different in each app,
+so a file moved to the same path in another app can compile while pointing elsewhere. That only happens
+with generic code, which is the code that belonged in the package.
+
+**A Vite app and a Next app consume the package as source with no configuration**: Next 16 needs no
+`transpilePackages`; a page importing it builds, stays static, and renders the imported value. Its `exports` points at `src/index.ts`,
+`tsc` with `moduleResolution: bundler` typechecks through it, and `vite build` bundles it, verified in a composed
+workspace. The API does not import the package, so Nest never compiles it.
+
+**Expo resolves workspace packages automatically from SDK 52**, with no `watchFolders` or
+`nodeModulesPaths` configuration. Older guidance about configuring Metro by hand no longer applies. Verified with
+SDK 57: Metro bundles `@app/api-contract` as source, and Jest with `jest-expo` resolves it the same way.

package/.prumo-templates/monorepo/tasks.md

@@ -0,0 +1,76 @@
+# Tasks and configuration
+
+## Rule
+
+Give the root `package.json` three scripts (`lint`, `typecheck` and `test`), each running through
+`pnpm -r`.
+
+**Do not add a `dev` script at the root.** Start development with `pnpm --filter <app> dev`.
+
+Keep compiler options in `tsconfig.base.json` at the workspace root. Extend it by relative path from each
+app and package, overriding only what differs.
+
+Do not use project references.
+
+Keep Biome's shared settings (formatter and preset) in `biome.jsonc` at the root. Give each app that needs more
+its own `biome.jsonc` with `"extends": "//"`, holding only what differs.
+
+## Rationale
+
+`pnpm -r` runs in topological order, so the orchestration usually credited to a task runner already exists.
+What does not exist is caching, and caching pays once a build hurts, which a freshly generated workspace
+does not.
+
+The missing `dev` script is deliberate. `pnpm dev` in a workspace with four apps would start four
+processes, one of them interactive, when whoever typed it expected the app they are working on. **Its
+absence is what teaches that `dev` is per app**; if it existed, nobody would learn.
+
+The other three belong at the root because that is what the pre-push hook calls. Leaving them out would
+mean each person assembling their own `--filter`, and several versions of one command.
+
+A single base config keeps five files from starting identical and diverging silently: one gains a flag,
+another does not, and nobody notices until behaviour differs between apps. It is a root file rather than a
+package because turning configuration into a package adds a `package.json`, a workspace entry and a
+declared dependency in order to deliver one JSON file.
+
+Biome follows the same shape because the two apps genuinely differ (decorator parsing in `api`, the shadcn
+exceptions in `web`) while formatting and the preset must not. `"extends": "//"` is Biome's own syntax for
+*inherit from the root, wherever it is*, and running `biome` from the root respects every nested file. One
+configuration with per-directory overrides was refused because every new app would edit the shared file, and
+because composing it would mean merging JSON rather than moving a file.
+
+**Project references are refused for the same reason the shared package ships source:** they need
+`composite: true` and produce a build order with intermediate artefacts, which brings back the failure of
+changing something and not seeing the effect.
+
+## Applies to
+
+The workspace root, and every `tsconfig.json` beneath it.
+
+## Examples
+
+Starting work:
+
+```
+✅  pnpm --filter web dev
+❌  pnpm dev                    // four apps, one of them interactive
+```
+
+Extending the base:
+
+```
+✅  { "extends": "../../tsconfig.base.json", "compilerOptions": { "jsx": "react-jsx" } }
+❌  a complete compilerOptions block per app
+```
+
+## Enforcement
+
+**The hook.** Pre-push runs the root `typecheck`, so a type error in any package stops the push.
+
+**Review only.** That a new app extends the base rather than copying it, and that a root `dev` script has
+not appeared.
+
+**The reversal condition, stated so it is measurable rather than a feeling:** without caching,
+`pnpm -r typecheck` runs `tsc` in every package from scratch every time. Turborepo belongs on the table the
+day that becomes annoying enough for somebody to stop running it before pushing, not when the repository
+merely feels large.

package/.prumo-templates/multi-tenancy/client.md

@@ -0,0 +1,83 @@
+# The tenant in a client
+
+## Rule
+
+Clear the **entire** query cache when the active tenant changes. Do not add the tenant to query keys.
+
+Navigate to the tenant's root after a switch, always, even when the current route would exist in the
+destination.
+
+Show the active tenant persistently on every screen. Not inside a menu.
+
+Never send the tenant to the API: not as a header, not as a parameter. The server derives it.
+
+Never read the tenant from local storage or from a cached response to decide what to display.
+
+## Rationale
+
+The query-key rule already says a key includes everything that changes the result, and the tenant changes
+the result. **But the tenant is invisible to whoever writes the query:** the server derives it from the
+session, so the client never sends it, never passes it as a filter, and never sees it in the calling code.
+Nobody remembers to put it in a key, because nothing in the file suggests it exists. Adding it everywhere
+would be correct when remembered and silent when not; clearing once, in one place, does not depend on
+memory.
+
+Staying on the current route after a switch means a 404 as the first thing the user sees, answering a
+question they did not ask: they asked to change company. Mapping the route back to a list works for
+`/orders/abc` and lands somewhere strange for `/settings/billing/method/xyz`, and behaviour that depends
+on the shape of a URL is behaviour nobody can predict. Worse, if a resource with the same id existed in
+the destination, staying would open **a different record at the same URL** while the user believed nothing
+had changed.
+
+**The visible label is a safety rule, not decoration.** Whoever operates a multi-tenant system usually has
+access to several tenants, and the expensive mistake is not the system leaking; it is the person acting
+on the wrong tenant: deleting an order, sending an invoice, inviting somebody, in the wrong account. The
+system cannot detect it, because from the API's side the request is perfectly authorised. A selector inside
+a menu answers *where am I* only for someone who already suspects; whoever acts by mistake acts because
+they do not.
+
+## Applies to
+
+Every client of a multi-tenant project: `web`, `mobile` and `site` alike.
+
+## Examples
+
+Switching:
+
+```
+✅  await organization.setActive({ organizationId })
+    queryClient.clear()
+    router.navigate({ to: '/' })
+❌  await organization.setActive({ organizationId })   // cache and route untouched
+```
+
+Query keys:
+
+```
+✅  ['orders', filters]
+❌  ['orders', tenantId, filters]     // correct when remembered, silent when not
+```
+
+Trusting the client:
+
+```
+✅  GET /api/v1/orders
+❌  GET /api/v1/orders?tenantId=…
+```
+
+## Enforcement
+
+**Review only, and all three fail silently:**
+
+That a switch clears the cache. Forgetting shows the previous tenant's data on the next screen, with no
+error.
+
+That nothing sends a tenant to the API. It would be ignored today, and it teaches the habit that the
+client may choose.
+
+That the active tenant is on screen. Its absence breaks nothing and costs somebody a wrong action in the
+wrong account.
+
+**Known limit:** if the session's tenant changes without this app knowing (another tab switching), the
+cache is not cleared. That follows from the active organization living in the session, and is the cost that
+decision accepted.

package/.prumo-templates/multi-tenancy/isolation.md

@@ -0,0 +1,104 @@
+# Isolation
+
+## Rule
+
+Derive the active tenant from the session. **Never from anything the client sends**: not a header, not a
+path parameter, not the `Host`.
+
+Use Better Auth's `organization` plugin with `activeOrganizationId` **persisted in the session**. Do not
+manage the active organization client-side.
+
+Give every tenant-scoped table a `tenant_id` that is `NOT NULL` and carries a foreign key into
+`organization`, with `ON DELETE RESTRICT`.
+
+Register the MikroORM filter with `default: true` and set its parameter once per request, from the
+session.
+
+**Never accept `tenant_id` as a method argument.** Read it where the filter's parameter is read.
+
+Call `qb.applyFilters()` on every QueryBuilder query. Write `WHERE tenant_id = $1` in every raw query, and
+a comment saying it was checked.
+
+Declare a route that has no tenant. **Treat an absent filter parameter as an error**, never as "no
+filter".
+
+Run Better Auth's migrations before ours.
+
+## Rationale
+
+The tenant is a property of who you are, not of how you asked. A client-sent tenant works, and depends on
+validation existing on **every** route; forgetting once is complete cross-tenant access, and the
+forgetting is invisible, because the route works perfectly for someone entitled and equally well for
+someone who is not. A subdomain is input too: it arrives in a header a client controls and that proxies
+rewrite, so the defence would rest on infrastructure configuration.
+
+Better Auth's own documentation offers managing the active organization client-side, for multiple tabs. For
+a multi-tenant system that means the **tab** decides isolation, so it is refused here by name: somebody
+will find that sentence.
+
+The filter is an application-level guard, and its own documentation says a raw query or a forgotten
+`filters` option reads past it. It leaves three holes and they get different answers, because the problems
+differ: creation is not filtered at all, the QueryBuilder needs an explicit call, and raw SQL is out of
+reach. Reading `tenant_id` from the session rather than taking it as an argument removes the path by which
+somebody passes the tenant of the record being read instead of the tenant of the user reading it.
+`NOT NULL` does not prevent a wrong tenant; it prevents an absent one, which is the common failure.
+
+A missing parameter must be an error because the alternative turns every resolution bug (a session that
+did not load, middleware in the wrong order) into a query that returns the whole system, silently.
+
+The foreign key exists because without it a `tenant_id` pointing nowhere inserts cleanly and passes tests,
+leaving a row invisible to every filtered query. `RESTRICT` means deleting an organization with business
+data fails, which is wanted: the application should decide what happens to that data rather than a library
+CLI cascading it away.
+
+## Applies to
+
+Every tenant-scoped table, every query against one, and the request pipeline that resolves the session.
+
+**The tenantless list is closed:** authentication, the health route, third-party webhooks, and the route
+listing a user's organizations. Every new route is born with a tenant, and adding to this list is a
+decision rather than configuration.
+
+## Examples
+
+Where the tenant comes from:
+
+```
+✅  const tenantId = session.activeOrganizationId
+❌  const tenantId = req.headers['x-tenant-id']
+❌  const tenantId = subdomainOf(req.headers.host)
+```
+
+Creating a row:
+
+```
+✅  create(input: CreateOrderInput)      // reads the tenant where the filter does
+❌  create(input: CreateOrderInput, tenantId: string)
+```
+
+Stepping off `em.find`:
+
+```
+✅  qb.applyFilters()
+    // raw: tenant filter checked
+    WHERE tenant_id = $1 AND …
+❌  qb.where(…).getResult()               // no filter: reads every tenant
+```
+
+## Enforcement
+
+**Database.** `NOT NULL` rejects an absent tenant, and the foreign key rejects one that does not exist.
+
+**Boot.** The filter is registered once with `default: true`, so `em.find` cannot opt out by omission.
+
+**Review only, and these are the lines that matter; every one of them fails silently:**
+
+That `applyFilters()` is present on each QueryBuilder query, and `WHERE tenant_id` on each raw one.
+
+That no method takes a tenant as an argument.
+
+That a route added to the tenantless list genuinely belongs there.
+
+**Not solved here:** raw SQL remains outside the filter's reach by design. Row Level Security is the only
+guarantee that survives it, and it is not adopted because its cost in this stack is unmeasured. See the
+open question.