gemi 0.58.1 → 0.60.0

package/dist/services/logging/LogManager.d.ts

@@ -6,13 +6,22 @@ export declare class LogManager {
     static token: string;
     writer: FileSink;
     isReady: boolean;
-    private logsDirPath;
     private flushTimeout;
     private fileSize;
     private writerSize;
     private isCreatingFile;
     private bootPromise;
     currentLogFilePath: string;
+    /**
+     * Computed per read, not once in the constructor: `Server.start` awaits
+     * `waitForBoot()` — where `LogServiceProvider.boot()` builds this directory —
+     * and only *then* imports the http layer that sets `ROOT_DIR`. A field
+     * initializer (or any `process.env.ROOT_DIR` read here) resolves to
+     * `undefined/storage/logs` at boot, which is how every `Log.info()` ended up
+     * throwing on an undefined writer. `projectRoot()` is the same rule
+     * `httpProd` sets `ROOT_DIR` from, a moment later.
+     */
+    private get logsDirPath();
     constructor(config: Required<LogConfig>);
     /**
      * Idempotent. `LogServiceProvider.boot()` calls this so the storage

package/dist/services/logging/LogManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LogManager.d.ts","sourceRoot":"","sources":["../../../services/logging/LogManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAYpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,SAAS,CAAC;AAElD,qBAAa,UAAU;IAcF,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAb9C,MAAM,CAAC,KAAK,SAAS;IAErB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,OAAO,CAAS;IAEzB,OAAO,CAAC,WAAW,CAAkD;IACrE,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,WAAW,CAA8B;IAC1C,kBAAkB,EAAE,MAAM,CAAC;gBAEf,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAE9C;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YASP,aAAa;IAarB,UAAU;IAgDV,GAAG,CACP,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;IA8C9B,QAAQ;CAkBf"}
+{"version":3,"file":"LogManager.d.ts","sourceRoot":"","sources":["../../../services/logging/LogManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAapC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,SAAS,CAAC;AAElD,qBAAa,UAAU;IA0BF,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAzB9C,MAAM,CAAC,KAAK,SAAS;IAErB,MAAM,EAAE,QAAQ,CAAC;IACjB,OAAO,EAAE,OAAO,CAAS;IAEzB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,WAAW,CAA8B;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAElC;;;;;;;;OAQG;IACH,OAAO,KAAK,WAAW,GAEtB;gBAEkB,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC;IAE9C;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBP,aAAa;IAWrB,UAAU;IAgDV,GAAG,CACP,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;IAqE9B,QAAQ;CAkBf"}

package/dist/services/logging/LogServiceProvider.d.ts

@@ -7,6 +7,16 @@ export declare class LogServiceProvider extends ServiceProvider {
      * Resolving here is deliberate: it is the one service whose readiness is a
      * boot-time side effect, and paying for it lazily mid-request would add file
      * IO to whichever handler happened to log first.
+     *
+     * Only for a process that is serving, though. `runConsole` boots these same
+     * providers for every command, as does a migration or a test with a Kernel,
+     * and preparing a log file is not free: a `mkdir`, a `readdir`, and — when
+     * the newest file still has room — reading its whole text back into a fresh
+     * writer, up to `maxFileSize` (10MB by default), in whatever directory the
+     * process was started from. `ROOT_DIR` is what `Server.start` sets and
+     * nothing else does. Those contexts stay lazy rather than silent: a command
+     * that actually logs still gets its file, because `LogManager.log()` boots
+     * the manager on first use.
      */
     boot(): Promise<void>;
 }

package/dist/services/logging/LogServiceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LogServiceProvider.d.ts","sourceRoot":"","sources":["../../../services/logging/LogServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAKhE,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,QAAQ;IAaR;;;;;;OAMG;IACG,IAAI;CAGX"}
+{"version":3,"file":"LogServiceProvider.d.ts","sourceRoot":"","sources":["../../../services/logging/LogServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAKhE,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,QAAQ;IAaR;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI;CAMX"}

package/dist/support/index.js

@@ -1,4 +1,4 @@
 // @bun
-import{Sb as S,Tb as U,Ub as V,Vb as W}from"../chunk-fjm4y8bn.js";import{Yb as Y}from"../chunk-4yt5x8s2.js";import{qf as R}from"../chunk-sy7jbdeb.js";import{Af as q,yf as F}from"../chunk-d125j8t0.js";import"../chunk-dgsgjg53.js";import"../chunk-jhkjz9jr.js";class v{static token;async boot(){}static inject(){if(!this.token)throw Error(`Service [${this.name}] does not declare a \`static token\`, so the container has no key to resolve it by.`);try{return q(this)}catch(x){throw Error(`Could not inject [${this.name}]. Services are constructed when the kernel boots, so `+"inject() only works from code that runs after that \u2014 a constructor default or a method "+`body, never module top level. Check that [${this.name}] is listed in \`services\` on your Kernel.`,{cause:x})}}static with(x){let f=new this;for(let[C,g]of Object.entries(x))if(g!==void 0)f[C]=g;return f}}import{readdir as H}from"fs/promises";import{join as J,parse as z}from"path";var L=[".ts",".tsx",".js",".mjs",".jsx"];function M(x={}){let f={};for(let[C,g]of Object.entries(x))f[C]=B(g);return new F(f)}async function Q(x,f=new F){let C=[];try{C=await H(x)}catch(D){return f}let g=C.filter((D)=>{let{ext:P,name:j}=z(D);return L.includes(P)&&!j.startsWith(".")}).sort();for(let D of g){let{name:P}=z(D),j=await import(J(x,D));f.set(P,B(j))}return f}function B(x){if(x&&typeof x==="object"&&"default"in x)return x.default;return x}export{R as withDefaults,S as sourceFiles,W as projectRoot,Q as loadConfigFrom,V as discoverClasses,M as createConfigRepository,Y as ServiceProvider,v as Service,F as Repository,U as DiscoveryError};
+import{Ub as Y}from"../chunk-ys904esh.js";import{nf as R}from"../chunk-3296fwss.js";import{vf as F,xf as q}from"../chunk-tds3xq6b.js";import"../chunk-j23cengk.js";import{Af as S,Bf as U,Cf as V,Df as W}from"../chunk-hxb1eg2z.js";import"../chunk-4dan69s4.js";class v{static token;async boot(){}static inject(){if(!this.token)throw Error(`Service [${this.name}] does not declare a \`static token\`, so the container has no key to resolve it by.`);try{return q(this)}catch(x){throw Error(`Could not inject [${this.name}]. Services are constructed when the kernel boots, so `+"inject() only works from code that runs after that \u2014 a constructor default or a method "+`body, never module top level. Check that [${this.name}] is listed in \`services\` on your Kernel.`,{cause:x})}}static with(x){let f=new this;for(let[C,g]of Object.entries(x))if(g!==void 0)f[C]=g;return f}}import{readdir as H}from"fs/promises";import{join as J,parse as z}from"path";var L=[".ts",".tsx",".js",".mjs",".jsx"];function M(x={}){let f={};for(let[C,g]of Object.entries(x))f[C]=B(g);return new F(f)}async function Q(x,f=new F){let C=[];try{C=await H(x)}catch(D){return f}let g=C.filter((D)=>{let{ext:P,name:j}=z(D);return L.includes(P)&&!j.startsWith(".")}).sort();for(let D of g){let{name:P}=z(D),j=await import(J(x,D));f.set(P,B(j))}return f}function B(x){if(x&&typeof x==="object"&&"default"in x)return x.default;return x}export{R as withDefaults,S as sourceFiles,W as projectRoot,Q as loadConfigFrom,V as discoverClasses,M as createConfigRepository,Y as ServiceProvider,v as Service,F as Repository,U as DiscoveryError};
 
-//# debugId=C2E9E4E1217608F664756E2164756E21
+//# debugId=7CF7DE923F6BD77064756E2164756E21

package/dist/support/index.js.map

@@ -6,6 +6,6 @@
     "import { readdir } from \"node:fs/promises\";\nimport { join, parse } from \"node:path\";\n\nimport { Repository } from \"./Repository\";\n\nconst CONFIG_EXTENSIONS = [\".ts\", \".tsx\", \".js\", \".mjs\", \".jsx\"];\n\n// Builds a Repository from an already-imported map of config modules. The map\n// key becomes the top-level config key, so `{ mail: mailModule }` is readable\n// as `config.get(\"mail.driver\")`. Each entry may be either the module namespace\n// (its `default` export is unwrapped) or the config object itself.\nexport function createConfigRepository(\n  modules: Record<string, any> = {},\n): Repository {\n  const items: Record<string, any> = {};\n\n  for (const [key, mod] of Object.entries(modules)) {\n    items[key] = unwrap(mod);\n  }\n\n  return new Repository(items);\n}\n\n// Reads every config module in an app's `app/config` directory into a\n// Repository. The file's basename is the top-level key: `app/config/mail.ts`\n// populates `mail.*`. A missing directory yields an empty Repository so apps\n// that declare no config still boot.\nexport async function loadConfigFrom(\n  directory: string,\n  repository = new Repository(),\n): Promise<Repository> {\n  let entries: string[] = [];\n\n  try {\n    entries = await readdir(directory);\n  } catch (err) {\n    return repository;\n  }\n\n  const files = entries\n    .filter((entry) => {\n      const { ext, name } = parse(entry);\n      return CONFIG_EXTENSIONS.includes(ext) && !name.startsWith(\".\");\n    })\n    .sort();\n\n  for (const file of files) {\n    const { name } = parse(file);\n    const mod = await import(join(directory, file));\n    repository.set(name, unwrap(mod));\n  }\n\n  return repository;\n}\n\nfunction unwrap(mod: any) {\n  if (mod && typeof mod === \"object\" && \"default\" in mod) {\n    return mod.default;\n  }\n  return mod;\n}\n"
   ],
   "mappings": ";2RAgCO,CAAe,JAAQ,EAOrB,OAMD,AAAI,EAAkB,QAmBrB,OAAS,EAKX,CACH,GAAI,CAAC,KAAK,MACR,MAAU,MACR,YAAY,KAAK,0FACnB,EAGF,GAAI,CACF,OAAO,EAAI,IAAuB,EAClC,MAAO,EAAO,CACd,MAAU,MACR,qBAAqB,KAAK,6DACxB,+FACA,6CAA6C,KAAK,kDAEpD,CAAE,OAAM,CACV,SAoBG,KAAuB,CAAoB,EAA0B,CAC1E,IAAM,EAAW,IAAI,KACrB,QAAY,EAAK,KAAU,OAAO,QAAQ,CAAS,EACjD,GAAI,IAAU,OAAW,EAAS,GAAO,EAE3C,OAAO,EAEX,CChHA,kBAAS,oBACT,eAAS,WAAM,aAIf,IAAM,EAAoB,CAAC,MAAO,OAAQ,MAAO,OAAQ,MAAM,EAMxD,SAAS,CAAsB,CACpC,EAA+B,CAAC,EACpB,CACZ,IAAM,EAA6B,CAAC,EAEpC,QAAY,EAAK,KAAQ,OAAO,QAAQ,CAAO,EAC7C,EAAM,GAAO,EAAO,CAAG,EAGzB,OAAO,IAAI,EAAW,CAAK,EAO7B,eAAsB,CAAc,CAClC,EACA,EAAa,IAAI,EACI,CACrB,IAAI,EAAoB,CAAC,EAEzB,GAAI,CACF,EAAU,MAAM,EAAQ,CAAS,EACjC,MAAO,EAAK,CACZ,OAAO,EAGT,IAAM,EAAQ,EACX,OAAO,CAAC,IAAU,CACjB,IAAQ,MAAK,QAAS,EAAM,CAAK,EACjC,OAAO,EAAkB,SAAS,CAAG,GAAK,CAAC,EAAK,WAAW,GAAG,EAC/D,EACA,KAAK,EAER,QAAW,KAAQ,EAAO,CACxB,IAAQ,QAAS,EAAM,CAAI,EACrB,EAAM,MAAa,SAAK,EAAW,CAAI,GAC7C,EAAW,IAAI,EAAM,EAAO,CAAG,CAAC,EAGlC,OAAO,EAGT,SAAS,CAAM,CAAC,EAAU,CACxB,GAAI,GAAO,OAAO,IAAQ,UAAY,YAAa,EACjD,OAAO,EAAI,QAEb,OAAO",
-  "debugId": "C2E9E4E1217608F664756E2164756E21",
+  "debugId": "7CF7DE923F6BD77064756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemi",
-  "version": "0.58.1",
+  "version": "0.60.0",
   "private": false,
   "license": "MIT",
   "author": "Enes Tufekci <enes@gemijs.dev>",
@@ -15,7 +15,8 @@
   },
   "files": [
     "dist/**/*",
-    "ide/typescript-plugin/package.json"
+    "ide/typescript-plugin/package.json",
+    "skills/**/*"
   ],
   "module": true,
   "exports": {

package/skills/gemi-react-best-practices/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: gemi-react-best-practices
+description: Best practices for the gemi framework (Bun + Vite + React 19 SSR full-stack TypeScript framework) — routing, controllers, the ORM, the SSR data payload, useQuery, i18n, jobs/services, and testing. Use when writing, reviewing, or refactoring anything under app/ — views, routers, controllers, models, dictionaries — or when a task mentions slow pages, extra round-trips, N+1 queries, bundle size, or re-renders.
+---
+
+# gemi Best Practices
+
+Rules for building on **gemi**, the full-stack TypeScript framework this app runs on
+(Bun + Vite, React 19 SSR). 45 rules across 11 categories, ordered by impact.
+
+Every rule is derived from the gemi documentation and from patterns that recur across
+gemi codebases. This skill ships with the `gemi` package, so it describes the
+framework; where it and your app disagree, your app wins (ground rule 2).
+
+## When to Apply
+
+- Adding or changing a route, view, layout, controller, or middleware
+- Writing a `useQuery` read, a mutation, or a `Query.prefetch`
+- Writing ORM queries — especially list reads, aggregations, and transactions
+- Adding a Job, Service, or one-off Command
+- Writing dictionaries or tests
+- Diagnosing extra round-trips, slow first paint, blank flashes, or bundle growth
+
+## Ground Rules That Precede Everything Below
+
+1. **Fetch the docs; do not guess an API.** Index (page list + one-line summaries):
+   <https://nstfkc.github.io/gemi/llms.txt> — fetch only the pages you need.
+   Everything in one file: <https://nstfkc.github.io/gemi/llms-full.txt> (~170 KB).
+2. **`CLAUDE.md` in this app wins** where it and either the docs or this skill
+   disagree — it describes *our* app, not the framework in general.
+3. **Mirror existing code.** Don't invent gemi patterns. When a rule here and an
+   existing pattern disagree, check git history before "fixing" it.
+4. **Routing is class-based and data is loaded in controllers.** File location
+   registers nothing; a view's file name has no relation to its URL.
+5. **Check whether the React Compiler is on before hand-memoizing.** It is enabled
+   per app in `gemi.config.ts` via the React plugin's `compiler` option, which the
+   gemi template turns on by default — and `GEMI_REACT_COMPILER=off` in the
+   environment disables it, so the config is not the last word. With it on, the client build is
+   auto-memoized and a hand-written `useMemo` is usually redundant; with it off,
+   memoization is manual and load-bearing. The compiler never runs on the SSR view
+   build — server rendering is a single pass — so it changes nothing about what a
+   controller does.
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 0 | Project Structure | HIGH | `structure-` |
+| 1 | Server Payload & Waterfalls | CRITICAL | `payload-` |
+| 2 | Client Data Fetching | CRITICAL | `query-` |
+| 3 | Data Access (ORM) | HIGH | `orm-` |
+| 4 | Routing & Middleware | HIGH | `routing-` |
+| 5 | Controllers & Request Handling | HIGH | `controller-` |
+| 6 | Services, Jobs & Commands | HIGH | `service-` |
+| 7 | Client Components & Navigation | MEDIUM | `client-` |
+| 8 | Bundle Size | MEDIUM | `bundle-` |
+| 9 | Internationalization | MEDIUM | `i18n-` |
+| 10 | Testing | MEDIUM | `testing-` |
+
+## Project Structure
+
+Everything the framework guarantees lives under `app/`. This is the layout a
+scaffolded project has; the parts marked *discovered* are read by walking the
+directory, so writing the file is the registration.
+
+```
+app/
+  server.ts            server entry - boots the kernel, starts the HTTP server
+  client.tsx           browser entry - hydrates the React app
+  preload.ts           optional Bun preload, runs before the server starts
+  kernel/Kernel.ts     declares `config`, `providers`, and `models`
+  config/              runtime config, one file per framework service
+  providers/           your own container bindings
+  http/
+    routes/            api.ts and view.ts - the root routers
+    controllers/       controller classes
+    requests/          HttpRequest subclasses used for validation
+  models/              ORM models  (declared on the Kernel)
+    generated/         OUTPUT - never hand-edit
+  views/               React views, layouts, RootLayout  (path is NOT the URL)
+  email/               jsx-email templates
+  i18n/                dictionaries
+  cron/                CronJob classes        <- discovered at boot
+  jobs/                Job classes            <- discovered at boot
+  listeners/           Listener classes       <- discovered at boot
+  commands/            defineCommand chains   <- discovered by `gemi run`
+  database/prisma.ts   the Prisma client instance
+```
+
+`app/listeners/` is absent from a fresh scaffold; that is not an error, it means
+the app has no listeners yet.
+
+### Where a new file goes
+
+| Adding a… | Goes in | Reached by |
+|---|---|---|
+| page / layout | `app/views/` | a **router**, never its file path |
+| URL, or middleware on one | `app/http/routes/` | mounted from `view.ts` / `api.ts` |
+| handler logic for a route | `app/http/controllers/` | named by a router |
+| request validation | `app/http/requests/` | named by a controller method |
+| ORM model | `app/models/` | the Kernel's `models` |
+| background work | `app/jobs/` | discovery |
+| scheduled work | `app/cron/` | discovery |
+| event handler | `app/listeners/` | discovery |
+| one-off ops task | `app/commands/` | discovery, via `gemi run` |
+| anything with I/O, a client, or state | `app/services/` | the container, by `static token` |
+| container bindings | `app/providers/` | the Kernel's `providers` |
+| settings for a framework service | `app/config/` | the Kernel's `config` |
+| translations | `app/i18n/` | `defineDictionary` |
+| build config (Vite/Bun plugins) | `gemi.config.ts` **at the root** | the CLI — *not* `app/config/` |
+
+Two mistakes this table exists to prevent, both of which typecheck and then do
+nothing: putting a view at a path that looks like its URL and expecting it to
+route, and writing a model without declaring it on the Kernel. See
+`structure-discovered-vs-registered` and `structure-do-not-reinvent-the-framework`.
+
+## Quick Reference
+
+### 0. Project Structure (HIGH)
+
+- `structure-discovered-vs-registered` - Four directories register by being walked; models, routers, config and providers are declared
+- `structure-do-not-reinvent-the-framework` - `lib/`, a singleton, a hand-rolled registry: gemi already has each of these with a name
+
+### 1. Server Payload & Waterfalls (CRITICAL)
+
+The biggest lever in the app. gemi ships a data payload with the SSR HTML; every read
+the client discovers only after hydration costs a round-trip the payload could have
+carried for free.
+
+- `payload-prefetch-mirrors-usequery` - A prefetch lands only if path + params + search match the cache key exactly
+- `payload-prefetch-late-queries` - Prefetch reads render discovers late (nested under suspense, conditionally rendered)
+- `payload-instant-vs-prefetch` - `Query.instant` blocks the response; `Query.prefetch` runs in parallel
+- `payload-parallel-controller-work` - `Promise.all` independent work in a controller method
+- `payload-dont-overprefetch` - Popover and heavy-collection reads belong behind a mount gate
+- `payload-minimal-view-props` - Ship the shape the view renders, not the row you loaded
+
+### 2. Client Data Fetching (CRITICAL)
+
+- `query-no-hand-rolled-fetch` - `useQuery` / mutation hooks, never a raw `fetch`
+- `query-suspense-default` - `suspense: true` is the DEFAULT and throws to the nearest boundary
+- `query-lazy-vs-mount-gate` - A lazy query does not refetch when its variant changes
+- `query-share-cache-key` - Identical path + params + search dedupes across components for free
+- `query-keep-previous-data` - Keep the previous page rendered while the next variant loads
+- `query-mutate-over-refetch` - Write the cache with `mutate` / `useMutate` instead of refetching
+- `query-debounce-search-variant` - Debounce a value before it becomes a query variant
+- `query-revalidate-on-focus` - Opt in only for cross-tab-mutable data; let `staleTime` gate it
+
+### 3. Data Access — ORM (HIGH)
+
+- `orm-include-not-n-plus-one` - One `include` tree beats a loop of queries (lateral strategy = one round trip)
+- `orm-transaction-sequential` - `Promise.all` inside `Model.transaction` is unsafe — one reserved connection
+- `orm-transaction-no-io` - Keep network calls, uploads and queue pushes out of a transaction callback
+- `orm-analytics-connection` - Heavy admin/cron aggregations run on the analytics pool
+- `orm-paginate-helper` - Use `paginate()` from `gemi/orm`; know its 100-row ceiling
+- `orm-select-narrow` - `select` the columns the response actually serializes
+- `orm-plain-rows-by-default` - Plain rows are free; `track` costs ~100% on a large read
+
+### 4. Routing & Middleware (HIGH)
+
+- `routing-routers-are-classes` - Routes are declared on router classes, not by file location
+- `routing-middleware-dsl` - Middleware is a string DSL at router or route level; `-name` cancels
+- `routing-cache-policy-constants` - Name cache policies once and reuse the constant
+- `routing-resource-routes` - `resource()` for standard REST, with per-method middleware
+
+### 5. Controllers & Request Handling (HIGH)
+
+- `controller-request-schema` - Validate with a request schema, not inline checks
+- `controller-throw-framework-errors` - Throw `ValidationError` / auth errors; never invent a response shape
+- `controller-redirect-facade-throws` - Never wrap the `Redirect` facade in try/catch — it works by throwing
+- `controller-authorize-every-tenant-read` - Scope every tenant read, in middleware or an ORM policy
+- `controller-parse-request-at-the-boundary` - Parse the request in the controller; keep utils framework-free
+
+### 6. Services, Jobs & Commands (HIGH)
+
+- `service-static-token-and-name` - `static token` / `static name` survive minification; class names do not
+- `service-queue-is-in-memory` - The queue is in-process; enqueued work is lost on restart
+- `service-lazy-not-module-scope` - Construct clients lazily — discovery imports every module
+
+### 7. Client Components & Navigation (MEDIUM)
+
+- `client-typed-links` - Navigate with a typed `Link` / `useNavigate`, not an interpolated path
+- `client-form-vs-mutation-hooks` - `<Form>` first; mutation hooks when you need control
+- `client-loading-error-exports` - A route module's `Loading` / `Error` exports ARE its suspense boundary
+- `client-no-effect-data-flow` - Derive in `useMemo`, reset in the handler, debounce before use
+
+### 8. Bundle Size (MEDIUM)
+
+- `bundle-deep-imports` - Import UI primitives by deep path; a barrel drags the whole library in
+- `bundle-mount-gate-heavy-panels` - Put heavy subtrees inside the thing that unmounts them
+
+### 9. Internationalization (MEDIUM)
+
+- `i18n-define-dictionary-inline` - The `defineDictionary` literal must be inline — a helper fails the BUILD
+
+### 10. Testing (MEDIUM)
+
+- `testing-page-seeds-real-inputs` - Mount with `<Page>` from `gemi/testing`; never mock `gemi/client`
+- `testing-assert-behaviour-over-markup` - Query the DOM; don't scrape `renderToStaticMarkup` output
+- `testing-match-the-suite` - Copy the runner and naming already in the directory; component tests need a DOM
+
+## The Gotchas Most Likely to Bite
+
+Counter-intuitive behaviours that produce silent failures rather than errors:
+
+| Gotcha | Rule |
+|---|---|
+| `Redirect` works by **throwing** — a `try/catch` swallows it | `controller-redirect-facade-throws` |
+| A `defineDictionary` behind a helper passes tests and fails the **build** | `i18n-define-dictionary-inline` |
+| `Promise.all` inside a transaction shares one reserved connection | `orm-transaction-sequential` |
+| A lazy query never refetches when its variant changes | `query-lazy-vs-mount-gate` |
+| A prefetch whose `search` differs primes a slot nothing reads | `payload-prefetch-mirrors-usequery` |
+| A class name is minified in prod — jobs and services need a static string | `service-static-token-and-name` |
+| `paginate()` silently caps `perPage` at 100 | `orm-paginate-helper` |
+| Command discovery **imports** every file under `app/commands` | `service-lazy-not-module-scope` |
+| A suspending query blanks everything up to the nearest boundary | `query-suspense-default` |
+| Returning `{ error }` from a controller is a **200** the client reads as success | `controller-throw-framework-errors` |
+
+## How to Use
+
+Read a rule file for the full explanation and examples:
+
+```
+rules/payload-prefetch-mirrors-usequery.md
+rules/orm-transaction-sequential.md
+```
+
+Each contains a short why, an incorrect example, a correct example, and — where one
+exists — a link to the gemi documentation page that covers it.
+
+`rules/_sections.md` holds the category metadata; `rules/_template.md` is the shape a
+new rule follows.

package/skills/gemi-react-best-practices/rules/_sections.md

@@ -0,0 +1,56 @@
+# Sections
+
+The section ID (in parentheses) is the filename prefix used to group rules.
+Rules are sorted by title within a section. Files starting with `_` are not rules.
+
+---
+
+## 1. Server Payload & Waterfalls (payload)
+
+**Impact:** CRITICAL
+**Description:** gemi renders on the server and ships a data payload with the HTML. Every read the client discovers only after hydration costs a full round-trip the payload could have carried. This is the largest lever in the app.
+
+## 2. Client Data Fetching (query)
+
+**Impact:** CRITICAL
+**Description:** `useQuery` defaults (suspense on, keepPreviousData on, 5s staleTime, focus revalidation off) are opinionated. Fighting them — or not knowing them — produces blank flashes, dead pagination, and duplicate requests.
+
+## 3. Data Access — ORM (orm)
+
+**Impact:** HIGH
+**Description:** The ORM is Prisma-typed but gemi-executed, with its own relation-loading strategies, transaction semantics, connection selection, and row-provenance model. Its constraints are not Prisma's.
+
+## 4. Routing & Middleware (routing)
+
+**Impact:** HIGH
+**Description:** Routing is class-based: routers declare a routes object, and middleware attaches as a string DSL. This is where a URL, its cache policy, and its auth boundary are all defined.
+
+## 5. Controllers & Request Handling (controller)
+
+**Impact:** HIGH
+**Description:** Controllers hold server logic and own the request boundary — validation, authorization, error shape. The client's error handling is a contract with what a controller throws.
+
+## 6. Services, Jobs & Commands (service)
+
+**Impact:** HIGH
+**Description:** Long-lived singletons, background work, and one-off ops. Most failures here are invisible in development and appear only in the production build or on a restart.
+
+## 7. Client Components & Navigation (client)
+
+**Impact:** MEDIUM
+**Description:** React 19 SSR with hydration. Typed navigation, forms, suspense boundaries declared by route module exports, and data flow that does not go through effects.
+
+## 8. Bundle Size (bundle)
+
+**Impact:** MEDIUM
+**Description:** Vite code-splits per route chunk. Client cost is determined by which module graph a route pulls in and where a heavy subtree is mounted.
+
+## 9. Internationalization (i18n)
+
+**Impact:** MEDIUM
+**Description:** Two dictionary systems coexist. The newer one is rewritten at build time by a Vite plugin, which constrains how it may be written.
+
+## 10. Testing (testing)
+
+**Impact:** MEDIUM
+**Description:** Views mount for real with seeded framework inputs, through `<Page>` from `gemi/testing`. Match whichever runner and naming convention the directory already uses — a test the runner never selects is a test that does not exist.

package/skills/gemi-react-best-practices/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

package/skills/gemi-react-best-practices/rules/bundle-deep-imports.md

@@ -0,0 +1,48 @@
+---
+title: Import UI Primitives By Deep Path
+impact: HIGH
+impactDescription: keeps a component library's dependencies out of routes that do not use it
+tags: bundle, imports, barrel, ui
+---
+
+## Import UI Primitives By Deep Path
+
+A component library where every primitive is its own module — the shadcn/ui shape,
+and the shape most in-repo `packages/ui` workspaces take — should be imported by deep
+path. A route then pulls in exactly the primitives it uses.
+
+A barrel import, or adding a barrel that re-exports everything, pulls the whole
+library and its transitive dependencies (for a Radix-based kit, ~25 packages) into
+every route that touches one button. Tree-shaking does not reliably save you here:
+the library is often source-only with no build step, and a single side-effecting
+module in the barrel's graph defeats it.
+
+**Incorrect (drags the library in):**
+
+```tsx
+import { Button, Input, Badge } from "@acme/ui";
+```
+
+**Correct (one module each):**
+
+```tsx
+import { Button } from "@acme/ui/components/ui/button";
+import { Input } from "@acme/ui/components/ui/input";
+import { Badge } from "@acme/ui/components/ui/badge";
+import { cn } from "@acme/ui/lib/utils";
+```
+
+**Do not add a barrel** to make the imports shorter. The deep paths are the
+mechanism, not a style preference.
+
+Two related notes:
+
+- **Check whether your repo has a legacy copy.** A local `app/views/components/ui`
+  alongside a shared `packages/ui` means two divergent sets of the same primitives;
+  pick the shared one and say so in `CLAUDE.md`.
+- **Keep import paths statically analyzable.** A computed specifier defeats
+  tree-shaking and widens what the build has to trace.
+
+This matters more under gemi than under a bundler that ships one chunk: each view is
+its own build entry (`preserveEntrySignatures: "strict"`), so a barrel import in one
+view inflates that view's chunk and every chunk that shares its graph.

package/skills/gemi-react-best-practices/rules/bundle-mount-gate-heavy-panels.md

@@ -0,0 +1,63 @@
+---
+title: Put Heavy Subtrees Inside the Thing That Unmounts Them
+impact: HIGH
+impactDescription: ~47 kB and two queries off the initial load, measured
+tags: bundle, mounting, radix, queries
+---
+
+## Put Heavy Subtrees Inside the Thing That Unmounts Them
+
+The cheapest work is work that never mounts. **Let an unmounted subtree be the
+gate**: Radix `PopoverContent`, `DialogContent`,
+`DropdownMenuContent` and the tab primitives do not render their children while
+closed. A component placed inside them costs nothing until the user opens the thing.
+
+Hoisting a query or a heavy component *above* that boundary "to keep the parent
+tidy" is how it starts running on every page load for a panel nobody opened. In this
+app that cost ~47 kB resolved across two reads, on every load of the customer app.
+
+**Incorrect (reads run on every page load to fill a closed popover):**
+
+```tsx
+function ProductPicker() {
+  const { data: products } = useQuery("/app/:orgId/products/search", { params });
+  const { data: lists } = useQuery("/app/:orgId/lists", { params });
+
+  return (
+    <Popover>
+      <PopoverTrigger>Add product</PopoverTrigger>
+      <PopoverContent>
+        <CatalogSearchPanel products={products} lists={lists} />
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+**Correct (the reads move down, inside the content Radix unmounts):**
+
+```tsx
+function ProductPicker() {
+  return (
+    <Popover>
+      <PopoverTrigger>Add product</PopoverTrigger>
+      <PopoverContent>
+        <CatalogSearchPanel orgId={orgId} />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+function CatalogSearchPanel({ orgId }: { orgId: string }) {
+  const { data: products = [] } = useQuery(/* … */, { suspense: false });
+  const { data: lists = [] } = useQuery(/* … */, { suspense: false });
+}
+```
+
+**Why mounting rather than `{ lazy: true }`:** a lazy query does not refetch when
+its variant changes, so a searchable or paginated read breaks under it — see
+`query-lazy-vs-mount-gate`.
+
+**For a genuinely heavy module** (a chart library, an editor, a PDF renderer) plain
+`React.lazy` + `Suspense` is the right tool; gemi ships no wrapper of its own for
+it, and none is needed.

package/skills/gemi-react-best-practices/rules/client-form-vs-mutation-hooks.md

@@ -0,0 +1,57 @@
+---
+title: Reach for Form First, Mutation Hooks When You Need Control
+impact: MEDIUM
+impactDescription: CSRF, FormData and field errors for free
+tags: client, forms, mutations, validation
+---
+
+## Reach for Form First, Mutation Hooks When You Need Control
+
+`<Form>` wraps a native form and handles what is otherwise hand-written every time:
+collecting fields into `FormData`, attaching the CSRF token, tracking pending state,
+and exposing the server's per-field `validation_error` messages through context.
+
+**Incorrect (re-implementing all of it, and losing field errors):**
+
+```tsx
+const { trigger, loading } = usePost("/admin/user");
+const [name, setName] = useState("");
+const [errors, setErrors] = useState({});
+
+async function onSubmit(e) {
+  e.preventDefault();
+  const res = await trigger({ name });
+  if (res?.error?.kind === "validation_error") setErrors(res.error.messages);
+}
+```
+
+**Correct:**
+
+```tsx
+import { Form, ValidationErrors } from "gemi/client";
+
+<Form action="/admin/user" method="POST"
+      onSuccess={(_data, form) => { form.reset(); push("/admin/users"); }}>
+  <input name="name" />
+  <ValidationErrors name="name" />
+  <FormError />
+  <button type="submit">Create</button>
+</Form>;
+```
+
+Inside a `Form`, three hooks read its context: `useFormStatus()`
+(`{ isPending, validationErrors, formError }`), `useMutationStatus()`
+(`{ isPending }`), and `useFormData()` for live `FormData` as the user types. The
+form also carries a `data-loading` attribute for styling.
+
+**Use the mutation hooks (`usePost` / `usePut` / `usePatch` / `useDelete`) when the
+write is not a form submission** — a button that toggles a flag, an action in a menu,
+an optimistic list operation. Pair them with `useMutate` to update the reading
+query's cache rather than refetching.
+
+**File posts that need to be unit-testable use `usePost` with `FormData`.**
+`useUpload` is XHR-based, which is what gives it progress events and also what makes
+it uninterceptable by MSW under happy-dom — reach for it only when you need the
+progress bar.
+
+Reference: <https://nstfkc.github.io/gemi/forms.md>

package/skills/gemi-react-best-practices/rules/client-loading-error-exports.md

@@ -0,0 +1,54 @@
+---
+title: A Route Module's Loading and Error Exports Are Its Suspense Boundary
+impact: MEDIUM
+impactDescription: correct fallback placement, no full-page blanking
+tags: render, suspense, ssr, boundaries
+---
+
+## A Route Module's Loading and Error Exports Are Its Suspense Boundary
+
+A view module declares its own suspense boundary by exporting `Loading` and
+`Error` **alongside** its default export — there is no separate file convention for
+either. Since
+`useQuery` suspends by default (`query-suspense-default`), a route with no `Loading`
+export falls back to whatever boundary happens to be above it — often a bare
+`<Suspense fallback={null}>`, which blanks the surface.
+
+**Incorrect (no boundary of its own; suspending blanks whatever is above):**
+
+```tsx
+export default function Todos() {
+  const { data } = useQuery("/todos");
+  return <ul>{data.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+**Correct:**
+
+```tsx
+export default function Todos() {
+  const { data } = useQuery("/todos");
+  return <ul>{data.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+
+export function Loading() {
+  return <TodosSkeleton />;
+}
+
+export function Error({ error, resetErrorBoundary }) {
+  return <button onClick={() => resetErrorBoundary()}>Retry</button>;
+}
+```
+
+**Place the boundary where the blank is acceptable.** A route-level `Loading` is
+right for the route's primary read. For a secondary widget, do not add a boundary —
+give that query `{ suspense: false }` and render its loading state in place, so the
+rest of the page keeps its content.
+
+**Do not hand-roll a navigation spinner.** gemi already commits navigations in a
+transition, keeping the previous page visible until the new page's queries resolve,
+and the production shell preloads the chunks in the current route's component chain.
+`Link` sets `data-pending` during navigation if you want to style the transition —
+reach for that before adding state.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>