gemi 0.58.1 → 0.60.0

package/skills/gemi-react-best-practices/rules/query-lazy-vs-mount-gate.md

@@ -0,0 +1,54 @@
+---
+title: A Lazy Query Does Not Refetch When Its Variant Changes
+impact: HIGH
+impactDescription: prevents silently dead search and pagination
+tags: query, lazy, correctness, mounting
+---
+
+## A Lazy Query Does Not Refetch When Its Variant Changes
+
+`{ lazy: true }` defers a query until `trigger()` or `refetch()` is called. It is the
+right tool for a read that fires on an explicit user action with **fixed** inputs.
+
+It is the wrong tool for a read whose key changes — search text, page size, filters.
+A lazy query does not refetch when its variant changes, so search and "load more"
+keep rendering the first triggered result and appear to be broken. Nothing errors.
+
+When a read is both expensive and variant-keyed, **gate it by mounting instead**.
+Mounting is a real gate: an unmounted component runs no query, and remounting
+re-establishes the subscription with the current variant.
+
+**Incorrect (lazy on a variant-keyed read — search silently stops working):**
+
+```tsx
+const { data, trigger } = useQuery(
+  "/app/:orgId/products/search",
+  { params: { orgId }, search: { q: debouncedQuery, limit } },
+  { lazy: true },
+);
+
+useEffect(() => { trigger(); }, [debouncedQuery, limit]); // fights the design
+```
+
+**Correct (move the read into the subtree that only mounts when opened):**
+
+```tsx
+// Radix unmounts PopoverContent while the popover is closed, so this query
+// does not exist until the user opens the picker — and it re-keys normally
+// on `debouncedQuery` and `limit` once it does.
+<PopoverContent>
+  <CatalogSearchPanel orgId={orgId} />
+</PopoverContent>
+```
+
+**Also correct — lazy for a fixed-input, action-triggered read:**
+
+```tsx
+const { data, trigger, loading } = useQuery(
+  "/app/:orgId/export/preview",
+  { params: { orgId } },
+  { lazy: true },
+);
+
+<Button onClick={() => trigger()}>Preview export</Button>
+```

package/skills/gemi-react-best-practices/rules/query-mutate-over-refetch.md

@@ -0,0 +1,55 @@
+---
+title: Write the Cache With mutate Instead of Refetching
+impact: MEDIUM-HIGH
+impactDescription: removes a round-trip from every write
+tags: query, mutations, cache, optimistic
+---
+
+## Write the Cache With mutate Instead of Refetching
+
+After a successful mutation the UI needs to reflect the new state. Refetching the
+list costs a round-trip the client can often skip: `mutate` writes the cache
+immediately, then reconciles with the server on its own.
+
+- **`mutate(fn)`** from a `useQuery` — updates that component's variant.
+- **`useMutate()`** — updates **any** variant by path, from outside the component
+  that owns it. This is the one to reach for after a mutation, since the writer is
+  rarely the reader.
+
+The callback must return the complete next value — merge existing data yourself.
+After the optimistic write, gemi refetches to reconcile, so a wrong guess
+self-corrects rather than sticking.
+
+**Incorrect (blank, then a full round-trip, before the row disappears):**
+
+```tsx
+const { trigger } = useDelete("/app/:orgId/products/:id");
+
+await trigger();
+await refetch(); // user waits for the list again
+```
+
+**Correct (row disappears immediately; reconciliation happens behind it):**
+
+```tsx
+import { useMutate, useDelete } from "gemi/client";
+
+const mutate = useMutate();
+const { trigger } = useDelete("/app/:orgId/products/:id");
+
+await trigger();
+mutate(
+  { path: "/app/:orgId/products", params: { orgId } },
+  (products) => products.filter((p) => p.publicId !== id),
+);
+```
+
+**Refetch, don't guess, when the server derives the value.** If a write changes
+counts, totals, credit balances or anything else computed server-side, call
+`mutate()` with no callback — it refetches without an optimistic write, which is
+still cheaper than remounting the surface.
+
+Note the target must name the same variant as the reader (`query-share-cache-key`):
+`mutate({ path, params, search })` misses if the search object differs.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/query-no-hand-rolled-fetch.md

@@ -0,0 +1,60 @@
+---
+title: Read Server Data With useQuery, Never a Raw fetch
+impact: CRITICAL
+impactDescription: dedup, caching, SSR priming, types — all lost otherwise
+tags: query, data-fetching, types
+---
+
+## Read Server Data With useQuery, Never a Raw fetch
+
+A hand-rolled `fetch` in an effect opts out of everything gemi's network layer
+provides: SSR priming from `Query.prefetch`, cross-component deduplication, the
+cache, revalidation, suspense integration, and end-to-end types generated into
+`.gemi/gemi.d.ts`. It also reintroduces the classic effect bugs — races on fast
+navigation, no cancellation, a setState after unmount.
+
+**Incorrect (no dedup, no cache, no priming, no types):**
+
+```tsx
+function Products() {
+  const [products, setProducts] = useState([]);
+  useEffect(() => {
+    fetch(`/api/app/${orgId}/products`)
+      .then((r) => r.json())
+      .then(setProducts);
+  }, [orgId]);
+}
+```
+
+**Correct:**
+
+```tsx
+import { useQuery } from "gemi/client";
+
+function Products() {
+  const { data: products } = useQuery("/app/:orgId/products", {
+    params: { orgId },
+  });
+}
+```
+
+**Writes go through the mutation hooks or `<Form>`, for the same reason:**
+
+```tsx
+import { usePost } from "gemi/client";
+
+const { trigger, loading, error } = usePost("/app/:orgId/products");
+await trigger({ name });
+```
+
+Mutation errors arrive as tagged objects — `validation_error` (with per-field
+`messages`), `form_error`, `server_error`, `not_authorized`,
+`insufficient_permissions` — so a controller should `throw new ValidationError(...)`
+rather than inventing a per-endpoint error shape.
+
+**The one documented exception is file upload.** `useUpload` is XHR-based (it needs
+progress events). That is also why it cannot be intercepted by MSW under happy-dom:
+a client file post that needs to be unit-testable should use `usePost` with
+`FormData` instead.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/query-revalidate-on-focus.md

@@ -0,0 +1,44 @@
+---
+title: revalidateOnFocus Is Opt-In, For Cross-Tab-Mutable Data Only
+impact: MEDIUM
+impactDescription: freshness without a request storm
+tags: query, revalidation, focus, staleness
+---
+
+## revalidateOnFocus Is Opt-In, For Cross-Tab-Mutable Data Only
+
+`revalidateOnFocus` defaults to `false` in gemi. Turn it on only for a value that can
+change **without this tab doing anything** — a balance a webhook can credit, a status
+another tab can flip, a quota a background job can consume. For everything else, the
+5s `staleTime` and the mutation-driven cache writes are enough.
+
+When you do turn it on, two defaults keep it from becoming a request storm:
+`staleTime` (5000ms) suppresses revalidation for data that is still fresh, and
+`focusThrottleInterval` (5000ms) sets a floor between focus-triggered revalidations.
+A tab return that fires both `focus` and `visibilitychange` collapses to one request.
+
+**Incorrect (a long-lived widget goes stale for the whole session):**
+
+```tsx
+// Mounted in the nav for the entire session. A purchase made in another tab,
+// or a renewal landing via webhook, leaves this balance wrong until reload.
+const { data: credits } = useQuery("/app/:orgId/ai-credits", { params: { orgId } });
+```
+
+**Correct:**
+
+```tsx
+const { data: credits, loading } = useQuery(
+  "/app/:orgId/ai-credits",
+  { params: { orgId } },
+  { revalidateOnFocus: true },
+);
+```
+
+**Do not reach for `refreshInterval` where focus revalidation would do.** Polling
+runs while nobody is looking; focus revalidation runs when someone starts looking.
+Reserve `refreshInterval` for genuinely live data (a job that is running now), and
+stop polling when the surface unmounts or the work completes.
+
+Remember `query-share-cache-key`: turning this on for a shared variant turns it on
+for every reader of that variant.

package/skills/gemi-react-best-practices/rules/query-share-cache-key.md

@@ -0,0 +1,51 @@
+---
+title: Identical Query Variants Dedupe For Free
+impact: HIGH
+impactDescription: N components, 1 request
+tags: query, deduplication, cache
+---
+
+## Identical Query Variants Dedupe For Free
+
+gemi's query cache is keyed on path + params + search. Two components reading the
+same variant share one request, one cache entry, and one revalidation — there is no
+caching library to add and no context to thread. Deduplication is the default, not
+something you opt into.
+
+The corollary is the useful part: **do not lift a query into a parent and prop-drill
+it just to avoid a "duplicate" request.** There is no duplicate request. Reading it
+where it is used keeps the component self-contained, and a mutation that refreshes
+the variant refreshes every reader at once.
+
+**Incorrect (prop-drilling to dedupe something already deduped):**
+
+```tsx
+function Settings() {
+  const { data: credits } = useQuery("/app/:orgId/ai-credits", { params });
+  return (
+    <>
+      <CreditsPanel credits={credits} />
+      <Composer credits={credits} />
+      <NavBadge credits={credits} />
+    </>
+  );
+}
+```
+
+**Correct (each reads it; one request serves all three):**
+
+```tsx
+function CreditsPanel() {
+  const { data: credits } = useQuery("/app/:orgId/ai-credits", { params });
+  // …
+}
+```
+
+Two things follow from the key being exact:
+
+- **A cosmetic difference in `search` splits the cache.** `{ limit: 25 }` and
+  `{ limit: "25" }` are different variants; so are `{ q: "" }` and `{ q: null }`.
+  Normalize at one place — usually a shared constant — so readers agree.
+- **Sharing a variant means sharing its config's effects.** A `revalidateOnFocus`
+  set by one reader refreshes the value every reader sees. That is usually what you
+  want; know that it is happening.

package/skills/gemi-react-best-practices/rules/query-suspense-default.md

@@ -0,0 +1,52 @@
+---
+title: suspense Is On By Default and Throws to the Nearest Boundary
+impact: CRITICAL
+impactDescription: prevents whole-surface blanking
+tags: query, suspense, loading, ux
+---
+
+## suspense Is On By Default and Throws to the Nearest Boundary
+
+`useQuery` defaults to `suspense: true`. Two consequences that surprise people:
+
+1. **A fresh fetch suspends the component**, which blanks everything up to the
+   nearest boundary — not just the widget doing the read. A query added deep inside
+   an interactive surface can blank the whole route behind it.
+2. **A failed fetch throws**, so `loading` and `error` are not what that path
+   returns. Under suspense, `data` is non-nullable and the loading/error states are
+   the boundary's job.
+
+Keep the default for a route's primary read — that is what the route's `Loading` /
+`Error` exports are for (`render-loading-error-exports`). Pass `{ suspense: false }`
+for a secondary read that should render its own inline loading state in place.
+
+**Incorrect (opening a picker blanks the chat behind it):**
+
+```tsx
+// Inside a popover nested in the composer. The nearest boundary is the ROUTE's
+// <Suspense fallback={null}>, so this suspends the entire surface.
+const { data: products } = useQuery("/app/:orgId/products/search", {
+  params: { orgId },
+  search: { q: debouncedQuery },
+});
+```
+
+**Correct (the panel owns its loading state, nothing above it blanks):**
+
+```tsx
+const { data: products = [], loading } = useQuery(
+  "/app/:orgId/products/search",
+  { params: { orgId }, search: { q: debouncedQuery || null, limit } },
+  { suspense: false },
+);
+
+if (loading) return <PanelSkeleton />;
+```
+
+Note the third-argument position: options like `suspense`, `keepPreviousData`,
+`staleTime` and `refreshInterval` are the **third** argument; `params` and `search`
+are the second.
+
+**When writing tests for this:** a non-lazy query suspends while its first page is
+in flight and throws when it fails, so seed `<Page>`'s `fallback` and
+`errorFallback` and assert those — `loading`/`error` are not what that path returns.

package/skills/gemi-react-best-practices/rules/routing-cache-policy-constants.md

@@ -0,0 +1,53 @@
+---
+title: Name Cache Policies Once, Reuse the Constant
+impact: MEDIUM-HIGH
+impactDescription: prevents a private page shipping a public cache header
+tags: routing, caching, middleware, correctness
+---
+
+## Name Cache Policies Once, Reuse the Constant
+
+`cache:` compiles to a `Cache-Control` header, so the difference between
+`cache:public` and `cache:private,0,no-store` is the difference between a CDN
+serving one customer's page to another and not. Spelling the policy inline at each
+router invites a typo that is invisible in review and catastrophic in production.
+
+This app hoists the policies it uses to named constants and reuses them.
+
+**Incorrect (four routers, four hand-typed policies, one of them wrong):**
+
+```ts
+class CustomerRouter extends ViewRouter {
+  middlewares = ["cache:private,0,no-store", "auth"];
+}
+class CustomerAuthRouter extends ViewRouter {
+  middlewares = ["cache:public"]; // signed-out, but now CDN-cacheable per-visitor
+}
+```
+
+**Correct (one named policy per audience):**
+
+```ts
+const ANONYMOUS_VIEW_CACHE = "cache:private,0,no-store";
+const LANDING_VIEW_CACHE = "cache:private,12840,must-revalidate";
+
+class CustomerAuthRouter extends ViewRouter {
+  middlewares = [ANONYMOUS_VIEW_CACHE];
+}
+```
+
+What the DSL expands to:
+
+| DSL | `Cache-Control` |
+|---|---|
+| `cache` / `cache:public` | `public, max-age=864000, stale-while-revalidate=300, stale-if-error=600` |
+| `cache:private` | `private, max-age=0, stale-while-revalidate=300, stale-if-error=600` |
+| `cache:private,0,no-store` | `private, max-age=0, no-store` |
+
+The arguments are `scope`, `maxAge`, then directives, and the middleware only sets
+headers on **GET** responses.
+
+**Default to `no-store` for anything behind `auth`.** A per-user page that is
+cacheable at all is a decision worth making explicitly, with a constant that says so.
+
+Reference: `app/http/routes/view.ts`

package/skills/gemi-react-best-practices/rules/routing-middleware-dsl.md

@@ -0,0 +1,60 @@
+---
+title: Middleware Is a String DSL, Applied at Router or Route Level
+impact: HIGH
+impactDescription: the app's actual auth boundary
+tags: routing, middleware, auth, security
+---
+
+## Middleware Is a String DSL, Applied at Router or Route Level
+
+Middleware attaches as strings — `"auth"`, `"admin"`, `"role:owner"`,
+`"rate-limit:10,30"`, `"cache:private,0,no-store"` — resolved through the aliases in
+`app/config/middleware.ts`. Everything after the colon is a comma-separated argument
+list passed to the middleware's `run(...)`.
+
+Declare it **router-level** (`middlewares = [...]`, inherited by nested routers) or
+**per-route** (`.middleware([...])`, which stacks on top).
+
+**Incorrect (hand-rolling an auth check that middleware already expresses):**
+
+```ts
+export class ReportController extends Controller {
+  async index(req: HttpRequest) {
+    const user = await Auth.user();
+    if (!user || Number(user.globalRole) >= 10) {
+      throw new InsufficientPermissionsError();
+    }
+    // …
+  }
+}
+```
+
+**Correct (the boundary is declared where the route is):**
+
+```ts
+class AdminRouter extends ApiRouter {
+  middlewares = ["cache:private,0,no-store", "auth", "admin"];
+  routes = {
+    "/reports": this.get(ReportController, "index"),
+  };
+}
+```
+
+**Cancel an inherited middleware with `-name`.** The framework keeps a de-duplicated
+map keyed by alias, so a sign-in page inside an authenticated router opts out
+explicitly rather than being moved:
+
+```ts
+class AdminAuthViewRouter extends ViewRouter {
+  middlewares = [ANONYMOUS_VIEW_CACHE, "-auth", "-admin"];
+  routes = { "/sign-in": this.view("auth/SignIn") };
+}
+```
+
+**Rate-limit buckets are per client IP *and* route path**, so `/api/search` and
+`/api/upload` hold separate budgets — a shared limit needs a configured `key`
+function, and a budget outside a route uses the `RateLimiter` facade
+(`RateLimiter.consume(key, { limit, window })`).
+
+Reference: `app/config/middleware.ts`, `app/http/routes/view.ts`
+<https://nstfkc.github.io/gemi/middleware.md>

package/skills/gemi-react-best-practices/rules/routing-resource-routes.md

@@ -0,0 +1,59 @@
+---
+title: Use resource() for Standard REST, With Per-Method Middleware
+impact: MEDIUM
+impactDescription: five routes, one line, no drift
+tags: routing, rest, controllers, middleware
+---
+
+## Use resource() for Standard REST, With Per-Method Middleware
+
+`this.resource(Controller)` binds a `ResourceController`'s five methods to the
+conventional REST shape in one line. The route key **must end with the item's id
+parameter**; gemi splits it into the collection path and the item path itself.
+
+| Method | Verb | Path |
+|---|---|---|
+| `list` | GET | collection |
+| `store` | POST | collection |
+| `show` | GET | item |
+| `update` | PUT | item |
+| `delete` | DELETE | item |
+
+**Incorrect (five hand-wired routes that will drift apart):**
+
+```ts
+routes = {
+  "/products": this.get(ProductsController, "list"),
+  "/products/new": this.post(ProductsController, "store"),
+  "/products/:productId": this.get(ProductsController, "show"),
+  "/product/:productId": this.put(ProductsController, "update"),
+  "/products/:productId/delete": this.delete(ProductsController, "delete"),
+};
+```
+
+**Correct:**
+
+```ts
+routes = {
+  "/:orgId/products/:productId": this.resource(ProductsController).middleware({
+    store: ["auth"],
+    update: ["auth"],
+    delete: ["auth"],
+  }),
+};
+```
+
+**`.middleware({})` takes a per-method map**, which is how a resource exposes public
+reads and authenticated writes without splitting into two routers.
+
+**Reach for the explicit verbs when the shape is not REST.** A path that needs two
+verbs bound to non-standard methods takes an object of lowercase method keys:
+
+```ts
+"/conversations/:id": {
+  get: this.get(ConversationController, "restoreV2"),
+  delete: this.delete(ConversationController, "deleteV2"),
+},
+```
+
+Reference: `app/http/routes/api.ts`; <https://nstfkc.github.io/gemi/routing.md>

package/skills/gemi-react-best-practices/rules/routing-routers-are-classes.md

@@ -0,0 +1,55 @@
+---
+title: Routes Are Declared on Router Classes, Not by File Location
+impact: HIGH
+impactDescription: the only place a URL is defined
+tags: routing, structure, views
+---
+
+## Routes Are Declared on Router Classes, Not by File Location
+
+Routing is **class-based**. A `ViewRouter` or `ApiRouter` subclass carries a `routes`
+object mapping a path to a handler, and routers nest by assigning one as a route
+value. Putting a file in `app/views` registers nothing — **the view file name has no
+relation to the URL**, and the mapping in `app/http/routes/view.ts` is the only thing
+that makes a page reachable.
+
+**Incorrect (creating the file and expecting a URL):**
+
+```tsx
+// app/views/customer/Billing.tsx — reachable at… nothing.
+export default function Billing() { /* … */ }
+```
+
+**Correct (register it, and bind its server data):**
+
+```ts
+// app/http/routes/view.ts
+class CustomerRouter extends ViewRouter {
+  middlewares = ["cache:private,0,no-store", "auth"];
+  routes = {
+    "/billing": this.view("customer/Billing", [BillingController, "view"]),
+  };
+}
+```
+
+The pieces worth knowing:
+
+- **`this.view(name, handler?)`** — the handler is an inline callback or a
+  `[Controller, "method"]` tuple; its return value becomes the component's props.
+- **`this.layout(name, handler?, routes)`** — nests a layout around child routes.
+  A layout handler **does not re-run** while navigating within the same layout unless
+  it is marked `.alwaysRun()`.
+- **`:param`** dynamic, **`:param?`** optional, **`(group)/`** groups routes for
+  shared middleware or a layout **without adding a URL segment**.
+- **`this.redirect(() => ({ destination }))`** for a static redirect.
+
+On the API side: `this.get/post/put/patch/delete(Controller, "method")`,
+`this.file(...)`, `this.stream(...)` (handles 206/416 and `Content-Range` for
+range requests), `this.proxy(...)`, and an object of lowercase method keys to bind
+several verbs to one path.
+
+**A view component must be a default export; a controller must be a named export.**
+The router imports each by that convention.
+
+Reference: `app/http/routes/view.ts`, `app/http/routes/api.ts`
+<https://nstfkc.github.io/gemi/routing.md>

package/skills/gemi-react-best-practices/rules/service-lazy-not-module-scope.md

@@ -0,0 +1,63 @@
+---
+title: Construct Clients Lazily, Never at Module Scope
+impact: HIGH
+impactDescription: keeps boot fast and command discovery working
+tags: service, boot, module-scope, commands
+---
+
+## Construct Clients Lazily, Never at Module Scope
+
+Work at module scope runs whenever the module is *imported*, which is not the same as
+when it is *used*. Three places in a gemi app punish that:
+
+1. **Command discovery imports every file under `app/commands` just to list them.**
+   A `new Stripe(key)` beside the handler throws on an empty key during
+   `gemi run` — with no command actually invoked.
+2. **Service `boot()` runs on every application start**, including per-test and
+   per-CLI-command. Validate settings there; open connections lazily.
+3. **Ports are installed at boot, after every module in the graph has evaluated**, so
+   reading one at module scope gets `undefined`.
+
+**Incorrect (constructed on import; `boot()` opens a connection):**
+
+```ts
+const stripe = new Stripe(process.env.STRIPE_KEY!);   // throws at import time
+
+export class SearchIndex extends Service {
+  static token = "searchIndex";
+  async boot() {
+    this.client = await Client.connect(process.env.SEARCH_URL!); // every start
+  }
+}
+```
+
+**Correct (validate at boot, connect on first use, construct in the handler):**
+
+```ts
+export class SearchIndex extends Service {
+  static token = "searchIndex";
+  url = process.env.SEARCH_URL;
+  private ready?: Promise<Client>;
+
+  async boot() {
+    if (!this.url) throw new Error("SEARCH_URL is not set");
+  }
+
+  private connect() {
+    return (this.ready ??= Client.connect(this.url!));
+  }
+}
+
+export default defineCommand("sync-prices").handle(async ({ line }) => {
+  const stripe = new Stripe(process.env.STRIPE_KEY!);   // inside the handler
+});
+```
+
+**`Service.inject()` must not be called at module top level either** — it throws
+because the kernel has not booted. Inject as a constructor default
+(`constructor(private billing = Billing.inject())`), which resolves per request and
+lets a test pass a double without touching the container.
+
+**Read a runtime port inside a function or behind a getter**, never at module scope.
+
+Reference: <https://nstfkc.github.io/gemi/services.md>

package/skills/gemi-react-best-practices/rules/service-queue-is-in-memory.md

@@ -0,0 +1,52 @@
+---
+title: The Queue Is In-Process and In-Memory — Do Not Trust It With Durable Work
+impact: HIGH
+impactDescription: enqueued work is lost on restart
+tags: service, jobs, queue, durability
+---
+
+## The Queue Is In-Process and In-Memory — Do Not Trust It With Durable Work
+
+Jobs live in the server process's memory. **Enqueued jobs do not survive a restart**,
+and there is no cross-machine queue — a job dispatched on one instance runs on that
+instance or not at all. Use jobs for best-effort work: warming a cache, sending a
+non-critical email, kicking off media processing that the user can retry.
+
+Anything that must not be lost needs a durable record: write the row first, then let
+the job (or a cron sweep) act on it, so a restart leaves work to pick up rather than
+a gap.
+
+**Incorrect (the only record of the charge lives in the queue):**
+
+```ts
+async store(req: HttpRequest) {
+  const order = await Order.create({ data });
+  SettleOrderJob.dispatch({ orderId: order.publicId }); // lost on deploy
+  return { order };
+}
+```
+
+**Correct (durable state first; the job is an accelerator):**
+
+```ts
+async store(req: HttpRequest) {
+  const order = await Order.create({ data: { ...data, settlementStatus: "pending" } });
+  SettleOrderJob.dispatch({ orderId: order.publicId });
+  return { order };
+}
+// A cron sweeps `settlementStatus: "pending"` rows, so a lost dispatch self-heals.
+```
+
+**Two deployment-shaped constraints that follow:**
+
+- **The `queue` and `schedule` config slices declare their `jobs` lists
+  explicitly, and must keep doing so.** Discovery is a *runtime* filesystem walk, and
+  the release image ships only `dist/` — there is no `app/jobs` or `app/cron` on disk
+  in production. Discovery there warns once and registers nothing, so every job and
+  cron would stop running while dev and CI stayed green. Note `jobs: []` is
+  *present* and disables everything; omitting the key is what enables discovery.
+- **A command dispatching a Job may exit before it runs.** The queue runs in-process
+  and the cron scheduler does not start under `gemi run` — do that work inline in the
+  command instead.
+
+Reference: <https://nstfkc.github.io/gemi/jobs-and-queues.md>