@cavulsqa/create 0.1.0

package/templates/f7-app/.claude/rules/native.md

@@ -0,0 +1,47 @@
+# Capacitor and native behaviour
+
+Every native call is guarded with `Capacitor.isNativePlatform()` or
+`Capacitor.getPlatform() === "web"`. `vp dev` in a browser must keep working — it is how the app is
+inspected — so a handler that assumes a device breaks the fastest feedback loop you have.
+
+Native wiring that needs the Framework7 instance runs inside `f7ready`, not at module load.
+`src/plugins/capacitor/index.ts` is the single entry point.
+
+## What is already handled, and why it is not simple
+
+- **Back button** (`useAndroidBackButton`) closes the topmost layer before it navigates, in order:
+  actions, dialog, sheet, popover, popup, login screen, panel. Then a popup's own view history, then
+  the router, then it minimises rather than exits. The order matters: an actions sheet over a popup
+  must close first or back dismisses the popup underneath and orphans the sheet.
+- **Keyboard** (`useKeyboard`) scrolls the focused input into view on _every_ phase of the
+  transition, not once — the layout is still settling at `keyboardWillShow` and only
+  `keyboardDidShow` sees the final height. It also hides the tab bar, which otherwise steals a row
+  from the field being typed into, and leaves a message bar's accessory row alone.
+- **Status bar** overlays the web view; the page owns the inset.
+- **Splash** stays up until `hideSplashScreen()`, called on a frame boundary so there is no flash of
+  an unpainted shell.
+
+Do not simplify these into a single listener. Each branch is there because of a specific device
+behaviour, and the comments say which.
+
+## The bootstrap must never fail silently
+
+`main.ts` opens the database before mounting, inside a `try`, and renders the failure on the page if
+it throws. An earlier version awaited it at module top level: a rejection produced an empty `#app`
+and a completely silent console, which is the worst possible failure for whoever generates from this
+template. The timeout exists so a hang cannot masquerade as a blank screen either.
+
+Anything else added to the bootstrap follows the same shape: guarded, and loud when it fails.
+
+## Fixed elements and the shell
+
+The tab bar lives in the shell, outside every page, inside `.views.tabs`. So:
+
+- A page already ends above it — do not add a bottom offset to a FAB to "clear" it. That counts it
+  twice.
+- FAB buttons open upward (`position="top"`), or they land behind it.
+
+## Proof obligations
+
+Say which platform you tested on. "Type-checks" is not a claim about a device, and neither is a
+browser. If you have not run it on Android, say so.

package/templates/f7-app/.claude/skills/f7-design/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: f7-design
+description: Framework7 UI work in this app. Use whenever the task is to build or change a screen, view, page, component, layout, navbar, tabbar, toolbar, list, sheet, popup, panel, FAB, card, chip, searchbar, swipeout, or any mobile UI. Covers the component-first rule, the resolver allowlist you must update before using a new component, the icon ligature trap, and why this app writes no CSS.
+---
+
+# Framework7 UI workflow
+
+Mobile-first, Android-first, native-feeling on both themes. Reach for a Framework7 component before
+building anything by hand — it already handles the theme, dark mode, safe areas and the gestures.
+
+## Before building a screen
+
+1. Check whether Framework7 has the component: https://framework7.io/vue/. The catalogue wired into
+   this app is [components.md](components.md).
+2. In the allowlist → use `<F7Xxx>` directly. **No import** — `Framework7VueResolver` resolves it.
+3. Not in the allowlist → add the kebab name to `framework7Components` in
+   `src/shared/utils/resolvers/resolvers.ts` **first**. Skip this and the component silently fails
+   to resolve.
+4. Before adding a name, confirm the installed `framework7-vue` actually exports it. `f7-toolbar-pane`
+   is a Framework7 9 CSS class with no Vue component in framework7-vue 8 — resolving it throws a
+   runtime `SyntaxError`, not a warning. Use the class on a plain `div` in that case.
+5. Hand-build only when Framework7 has nothing suitable.
+
+## Layout idiom
+
+```
+F7Page > F7Navbar > [F7NavRight, F7Subnavbar]
+         F7BlockTitle          section heading
+         F7Block strong inset  prose or a stat surface
+         F7List strong inset dividers   rows
+```
+
+- Rounded surfaces: `class="rounded-2xl!"`. The `!` matters — Tailwind loads after the F7 bundle.
+- `F7ListItem` renders `subtitle`, `text` and `#media` **only in a media list**. Outside one they
+  are dropped with no warning.
+- Long descriptive text goes in `#text` in a media list, never `#footer` — footers are sized for a
+  few words and long text overlaps the title.
+- Detail-screen actions go in `F7Toolbar bottom`, which spaces links evenly and clears the safe
+  area. A hand-built fixed bar does neither.
+
+## Write no CSS
+
+No backgrounds, heights, safe-area padding or body font sizes. The theme owns them, for iOS and
+Material, light and dark. `assets/css/app.css` is one line.
+
+Tailwind is for layout inside a component — flex, grid, gaps, a size on a number. The moment you
+reach for a colour, use a Framework7 component or a theme variable instead. Theme colour is set once
+via `colors.primary` in `src/plugins/framework7.plugin.ts`, never as a CSS override: Framework7
+derives tints, shades, ripples and the dark variants from that value.
+
+## Icons
+
+Read [icons.md](icons.md) before typing an icon name. framework7-icons is a **ligature font**: a
+wrong name renders nothing at all, with no warning. This app has shipped invisible icons twice.
+
+## Navigation and gestures
+
+- Tabs are data in `src/app/tabs.ts`; each is a view with its own history.
+- A pushed page calls `useHiddenTabbar()`.
+- Swipeout inside swipeable tabs needs `swiper-no-swiping` on the list, or one drag does both.
+- A route's `async` is Framework7's hook, not an async function — resolve from a promise.
+- `f7route` / `f7router` are props: `defineProps<{ f7route: Router.Route }>()`.
+
+## Before saying it works
+
+`vp test` (includes the icon check) and `pnpm type-check`. Then say whether you have actually seen
+the screen. A screen that compiles can still be an empty box.

package/templates/f7-app/.claude/skills/f7-design/components.md

@@ -0,0 +1,49 @@
+# Component catalogue
+
+The allowlist is the `framework7Components` array in
+`src/shared/utils/resolvers/resolvers.ts`. Only names in it resolve; anything else renders as an
+unknown element.
+
+## Wired
+
+Shell and navigation
+: `f7-app`, `f7-view`, `f7-views`, `f7-page`, `f7-page-content`, `f7-navbar`, `f7-nav-left`,
+`f7-nav-right`, `f7-nav-title`, `f7-nav-title-large`, `f7-toolbar`, `f7-subnavbar`, `f7-link`,
+`f7-tabs`, `f7-tab`, `f7-panel`, `f7-searchbar`
+
+Lists and inputs
+: `f7-list`, `f7-list-group`, `f7-list-item`, `f7-list-item-row`, `f7-list-item-cell`,
+`f7-list-item-content`, `f7-list-button`, `f7-list-input`, `f7-checkbox`, `f7-toggle`,
+`f7-stepper`
+
+Actions and surfaces
+: `f7-button`, `f7-segmented`, `f7-fab`, `f7-fab-button`, `f7-fab-buttons`, `f7-card`,
+`f7-card-header`, `f7-card-content`, `f7-card-footer`, `f7-popup`, `f7-popover`, `f7-actions`,
+`f7-actions-group`, `f7-actions-button`, `f7-actions-label`, `f7-sheet`, `f7-login-screen`
+
+Content
+: `f7-block`, `f7-block-title`, `f7-block-header`, `f7-block-footer`, `f7-icon`, `f7-chip`,
+`f7-badge`, `f7-preloader`, `f7-progressbar`, `f7-skeleton-block`, `f7-skeleton-text`,
+`f7-accordion*`, `f7-swipeout*`, `f7-messages*`, `f7-messagebar*`, `f7-photo-browser`,
+`f7-virtual-list`, `f7-list-index`, `f7-row`, `f7-col`
+
+## Deliberately absent
+
+`f7-toolbar-pane`
+: Framework7 9 ships the CSS class; framework7-vue 8 exports no component. Resolving it fails as a
+runtime `SyntaxError`. Use `<div class="toolbar-pane">`.
+
+## Adding one
+
+1. Confirm the installed `framework7-vue` exports it — check its entry, not the docs, since the Vue
+   bindings lag the core.
+2. Add the kebab name to the array.
+3. Use the PascalCase tag with no import.
+
+## Programmatic APIs
+
+`f7` is auto-imported. `f7.dialog.*`, `f7.toast.*`, `f7.sheet.*`, `f7.actions.*`, `f7.fab.*`,
+`f7.tab.show()`.
+
+Check the option names against `framework7/components/<name>/<name>.d.ts` rather than from memory —
+an action-sheet heading is `{ text, label: true }`, and emphasis is `strong`, not `bold`.

package/templates/f7-app/.claude/skills/f7-design/icons.md

@@ -0,0 +1,52 @@
+# Icons
+
+Three systems. Pick by context.
+
+## 1. Framework7 icon font — chrome and list media
+
+```vue
+<F7Icon f7="checkmark_seal_fill" color="green" />
+<F7Icon ios="f7:house_fill" md="material:home" />
+<!-- per-theme, for the tab bar -->
+```
+
+**The trap.** framework7-icons is a ligature font. A name it does not carry renders _nothing_ — no
+warning, no fallback, no console message. Invisible in review, invisible in a screenshot you did not
+look closely at.
+
+Rules that came from getting this wrong twice:
+
+- **Verify against the font, never from memory.** `tests/icons.test.ts` checks every name used in
+  the app against `Framework7Icons-Regular.ttf`. It is the authority; run it.
+- The name **keeps the underscore before a digit**: `arrow_2_circlepath`, `square_grid_2x2_fill`,
+  `square_stack_3d_down_right_fill`, `rectangle_3_offgrid_fill`.
+- **Do not derive names from `framework7-icons/react/*`.** Those files are SVG wrappers whose names
+  do not match the ligatures. Trusting them turned four working icons into fragments of other
+  glyphs.
+- **SF Symbols names are not Framework7 names.** It is `search`, not `magnifyingglass`.
+- Browse real names at https://framework7.io/icons/.
+
+## 2. Material icons — the `md` theme
+
+`icon-md="material:home"` needs the Material font, which is bundled in `src/assets/css/icons.css`
+with a `font-feature-settings: "liga"` rule. Without it the icon renders as the literal word
+"home". The font is self-hosted, not from a CDN, because an offline-first app should not lose its
+icons with the network.
+
+## 3. unplugin-icons SVGs — feature UI
+
+```vue
+<ILucideZap class="text-yellow-500" />
+```
+
+Resolved by `IconsResolver` with the `framework7`, `material-symbols` and `lucide` collections
+enabled, and `autoInstall: true`. Unlike the font, a wrong name here **fails at build time**, which
+makes it the safer choice for anything decorative or one-off.
+
+## Choosing
+
+| Context                        | Use                          |
+| ------------------------------ | ---------------------------- |
+| Tab bar, navbar, native chrome | `F7Icon` with `ios=` / `md=` |
+| List row media, status glyphs  | `F7Icon f7="…" color="…"`    |
+| Feature illustration, one-offs | `<ILucide… />`               |

package/templates/f7-app/.claude/skills/module-architecture/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: module-architecture
+description: Where code goes in this app and how to add a feature end to end. Use when creating a new screen, module, route, domain, repository, composable, or when deciding whether something belongs in modules, domains or shared. Covers the dependency direction, the file layout of a module, and the checklist for wiring a feature into the shell.
+---
+
+# Module architecture
+
+```
+src/
+├── app/tabs.ts                        the tab bar, as data
+├── router/index.ts                    aggregates module routes, catch-all last
+├── domains/<domain>/<x>.repository.ts SQL only
+├── modules/<feature>/
+│   ├── router/routes/<feature>.routes.ts
+│   ├── views/<Name>View.vue
+│   ├── components/*.vue
+│   └── composables/use*.ts
+└── shared/                            what two modules genuinely both need
+```
+
+## The seam
+
+| Layer      | Owns                                    | Never contains                               |
+| ---------- | --------------------------------------- | -------------------------------------------- |
+| View       | Wiring a composable to components       | Business logic, SQL                          |
+| Composable | State, queries, actions for one feature | Markup                                       |
+| Repository | Plain functions over Kysely             | `ref`, lifecycle, Framework7, module imports |
+| Component  | Props in, emits out                     | Database access                              |
+
+Dependencies run **modules → domains → shared → packages**, never backwards. A repository importing
+from a module, or `shared` importing from `modules`, means something is in the wrong place.
+
+## Adding a feature
+
+1. `modules/<feature>/` with the four folders. Templates: [file-templates.md](file-templates.md).
+2. SQL in `domains/<domain>/<domain>.repository.ts`, taking the database as its first parameter.
+3. Routes in `modules/<feature>/router/routes/<feature>.routes.ts`, default-exported, registered in
+   `src/router/index.ts` **before** the global catch-all.
+4. A tab in `src/app/tabs.ts` only if it is a top-level section — with both `iconIos` and `iconMd`.
+   Otherwise it is a pushed page, and pushed pages call `useHiddenTabbar()`.
+5. Strings in **both** `locales/en.json` and `locales/fr.json`. A missing key renders as the key.
+   Remember `@` and `|` are message syntax.
+6. A test in `tests/` for anything with SQL.
+7. `vp check`, `vp test`, `pnpm type-check`.
+
+## shared/ is not a junk drawer
+
+Something moves to `shared/` when a second module imports it **today**. The test: name the second
+caller. If you cannot, it lives in the module that uses it.
+
+## Auto-imports
+
+`ref`, `computed`, `watch`, lifecycle hooks, `useI18n`, `@vueuse/core`, `f7`, `f7ready` and
+everything under `shared/composables`, `shared/utils`, `plugins` and `modules/**/composables` are
+auto-imported — no import line. Components under `shared/components` and `modules/**/{views,components}`
+resolve the same way.
+
+Two things are **not** auto-imported and must be declared:
+
+- `f7route` / `f7router` — Framework7 passes them to a route component as props.
+- Repositories and anything under `domains/` — imported explicitly, because a domain is a boundary
+  you should see being crossed.
+
+`auto-imports.d.ts` and `components.d.ts` are generated. Never hand-edit them; if the editor
+disagrees with the build, run the dev server once to regenerate.

package/templates/f7-app/.claude/skills/module-architecture/file-templates.md

@@ -0,0 +1,183 @@
+# File templates
+
+Copy these shapes. They encode decisions that are easy to get wrong once and then repeat everywhere.
+
+## Route file
+
+`modules/<feature>/router/routes/<feature>.routes.ts`
+
+```ts
+import type { Router } from "framework7/types";
+
+const featureRoutes: Router.RouteParameters[] = [
+  {
+    name: "feature",
+    path: "/feature/",
+    // `async` is Framework7's route hook, not an async function - resolve from the promise.
+    async({ resolve }) {
+      void import("@/modules/feature/views/FeatureView.vue").then((view) => {
+        resolve({ component: view.default });
+      });
+    },
+  },
+  {
+    name: "feature-detail",
+    path: "/feature/:id/",
+    async({ resolve }) {
+      void import("@/modules/feature/views/FeatureDetailView.vue").then((view) => {
+        resolve({ component: view.default });
+      });
+    },
+  },
+];
+
+export default featureRoutes;
+```
+
+`await` inside that hook does not compile — the property is literally named `async`.
+
+## Repository
+
+`domains/<domain>/<domain>.repository.ts`
+
+```ts
+import type { Kysely } from "kysely";
+import { nowISO } from "@cavulsqa/mobile-db";
+import type { Database } from "@/shared/database/schema";
+
+export interface ThingRow {
+  id: number;
+  name: string;
+  totalCents: number;
+}
+
+/** Reads take the database as a parameter - that is what makes them testable. */
+export function listThings(db: Kysely<Database>, term: string): Promise<ThingRow[]> {
+  let query = db.selectFrom("thing").select(["id", "name", "total_cents as totalCents"]);
+  if (term.trim()) query = query.where("name", "like", `%${term.trim()}%`);
+  return query.orderBy("id", "desc").limit(40).execute();
+}
+
+/** All-or-nothing work goes in one transaction. */
+export async function saveThing(
+  db: Kysely<Database>,
+  input: { name: string; lines: Array<{ productId: number; quantity: number }> },
+): Promise<void> {
+  await db.transaction().execute(async (trx) => {
+    const thing = await trx
+      .insertInto("thing")
+      .values({ created_at: nowISO(), name: input.name })
+      .returning("id")
+      .executeTakeFirstOrThrow();
+
+    for (const line of input.lines) {
+      await trx
+        .insertInto("thing_line")
+        .values({ thing_id: thing.id, ...line })
+        .execute();
+    }
+  });
+}
+```
+
+No `ref`, no lifecycle, no Framework7, no imports from `modules/`.
+
+## Composable
+
+`modules/<feature>/composables/useFeature.ts`
+
+```ts
+import { listThings, saveThing, type ThingRow } from "@/domains/thing/thing.repository";
+import { getDatabase, rdb } from "@/shared/database/database";
+import { uniqueQueryKey, useReactiveQuery } from "@/shared/database/queries";
+
+export function useFeature() {
+  const term = ref("");
+  const busy = ref(false);
+
+  const query = useReactiveQuery(() => listThings(getDatabase().db, term.value), {
+    // Every table the SQL touches. A join means each joined table.
+    tables: ["thing"],
+    queryKey: uniqueQueryKey("feature:things"),
+    debounce: 250,
+  });
+
+  const things = computed<ThingRow[]>(() => query.data.value ?? []);
+
+  // Writes go through `rdb`, which announces the tables they touched.
+  async function save(input: Parameters<typeof saveThing>[1]) {
+    busy.value = true;
+    try {
+      await saveThing(rdb, input);
+    } finally {
+      busy.value = false;
+    }
+  }
+
+  return { term, things, loading: query.loading, busy, save };
+}
+```
+
+`ref`, `computed` and the composable itself are auto-imported. Repositories are not.
+
+## View
+
+`modules/<feature>/views/FeatureView.vue`
+
+```vue
+<template>
+  <F7Page>
+    <F7Navbar :title="t('feature.title')" large :sliding="true" />
+
+    <F7BlockTitle>{{ t("feature.section") }}</F7BlockTitle>
+    <F7List v-if="things.length" media-list strong inset dividers class="rounded-2xl!">
+      <F7ListItem
+        v-for="thing in things"
+        :key="thing.id"
+        :title="thing.name"
+        :link="`/feature/${String(thing.id)}/`"
+      >
+        <template #media><F7Icon f7="cube_box_fill" color="blue" /></template>
+        <template #subtitle>
+          <span class="text-[13px] opacity-60">{{ thing.totalCents }}</span>
+        </template>
+      </F7ListItem>
+    </F7List>
+    <F7Block v-else strong inset class="rounded-2xl!">
+      <p class="m-0 text-sm opacity-70">{{ t("feature.empty") }}</p>
+    </F7Block>
+  </F7Page>
+</template>
+
+<script setup lang="ts">
+import { useFeature } from "@/modules/feature/composables/useFeature";
+
+const { t } = useI18n();
+const { things } = useFeature();
+</script>
+```
+
+No `f7-*` imports, no `<style>`. `subtitle` needs the media list.
+
+## Pushed detail view
+
+Same shape, plus:
+
+```ts
+import { useHiddenTabbar } from "@/shared/composables/useTabbarVisibility";
+
+const { t } = useI18n();
+
+// A pushed page owns the whole screen; the tab bar belongs to the tab roots.
+useHiddenTabbar();
+
+const props = defineProps<{ f7route: Router.Route; f7router: Router.Router }>();
+const id = Number(props.f7route.params.id ?? 0);
+```
+
+Actions on a detail screen go in `F7Toolbar bottom`.
+
+## Test
+
+`tests/<domain>.repository.test.ts` — see the reactive-data skill's testing guide for the harness.
+Assert the arithmetic, the empty state and the idempotence, not just that rows come back.

package/templates/f7-app/.claude/skills/reactive-data/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: reactive-data
+description: Reading and writing the local SQLite database in this app. Use whenever the task involves a query, a mutation, a repository, a migration, the schema, useReactiveQuery, the change bus, stale data, a screen not refreshing, query metrics, or testing data access. Covers the tables invalidation contract, why every write goes through rdb, and how to test SQL without a device.
+---
+
+# Reactive data workflow
+
+SQLite is the source of truth. A screen reads it through a reactive query; a write announces the
+tables it touched and every query watching one of them refetches. Nothing calls refetch by hand.
+
+## Adding a read
+
+```ts
+const query = useReactiveQuery(() => searchOrders(getDatabase().db, term.value), {
+  tables: ["sales_order", "order_line", "customer"],
+  queryKey: uniqueQueryKey("demo:orders"),
+  debounce: 250,
+});
+```
+
+1. Put the SQL in a repository: `src/domains/<domain>/<domain>.repository.ts`, taking the database
+   as its first parameter. Never reach for the singleton inside a repository — that is what makes it
+   testable.
+2. **List every table the SQL touches in `tables`.** Count them in the query, not from memory: a
+   join means each joined table. Under-list and the screen goes stale with no error; over-list and
+   an unrelated write re-runs an expensive query.
+3. `queryKey`: default to `uniqueQueryKey("prefix")`. A stable literal means "share this result with
+   any other query using the same key", which is right for one list rendered twice and wrong for
+   anything parameterised.
+4. `debounce` so a burst of writes causes one refetch.
+
+## Adding a write
+
+```ts
+await saveOrder(rdb, payload);        // announces its tables
+await saveOrder(getDatabase().db, …); // writes, and no screen notices
+```
+
+`rdb` is the reactive wrapper. A raw write lands in SQLite silently and the UI keeps showing old
+rows until something unrelated refetches — no error, nothing to see in review.
+
+All-or-nothing work goes in one transaction. A helper anyone can press twice must survive being
+pressed twice: insert-where-missing, or `onConflict(...).doNothing()`.
+
+## Schema changes
+
+`schema.ts` and `migrations.ts` are edited together — a field in one and not the other is a runtime
+error the compiler cannot see. Migrations are numbered, never renamed, never edited after shipping.
+Money is integer cents. Index what you filter and join by.
+
+## Testing
+
+Always. [testing.md](testing.md) has the harness: a Kysely on `createSqlJsDialect()`, migrate, then
+assert against real rows — including the arithmetic. A total that type-checks can still be computed
+wrong, and a device is not needed to catch that.
+
+## Diagnosing "the screen did not update"
+
+In order:
+
+1. Did the write go through `rdb`?
+2. Does the query's `tables` include the table that changed?
+3. Is the query's `queryKey` shared with a different query? Check the console for the conflict
+   warning.
+4. Is the page off-screen? `usePageVisibility` suppresses refetches for hidden pages by design.
+5. Only then look at the packages.
+
+## Proof obligations
+
+Name the tables the SQL touches and confirm `tables` matches. Say whether a test covers it. Never
+claim a data path works on the strength of a type-check.
+
+## Inserting a parent and its children
+
+The parent and its children go in one transaction, and the parent's id comes from `insertId`:
+
+```ts
+await db.transaction().execute(async (trx) => {
+  const inserted = await trx.insertInto("sales_order").values({ ... }).executeTakeFirstOrThrow();
+  const orderId = Number(inserted.insertId ?? 0);
+  if (!orderId) throw new Error("the order was written but the database reported no id for it");
+  ...
+});
+```
+
+`.returning("id")` looks like the obvious way and is the wrong one: inside an open transaction the
+plugin runs the statement through `query()` and discards its RETURNING rows, so kysely throws
+`no result` from a write that succeeded. `insertId` comes from `last_insert_rowid()` and works on
+both sides of the boundary. Full note in [database.md](../../rules/database.md).

package/templates/f7-app/.claude/skills/reactive-data/testing.md

@@ -0,0 +1,55 @@
+# Testing data access
+
+The queries run against real SQLite — sql.js, the same dialect `@cavulsqa/mobile-db` uses for its
+own tests. No device, no emulator, about a second for the suite.
+
+## The harness
+
+```ts
+import { beforeEach, expect, test } from "vite-plus/test";
+import { Kysely } from "kysely";
+import { Migrator } from "kysely/migration";
+import { createSqlJsDialect } from "@cavulsqa/mobile-db/testing";
+import { migrations } from "../src/shared/database/migrations.js";
+import type { Database } from "../src/shared/database/schema.js";
+
+let db: Kysely<Database>;
+
+beforeEach(async () => {
+  db = new Kysely<Database>({ dialect: await createSqlJsDialect() });
+  await new Migrator({
+    db,
+    provider: { getMigrations: () => Promise.resolve(migrations) },
+  }).migrateToLatest();
+});
+```
+
+A fresh in-memory database per test, with the app's real migrations applied. `Migrator` comes from
+`kysely/migration` — the root export is a compile-time error in kysely 0.29.
+
+## What to assert
+
+Type-checking proves the query compiles. These are the things it cannot prove:
+
+- **Arithmetic.** Two lines at quantity 1 and 2 × 1000 cents must total 3000. Write the number.
+- **Empty state.** An aggregate over no rows returns `0`, not `null`. `coalesce` is easy to forget
+  and the screen shows a blank tile.
+- **Joins.** Every joined row actually resolves — product names present, customer attached.
+- **Filters.** A search matches on each field it claims to, and returns `[]` for no match.
+- **State machines.** A status cycle lands where you expect at each step.
+- **Idempotence.** Anything a person can press twice, pressed twice. `seedSampleData` threw
+  `UNIQUE constraint failed: tag.label` on the second press and only a test caught it.
+- **Missing rows.** A lookup for an id that does not exist returns `null`, and an update against one
+  is a no-op rather than a throw.
+
+## The icon test
+
+`tests/icons.test.ts` guards a different silent failure: it reads the framework7-icons ttf and
+asserts every name used in `src/` is a real ligature, plus that the five names this app has already
+got wrong stay unresolvable. Extend the second list whenever a wrong name gets through.
+
+## Running
+
+```bash
+vp test        # from templates/f7-app
+```