@stjoseph/prumo 0.0.1

package/.prumo-templates/database/entities.md

@@ -0,0 +1,97 @@
+# Entities
+
+## Rule
+
+Declare an entity with `defineEntity` **and a class**. Put the schema in the `defineEntity` call and
+no MikroORM decorators on the class. The class carries `@Exclude` and `@ApiProperty` only: the
+serialization and documentation decorators.
+
+Keep the default `UnderscoreNamingStrategy`. Table names are singular and match the class name;
+columns are snake_case. Do not configure a naming strategy and do not set `tableName`.
+
+Give every table `id`, `created_at` and `updated_at`. Let `id` be `uuid` with `DEFAULT uuidv7()`. Let
+both timestamps be `timestamptz`, maintained by MikroORM's `onCreate` and `onUpdate`.
+
+Add `tenant_id` to every tenant-scoped table. Add `deleted_at` only with a stated reason.
+
+Map types as follows: money is `numeric`, text is `text`, JSON is `jsonb`, time is `timestamptz`, and
+an enum is `text` with a CHECK constraint. Never `float` for money, never `varchar(n)`, never `json`,
+never a native Postgres enum.
+
+Index `tenant_id`, every foreign key column, and every column used to fetch a single row. Add any
+other index on measurement, not on suspicion.
+
+Declare `ON DELETE RESTRICT` on every foreign key. Use `CASCADE` only where the child cannot exist
+without its parent, and say so where you use it.
+
+## Rationale
+
+The class exists because responses are serialized from the entity, which needs `@Exclude` to mark what
+must not leave. `defineEntity` exists because v7 made it the primary path and it keeps the ORM's own
+metadata off the class. The two are separate on purpose.
+
+snake_case is not a style choice: Postgres folds an unquoted identifier to lower case, so a camelCase
+column must be quoted in every hand-written query, psql session and dashboard, forever. Singular is the
+strategy's default, so it costs nothing and makes the table name match the class name.
+
+`numeric` because floating point does not represent 0.10 exactly and the error accumulates across a
+sum. `text` because it performs identically to `varchar(n)` in Postgres while adding no limit that
+hurts to change. `jsonb` because `json` stores raw text and cannot be indexed. A CHECK rather than a
+native enum because adding a value to a native enum is painless but removing or reordering one
+requires recreating the type and rewriting every dependent column.
+
+The three mandatory indexes need no measurement, because they are consequences of the design.
+**Postgres does not index the referencing side of a foreign key** (only the referenced side, by virtue
+of being a primary key), so `order.customer_id` has no index unless someone declares it, and that is
+the most commonly forgotten index there is.
+
+`RESTRICT` matters because deletes are real here. `CASCADE` by default would remove a customer's
+orders, invoices and payments in one transaction and return success, with no error and no warning.
+`RESTRICT` makes that command fail and forces the decision into explicit code.
+
+## Applies to
+
+Every entity file, which lives inside its module's `entities/` directory.
+
+## Examples
+
+Naming:
+
+```
+✅  class User {}      → table user, column created_at
+❌  class User {}      → table users, column createdAt
+```
+
+Money and enums:
+
+```
+✅  amount: numeric          status: text + CHECK (status IN (...))
+❌  amount: double precision status: CREATE TYPE ... AS ENUM
+```
+
+Declaring text:
+
+```
+✅  displayName: p.text()     → text
+❌  displayName: p.string()   → varchar(255)
+```
+
+Deletes:
+
+```
+✅  ON DELETE RESTRICT
+❌  ON DELETE CASCADE        // on customer → order
+```
+
+## Enforcement
+
+**Migration review.** Every rule here shows up as SQL in a migration, which is the one place a human
+reads the schema as text. That makes migration review the real check, and the reason migrations are
+generated as readable SQL rather than applied invisibly.
+
+**Review only.** That a new table carries the structural columns, that a foreign key got its index, and
+that each `CASCADE` was deliberate.
+
+**A caveat worth knowing:** `user` is a reserved word in Postgres. `SELECT * FROM user` in psql returns
+the session user, not the table, and does not error. Quote it: `FROM "user"`. The ORM always quotes
+identifiers, so this only bites hand-written queries.

package/.prumo-templates/database/migrations.md

@@ -0,0 +1,74 @@
+# Migrations
+
+## Rule
+
+Generate a migration from the entity diff, then read and edit it before committing. Treat what the
+generator emits as a draft.
+
+Run migrations as a separate pipeline step, before the new version is deployed. Never at application
+boot, and never by hand.
+
+Make every migration compatible with the **previous** release. Removing a column is two deployments:
+one that stops using it, one that removes it.
+
+Delete the generated `down`. Undoing a schema change is a new migration going forward.
+
+Keep DDL and data apart. A migration performs DDL only. Filling existing rows is a separate task, run
+in batches outside the deploy path, and written so it survives running twice.
+
+Add a column that existing rows must eventually carry as nullable first. It becomes `NOT NULL` in a
+third deployment, after the backfill finishes.
+
+## Rationale
+
+The generator does not see a rename. It sees one column gone and another appeared, and emits
+`DROP COLUMN` plus `ADD COLUMN`: correct against the diff and wrong against the intent, with no tool
+able to tell the difference. Reading the SQL is also what makes migration review the real check for the
+entity rules; unread, that claim has nothing behind it.
+
+Running at boot would race N replicas against each other and put every one into a restart loop when a
+migration fails. It would also mean **the process serving requests holds DDL permission**, so any
+injection or compromise could drop a table. A separate step lets the deploy use a privileged user for
+thirty seconds while the application runs as one that only reads and writes rows.
+
+During a rolling deploy the previous version is still running against the new schema, so a migration
+that removes something the old code reads breaks production before the new version finishes arriving.
+
+A `down` lies. Reversing a migration that dropped a column recreates it empty: the command succeeds,
+the schema returns, the data does not. And because migrations stay compatible with the previous
+release, rolling back the application never required rolling back the schema in the first place.
+
+DDL is fast and locks; a backfill is slow and does not need to. Together, the slow one inherits the
+lock and the deploy waits on it.
+
+## Applies to
+
+Every file under the migrations directory, and the deploy pipeline.
+
+## Examples
+
+A rename, after editing the generated draft:
+
+```
+✅  ALTER TABLE invoice RENAME COLUMN total TO amount
+❌  ALTER TABLE invoice DROP COLUMN total;
+    ALTER TABLE invoice ADD COLUMN amount numeric
+```
+
+Separating the backfill:
+
+```
+✅  migration:  ALTER TABLE order ADD COLUMN status text
+    task:       UPDATE order SET status = 'open' WHERE status IS NULL  -- batched
+❌  migration:  ALTER TABLE order ADD COLUMN status text NOT NULL DEFAULT 'open'
+```
+
+## Enforcement
+
+**Pipeline.** Migrations run in their own step, so the application cannot apply them and does not hold
+the permission to.
+
+**Review only, and it carries most of the weight in this area:** that the generated SQL was actually
+read, that nothing in it is destructive against the previous release, and that a backfill did not get
+folded into a migration. A 200-line migration is the signal that the reading became a skim, and it is
+usually two migrations mixed together.

package/.prumo-templates/database/queries.md

@@ -0,0 +1,79 @@
+# Queries
+
+## Rule
+
+Inject the `EntityManager`. Read with `em.find` and `em.findOne`, write with `em.persist` and
+`em.flush`. **Do not use `@InjectRepository`.**
+
+Declare every relation as `Ref<T>` or `Collection`. Access it only through `$`. State `populate` on
+every read that needs the relation.
+
+Reach for the QueryBuilder only where the operation does not exist in `em.find`: aggregation, window
+functions, CTEs, upserts. Reach for raw SQL only where the QueryBuilder cannot express it either.
+Write one comment line saying why, at each step down.
+
+Apply the tenant rules to raw SQL exactly as to everything else.
+
+Return the managed entity from a service. **Only the services of the module that owns an entity mutate
+it.** A controller, an interceptor and a serializer read it and never write to it.
+
+## Rationale
+
+MikroORM's own guidance is that the `EntityManager` is the persistence API and repositories are an
+extension point; `persist`, `flush` and `remove` were removed from repositories in v6 for being
+shortcuts to it. Since nothing can be persisted without the `em`, using a repository as well would put
+**two** doors in every service with a boundary somebody decides per method. This rule fights muscle
+memory (every Nest-with-an-ORM example reaches for `@InjectRepository`), which is why it is written
+negatively.
+
+`Ref` and `$` turn N+1 from a review item into a compile error, because `Loaded<Entity, Hints>` tracks
+what was populated and accessing `$` on an unloaded relation does not typecheck. N+1 is the most silent
+database defect there is: the page works and merely gets slower as the list grows. Eager loading would
+trade it for over-fetching on every query, invisible at the call site.
+
+The comment on a QueryBuilder query exists because a year later nobody can tell whether it is there
+because it was needed or because the author did not know how to express it otherwise, and that
+difference decides whether anyone may simplify it.
+
+An entity from `em.find` is managed, so changing it and flushing later writes to the database with no
+`persist` call. That is the Unit of Work, accepted deliberately. The ownership rule is what keeps a
+cosmetic change in an interceptor from becoming a write when some service downstream flushes.
+
+## Applies to
+
+Every service. The relation rules also shape how entities are declared.
+
+## Examples
+
+The door:
+
+```
+✅  constructor(private readonly em: EntityManager) {}
+❌  constructor(@InjectRepository(User) private readonly users: EntityRepository<User>) {}
+```
+
+Relations:
+
+```
+✅  const u = await em.findOne(User, id, { populate: ['organization'] })
+    u.organization.$.name
+❌  const u = await em.findOne(User, id)
+    u.organization.name
+```
+
+Dropping a level:
+
+```
+✅  // QueryBuilder: needs a window function, which em.find cannot express
+❌  // (no comment)
+```
+
+## Enforcement
+
+**Compiler.** Accessing an unpopulated relation through `$` does not typecheck. This is the only
+compile-time guarantee in the area, and it covers the most expensive common defect.
+
+**Review only.** That `@InjectRepository` did not creep back in, that each step down the query ladder
+carries its reason, and that nothing outside the owning module's services mutates an entity. Nothing prevents the
+last one (a managed entity and a detached one have the same shape), and its failure is silent: a
+change made for display becomes a write on the next flush of that request.

package/.prumo-templates/database/testing.md

@@ -0,0 +1,82 @@
+# Testing against the database
+
+## Rule
+
+Start one Postgres container per test run with Testcontainers. Give each Vitest worker its own database
+inside it. Never point a test at a shared or long-lived database.
+
+Build the schema by running the migrations, once per worker database. Do not use the schema generator.
+Run Better Auth's migrations first, through its programmatic `getMigrations`, then ours.
+
+Truncate every table between tests, in a single `TRUNCATE` statement listing them all, Better Auth's
+included. Do not wrap a test in a transaction and roll it back.
+
+Create test data with a factory per entity: a function returning a valid row from defaults and
+accepting overrides. Do not keep a shared fixture file.
+
+Pass only what the scenario depends on to a factory. Let everything else come from its defaults.
+
+## Rationale
+
+A real Postgres is not optional here: `uuidv7()` does not exist in a fake one, and the default that
+generates every primary key would have to be stubbed away.
+
+Vitest runs files in parallel workers, so one shared database means a worker truncating a table while
+another reads it. The test then fails intermittently and people re-run until it passes, which is worse
+than failing honestly. A database per worker keeps the parallelism and makes the isolation real.
+
+The schema comes from the migrations because migrations are edited by hand, so what they produce can
+diverge from what the entities describe. Building the test schema from the entities would hide exactly
+that divergence: the suite would run against a schema that exists nowhere while production runs against
+another.
+
+Truncation rather than rollback, because the code under test opens its own transactions. A test already
+inside one turns the code's transaction into a savepoint, which behaves differently, and a commit is
+never exercised. Testing a lock inside a wrapper that will roll back tests something adjacent to the
+truth.
+
+Better Auth's migrations run first for the same reason they do in production: an application table
+references `auth.user`, so its foreign key cannot be created before the table exists. Its tables are in the
+truncation for the mirror reason: leave them out and the next test's factory collides with a user the
+previous test created. A factory for such a table creates the user first; Better Auth's tables have no entity
+here, so that insert is raw SQL, with its one-line reason.
+
+Factories rather than a fixture file, because a fixture grows until a test depends on user number twelve
+having a particular plan, and then neither can be changed alone. A factory call states what the scenario
+needs and leaves the rest implied.
+
+## Applies to
+
+Every test that touches the database. Anything that does not (the runner, coverage, file naming, unit
+test conventions) belongs to `core/testing.md`, not here.
+
+## Examples
+
+Stating the scenario:
+
+```
+✅  const u = await makeUser({ plan: 'trial' })
+❌  const u = fixtures.users[12]
+```
+
+Cleaning up:
+
+```
+✅  TRUNCATE "user", organization, invoice
+❌  TRUNCATE "user"        // fails: invoice still references it
+```
+
+## Enforcement
+
+**Structural.** A worker cannot see another worker's data, because it cannot reach another worker's
+database. Nothing has to be remembered for that to hold.
+
+**The suite itself.** Running migrations rather than generating the schema means a wrong migration fails
+a test instead of a deploy, which is what makes migration review a real check rather than a claim.
+
+**Review only.** That a test asserts against data it created, rather than against whatever happened to
+be there.
+
+**A note that will save an hour:** with `ON DELETE RESTRICT` on every foreign key, truncating a parent
+table alone fails while children exist. Truncate every table in one statement, or use `CASCADE`.
+Postgres's error message does not suggest either.

package/.prumo-templates/database/transactions.md

@@ -0,0 +1,68 @@
+# Transactions
+
+## Rule
+
+Open a transaction only where more than one operation must succeed or fail together. A single
+`em.flush()` is already atomic.
+
+Open it with `em.transactional(async em => …)`. Do not use the `@Transactional()` decorator, and never
+write `begin` / `commit` / `rollback` by hand.
+
+Keep every network call outside the transaction block: an email, a payment gateway, any HTTP request.
+
+Leave the isolation level at READ COMMITTED. Where an invariant depends on reading a row and then
+deciding, lock it with `SELECT … FOR UPDATE`. Do not raise the isolation level.
+
+Do not retry a failed transaction. Fix the lock ordering instead.
+
+## Rationale
+
+`em.flush()` wraps its changes in an implicit transaction, so an explicit one is not for writing
+correctly; it is for the case where two units of work must happen together. A per-request transaction
+would last as long as the request, so a five-second timeout at an email provider becomes five seconds of
+row locks; under concurrency that becomes a queue and the queue becomes an outage. The database ends up
+paying for someone else's slowness.
+
+The callback rather than the decorator, because the decorator makes the whole method the boundary and
+cannot be narrowed. A method that writes two rows and also sends an email would sit entirely inside the
+transaction with nothing in the code showing it. The decorator composes better through `REQUIRED`
+propagation; that is given up because its failure mode is silent and only appears under load.
+
+READ COMMITTED does not prevent read-decide-write: two requests read the same balance, both find it
+sufficient, and both write. Nothing fails. `FOR UPDATE` is the local, visible fix: the second
+transaction waits instead of aborting, so it needs no retry. Raising the isolation level would make
+every transaction in the system need retry logic, including the ones that never conflicted.
+
+A deadlock is an ordering bug, not bad luck, and retrying hides it: the system slows under load and
+nothing ever fails loudly enough to be investigated. A retry also repeats whatever side effects already
+happened outside the database.
+
+## Applies to
+
+Every service method that writes more than once.
+
+## Examples
+
+Keeping the network out:
+
+```
+✅  await em.transactional(async (em) => { … })
+    await mailer.send(…)
+❌  await em.transactional(async (em) => { … ; await mailer.send(…) })
+```
+
+Read, decide, write:
+
+```
+✅  const acc = await em.findOne(Account, id, { lockMode: LockMode.PESSIMISTIC_WRITE })
+❌  const acc = await em.findOne(Account, id)   // two requests both pass the check
+```
+
+## Enforcement
+
+**Review only, and one line of it matters more than anything else in this area:** that a read-decide-write
+sequence locks the row. Nothing detects a missing `FOR UPDATE`. The failure is silent and expensive
+(a negative balance, stock sold twice), and no transaction errors when it happens.
+
+Also review: that no network call sits inside a transaction block, and that nobody added a retry
+wrapper.

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

@@ -0,0 +1,83 @@
+# Components
+
+## Rule
+
+Style with NativeWind for everything it covers. Reach for a style object or `StyleSheet` only where an API
+requires one (an animated style, a native prop that takes no `className`), and write one comment line
+naming the API that required it.
+
+Express variants with `cva`, in every component.
+
+Extract a repeated class list on its **third** occurrence, and extract it as a component, never as a
+string constant.
+
+Do not sort classes automatically.
+
+Put text styling on the `Text` element itself.
+
+Treat `text-base` as *the base size on this platform*. Write an absolute value where a measurement must
+match the web exactly.
+
+## Rationale
+
+The ladder off NativeWind is the same shape as the one off `em.find` in the database rules, because the
+problem is the same: with no permission to step down, somebody forces the upper tool to do what it cannot;
+with unlimited permission, the lower one becomes the default because it is familiar. The comment answers,
+a year later, whether that `StyleSheet` was required or merely unfamiliar, which decides whether anyone
+may simplify it.
+
+**NativeWind's `rem` is 16 on web and 14 on native**, matching each platform's own default. `text-base` is
+therefore not the same size in the two apps. On mobile alone that is invisible and correct; in a monorepo
+it is the source of *why is the button smaller in the app?*, with the answer in neither codebase because
+both say `text-base`. Forcing them to match would make every piece of text larger than in every other app
+on the device, trading consistency with the platform for consistency with the other app of the same
+product, and the user only sees the first.
+
+NativeWind was chosen so one styling language would cross both clients. The **language** crosses; the
+**scale** does not.
+
+`cva` and the third-repetition rule carry over from the web area unchanged, for the reasons given there.
+
+## Applies to
+
+Every component under `src/`.
+
+## Examples
+
+Stepping off NativeWind:
+
+```
+✅  // Reanimated requires a style object for animated values
+    <Animated.View style={animatedStyle} className="rounded-lg" />
+❌  <Animated.View style={{ padding: 16, borderRadius: 8 }} />
+```
+
+Matching the web exactly:
+
+```
+✅  <View style={{ height: 48 }} />       // must match the web header
+❌  <View className="h-12" />             // 42dp here, 48px there
+```
+
+## Enforcement
+
+**Compiler.** `cva` makes variant names typed, so a misspelled variant does not build.
+
+**Review only.** That a style object carries its reason, and that a third repetition was extracted.
+
+**Five things worth knowing rather than discovering:**
+
+NativeWind's Babel JSX runtime injects `react-native-css-interop` into the app's own files, so the app declares
+that package even though no line of it is written by hand; without it the bundle cannot resolve the import.
+
+NativeWind 4 uses Tailwind 3's `@tailwind` directives, which Biome does not recognise, so that one rule is off for
+`global.css` alone.
+
+The same class is not the same measurement across web and mobile. The language crosses; the scale does
+not.
+
+React Native does not cascade styles the way the web does, so text styling belongs on the `Text` element
+rather than on an ancestor.
+
+Automatic class sorting is worth revisiting when Biome's rule leaves the nursery group and its fix becomes
+safe, the same condition recorded for the web.

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

@@ -0,0 +1,84 @@
+# Configuration
+
+## Rule
+
+Embed only values that are public by nature: the API base URL, and a third-party **publishable** key
+where the project uses such a service.
+
+**Never embed a secret.** A feature that needs one is performed by the API, and the app calls the API.
+
+Read configuration from `EXPO_PUBLIC_*` variables in **one** module that exports a typed object. Use
+static dot notation there. Nothing else in the app touches `process.env`.
+
+Verify in the build pipeline that every expected variable exists, and fail the build when one is missing.
+Do it in `app.config.ts`, which Expo evaluates before bundling: throw when a variable is absent. Do not validate
+at runtime.
+
+Set the variables in the pipeline's environment. **`expo export` reads them from the environment, not from
+`.env`.**
+
+Keep `.env` in `.gitignore` and commit `.env.example` with every variable and a safe sample value.
+
+## Rationale
+
+**There is no safe place in an app build.** Whoever holds the `.apk` or `.ipa` reads any string inside it.
+Expo states this directly: *"Do not store sensitive info, such as private keys, in `EXPO_PUBLIC_`
+variables. These variables will be visible in plain-text in your compiled application."*
+
+This is the opposite of the API, where an environment variable is the correct place for a secret. The
+criterion here is: **would this still be safe printed on a billboard?** A publishable key is designed for
+exactly that; it is what the name means.
+
+Obfuscating a secret instead would be a speed bump, extractable in minutes from the binary. Its worst
+quality is not weakness but the *sense* of protection, which leads to embedding things nobody would embed
+knowing they were exposed.
+
+One config module, because Expo inlines only static dot notation (`process.env['X']` is not replaced), so
+every variable must appear literally somewhere. Gathering those reads in one file is what that constraint
+already forces, and it means the module is also the list of what is baked into the binary.
+
+Validation belongs to the build because that is where the fix is cheap: a missing variable found then is
+two minutes, and found at boot it is a store submission and a review. At boot there is also nothing left
+to detect: an absent variable was replaced by `undefined` at bundle time, so it is a constant rather than
+a missing value.
+
+`app.config.ts` rather than a separate script, because Expo evaluates it on every bundle and every build: there
+is no command that produces a binary without passing through it. **`.env` does not reach it during export:**
+verified with Expo SDK 57, `expo config` loads `.env` while `expo export` evaluated the configuration without it
+and failed. That is harmless in a pipeline, where the variables come from its environment, and surprising on a
+laptop, which is why the template's README says so.
+
+## Applies to
+
+The config module, the `.env` files, and the build pipeline.
+
+## Examples
+
+What may be embedded:
+
+```
+✅  EXPO_PUBLIC_API_URL=https://api.example.com
+❌  EXPO_PUBLIC_STRIPE_SECRET_KEY=sk_live_…
+❌  EXPO_PUBLIC_DATABASE_URL=postgres://…
+```
+
+How it is read:
+
+```
+✅  // config.ts
+    export const config = { apiUrl: process.env.EXPO_PUBLIC_API_URL }
+❌  process.env[`EXPO_PUBLIC_${name}`]     // not inlined; always undefined
+❌  process.env.EXPO_PUBLIC_API_URL        // scattered through feature files
+```
+
+## Enforcement
+
+**Build.** The pipeline fails when an expected variable is missing, which is the only moment the fix is
+cheap.
+
+**Review only, and it is the line that matters:** that nothing secret was added to a variable. Nothing
+breaks if it is: the app works exactly as before, and the value is simply readable by anyone who
+downloads it.
+
+A feature that appears to need a secret in the app is a feature that belongs on the server. That is the
+question to ask before adding a variable, not after.

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

@@ -0,0 +1,74 @@
+# Routing
+
+## Rule
+
+Hold the native splash screen until the session has been read from `expo-secure-store`. Only then let the
+router render the authenticated group or redirect to login.
+
+Express protection with an authenticated layout group. Do not check for a session inside a screen.
+
+When a deep link targets a protected route without a session, keep the intended destination **in memory**
+and navigate to it after a successful login. Do not persist it.
+
+Enable `experiments.typedRoutes`. Use absolute paths in every navigation.
+
+Let the navigation shape (how many tabs, which stacks) follow the product. It is not a convention.
+
+## Rationale
+
+On the web the cookie travels with every request and the server decides, so the client is never in doubt.
+On mobile the session lives in secure storage and reading it is asynchronous, so every cold start has a
+moment where nothing is known yet.
+
+**MMKV persists across launches, which makes that moment dangerous rather than merely untidy.** A
+protected screen rendering before the decision can show cached data from the **previous user** for a
+fraction of a second. Holding the splash costs nothing in perception (it is already a native, expected
+moment) while the alternative flash reads as a defect and can show somebody else's data.
+
+Checking inside each screen fails differently: the screen written tomorrow does not check.
+
+A dropped deep-link destination is the most common reason a notification link "does not work": the person
+taps a specific order, signs in, and lands on the home screen with the order to find by hand. Keeping the
+destination in memory rather than on disk matters because `orders/123` describes intent: it says the order
+exists and that this person wanted it. That value is useful for seconds and should not outlive the
+process. Somebody who closed the app midway through login is not returning expecting to resume.
+
+Typed routes are beta, and are enabled because the gain is correctness rather than appearance: a wrong
+`href` is broken navigation, not an untidy string. The web app gained end-to-end route typing from its own
+router; without this, the same typo compiles here and fails there.
+
+## Applies to
+
+Every file under `app/`, and the bootstrap that controls the splash.
+
+## Examples
+
+Protection:
+
+```
+✅  app/(app)/_layout.tsx        → resolves the session, then renders or redirects
+    app/(app)/orders.tsx
+❌  app/orders.tsx               → if (!session) router.replace('/login')
+```
+
+Navigation:
+
+```
+✅  router.push('/orders/123')
+❌  router.push('../orders/123')   // relative paths are not typed
+```
+
+## Enforcement
+
+**Structural.** A screen inside the authenticated group cannot skip the check, because the layout resolves
+before it renders.
+
+**Compiler.** Typed routes reject a misspelled path and a missing or wrongly typed param.
+
+**Review only.** That the splash is released only after the session resolves, and that a deep-link
+destination is not written to storage.
+
+**An asymmetry with the web area, recorded so nobody corrects it:** there, the generated route tree is
+committed, because without it a clean clone does not typecheck. Here `expo-env.d.ts` is generated and
+gitignored, which is Expo's own convention. That file is the framework's territory, and fighting its
+default `.gitignore` creates friction on every upgrade.