@cavulsqa/create 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @cavulsqa/create
+
+Create a Vue 3 + Framework7 + Capacitor + SQLite app. One command, no clone.
+
+```bash
+pnpm create @cavulsqa
+```
+
+`npm create @cavulsqa`, `bun create @cavulsqa` and `vp create @cavulsqa` all work the same way. With
+a terminal it asks four questions; with `--name` it asks none, which is what CI wants.
+
+```bash
+pnpm create @cavulsqa --name caputa --app-id com.sig.caputa --yes
+```
+
+| flag         | default          |                                                        |
+| ------------ | ---------------- | ------------------------------------------------------ |
+| `--name`     | asked            | package and directory name                             |
+| `--template` | the only one     | which bundled template                                 |
+| `--dir`      | `./<name>`       | where to write it                                      |
+| `--app-name` | `Name`           | launcher name, window title, Settings screen           |
+| `--app-id`   | `com.ayb.<name>` | Android application id                                 |
+| `--from`     | —                | a template directory on disk, instead of a bundled one |
+| `--yes`      | —                | take the defaults, ask nothing                         |
+
+## What you get
+
+The `f7-app` template: a tabbed shell, a `domains` / `modules` / `shared` layout, and a working
+sales demo over a six-table schema — dashboard aggregates, search, an order sheet, swipe actions,
+a detail screen — with tests against real SQLite.
+
+Underneath it, the data layer this repository publishes: `@cavulsqa/mobile-db` for Capacitor SQLite
+under Kysely, `@cavulsqa/reactive-db` for the change bus, and `@cavulsqa/reactive-vue` for
+`useReactiveQuery`. A write announces the tables it touched and every query watching them refetches;
+nothing in a screen asks for a refresh.
+
+`CLAUDE.md`, `.claude/rules/` and `.claude/skills/` come with it, so an agent opening the generated
+repository knows the architecture, the conventions, and the traps that have already cost someone a
+day.
+
+## Versions
+
+The template's dependencies are resolved and pinned when this package is published, so a given
+version of `@cavulsqa/create` always generates the same app. Upgrading the data layer afterwards is
+an ordinary `pnpm update`.
+
+## After generating
+
+```bash
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` runs the app in a browser against sql.js in memory — quick for UI work, and data does not
+survive a reload. The real target is a device:
+
+```bash
+npx cap add android
+pnpm build && npx cap sync android && npx cap run android
+```
+
+Android builds need **JDK 21**. An older one fails with `invalid source release: 21` from inside
+`capacitor-android`, which reads like a Capacitor bug and is not one.

package/bin/create.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * `pnpm create @cavulsqa` / `npm create @cavulsqa` / `vp create @cavulsqa`.
+ *
+ * Interactive when it can be, flag-driven when it cannot: a TTY gets asked, and CI passing
+ * `--name` gets no prompts at all. Anything still missing without a TTY is an error rather than a
+ * silent default, because a generated app named "my-app" in the wrong directory is worse than a
+ * failed command.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { scaffold } from "../lib/scaffold.mjs";
+
+const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
+const BUNDLED = join(PACKAGE, "templates");
+
+function parseArgs(argv) {
+  const flags = new Map();
+  const positional = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const [key, inline] = arg.slice(2).split("=");
+    if (inline !== undefined) flags.set(key, inline);
+    else if (argv[index + 1] && !argv[index + 1].startsWith("--")) flags.set(key, argv[++index]);
+    else flags.set(key, true);
+  }
+  return { flags, positional };
+}
+
+function usage() {
+  console.log(`Usage: create-cavulsqa [name] [options]
+
+Options:
+  --name NAME          package and directory name
+  --template NAME      which template (default: the only one, or you are asked)
+  --dir PATH           where to write it (default: ./<name>)
+  --app-name NAME      launcher name and window title (default: Name)
+  --app-id ID          android application id (default: com.ayb.<name>)
+  --from PATH          use a template directory on disk instead of the bundled ones
+  --yes                take the defaults, ask nothing
+  --help               this
+
+Templates bundled in this package:
+${listTemplates()
+  .map((entry) => `  ${entry.name}  ${entry.description}`)
+  .join("\n")}`);
+}
+
+function listTemplates() {
+  const manifest = JSON.parse(readFileSync(join(PACKAGE, "package.json"), "utf8"));
+  const declared = manifest.createConfig?.templates ?? [];
+  if (!existsSync(BUNDLED)) return declared;
+
+  // The manifest is what `vp create` reads; the directory is what actually shipped. Trust the
+  // directory, and let the manifest supply the descriptions.
+  return readdirSync(BUNDLED).map((name) => ({
+    name,
+    description: declared.find((entry) => entry.name === name)?.description ?? "",
+  }));
+}
+
+/** npm package names: lowercase, no spaces, no leading dot or underscore. */
+function validName(value) {
+  return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(value);
+}
+
+async function main() {
+  const { flags, positional } = parseArgs(process.argv.slice(2));
+  if (flags.has("help") || flags.has("h")) return usage();
+
+  const interactive = process.stdin.isTTY && !flags.has("yes");
+  const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+
+  const ask = async (question, fallback) => {
+    if (!rl) return fallback;
+    const answer = (await rl.question(`${question}${fallback ? ` (${fallback})` : ""}: `)).trim();
+    return answer || fallback;
+  };
+
+  try {
+    let name = flags.get("name") ?? positional[0];
+    if (typeof name !== "string") name = await ask("App name", "my-app");
+    if (typeof name !== "string" || !validName(name)) {
+      throw new Error(`"${String(name)}" is not a usable package name`);
+    }
+
+    const templates = listTemplates();
+    if (!templates.length) throw new Error("this build of @cavulsqa/create bundles no templates");
+
+    let template = flags.get("template");
+    if (typeof template !== "string") {
+      template =
+        templates.length === 1
+          ? templates[0].name
+          : await ask(`Template [${templates.map((t) => t.name).join(", ")}]`, templates[0].name);
+    }
+    if (!templates.some((entry) => entry.name === template)) {
+      throw new Error(
+        `unknown template "${template}"; bundled: ${templates.map((t) => t.name).join(", ")}`,
+      );
+    }
+
+    const titled = name.charAt(0).toUpperCase() + name.slice(1);
+    const appName = flags.get("app-name") ?? (await ask("Display name", titled));
+    const bareName = name.replace(/[^a-z0-9]/gi, "").toLowerCase();
+    const appId =
+      flags.get("app-id") ?? (await ask("Android application id", `com.ayb.${bareName}`));
+
+    const dir = flags.get("dir") ?? (await ask("Directory", `./${name}`));
+    const out = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
+
+    const from = flags.get("from");
+    const templateDir =
+      typeof from === "string" ? resolve(process.cwd(), from) : join(BUNDLED, template);
+
+    scaffold({ templateDir, out, name, appId, appName: String(appName) });
+
+    console.log(`
+${appName} created in ${out}
+  template  ${template}
+  appId     ${appId}
+
+  cd ${basename(out)}
+  pnpm install
+  pnpm dev
+
+Android needs JDK 21: npx cap add android, then pnpm build && npx cap sync android`);
+  } finally {
+    rl?.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(`\n${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});

package/lib/scaffold.mjs

@@ -0,0 +1,124 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+/** Files whose contents carry the app's identity and have to be rewritten, not copied. */
+function personalise(entry, text, { name, appName }) {
+  if (entry === "capacitor.config.ts") {
+    return text
+      .replace(/appId: "[^"]*"/, `appId: "${name.appId}"`)
+      .replace(/appName: "[^"]*"/, `appName: "${appName}"`);
+  }
+  if (entry === "vite.config.ts") {
+    return text.replace(
+      /__APP_NAME__: JSON\.stringify\("[^"]*"\)/,
+      `__APP_NAME__: JSON.stringify("${appName}")`,
+    );
+  }
+  if (entry === "index.html") {
+    return text.replace(/<title>[^<]*<\/title>/, `<title>${appName}</title>`);
+  }
+  return null;
+}
+
+function manifest(source, { name, appName, templateName }) {
+  const pkg = JSON.parse(source);
+  const { private: _private, ...rest } = pkg;
+  return `${JSON.stringify(
+    {
+      ...rest,
+      name: name.package,
+      version: "0.1.0",
+      private: true,
+      description: `${appName} - generated from @cavulsqa/create (${templateName}).`,
+      engines: { node: ">=22.18.0" },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+function copyTree(from, to, transform) {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from, { withFileTypes: true })) {
+    const source = join(from, entry.name);
+    const target = join(to, entry.name);
+    if (entry.isDirectory()) {
+      copyTree(source, target, transform);
+      continue;
+    }
+    const rewritten = transform(entry.name, source);
+    if (rewritten === null) cpSync(source, target);
+    else writeFileSync(target, rewritten);
+  }
+}
+
+/**
+ * Writes a generated app to `out`.
+ *
+ * The template's dependencies are already concrete - `bundleTemplates.mjs` resolved them when the
+ * creator was packed - so nothing here has to know about workspaces or catalogs.
+ */
+export function scaffold({ templateDir, out, name, appId, appName }) {
+  if (!existsSync(templateDir)) throw new Error(`no template at ${templateDir}`);
+  if (existsSync(out)) throw new Error(`${out} already exists`);
+
+  const templateName = basename(templateDir);
+  const identity = { package: name, appId };
+
+  copyTree(templateDir, out, (entry, source) => {
+    const text = readFileSync(source, "utf8");
+    if (entry === "package.json" && source === join(templateDir, "package.json")) {
+      return manifest(text, { name: identity, appName, templateName });
+    }
+    return personalise(entry, text, { name: identity, appName });
+  });
+
+  // pnpm will not finish an install while a dependency's build script is neither allowed nor
+  // denied, and vite-plus pulls esbuild in. Without this every generated app fails its first
+  // `pnpm install` with ERR_PNPM_IGNORED_BUILDS.
+  writeFileSync(join(out, "pnpm-workspace.yaml"), "allowBuilds:\n  esbuild: true\n");
+
+  // Inside the monorepo the template leaned on the root for the ordinary ignores.
+  const ignore = join(out, ".gitignore");
+  const existing = existsSync(ignore) ? readFileSync(ignore, "utf8").trim() : "";
+  writeFileSync(
+    ignore,
+    [
+      "node_modules",
+      "dist",
+      "*.log",
+      ".env",
+      ".env.*",
+      "!.env.example",
+      ".DS_Store",
+      "",
+      "# Generated native projects. Recreate with `npx cap add android`.",
+      "android",
+      "ios",
+      "",
+      existing,
+      "",
+    ].join("\n"),
+  );
+
+  writeFileSync(
+    join(out, "README.md"),
+    `# ${appName}
+
+Generated from \`@cavulsqa/create\` (${templateName}).
+
+\`\`\`bash
+pnpm install
+pnpm dev            # browser, sql.js in memory - data does not survive a reload
+npx cap add android # once
+pnpm build && npx cap sync android && npx cap run android
+\`\`\`
+
+Android builds need **JDK 21**; an older one fails with \`invalid source release: 21\`.
+
+\`CLAUDE.md\` and \`.claude/\` carry the architecture an agent needs before editing anything here.
+`,
+  );
+
+  return { templateName };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@cavulsqa/create",
+  "version": "0.1.0",
+  "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
+  "keywords": [
+    "capacitor",
+    "create",
+    "framework7",
+    "scaffold",
+    "sqlite",
+    "template",
+    "vue"
+  ],
+  "homepage": "https://github.com/aybinv7/cavulsqa/tree/main/packages/create#readme",
+  "bugs": {
+    "url": "https://github.com/aybinv7/cavulsqa/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aybinv7/cavulsqa.git",
+    "directory": "packages/create"
+  },
+  "bin": {
+    "create-cavulsqa": "./bin/create.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
+    "vite-plus": "0.3.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "createConfig": {
+    "templates": [
+      {
+        "name": "f7-app",
+        "description": "Vue 3 + Framework7 + Capacitor + SQLite, tabbed shell, offline-first data layer",
+        "template": "./templates/f7-app"
+      }
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/bundleTemplates.mjs",
+    "check": "vp check",
+    "test": "vp test"
+  }
+}

package/templates/f7-app/.claude/rules/data-fetching.md

@@ -0,0 +1,67 @@
+# Reading and writing data
+
+Every read is a reactive query or a deliberate on-demand call. Every write goes through `rdb`. A
+third shape — a hand-rolled cache, or a raw write — produces "stale screen, no error, no symptom",
+which is the one failure an offline app cannot afford: the user has no network to blame.
+
+## Reads
+
+`useReactiveQuery(fn, { tables, queryKey, debounce })` from `@/shared/database/queries`.
+
+- **`tables` is the invalidation contract.** It must list exactly the tables `fn` reads — no more,
+  no less. Under-list and a write to the missing table leaves the screen stale with no error.
+  Over-list and an unrelated write re-runs an expensive query for nothing.
+
+  A join means every joined table. `loadOrderDetail` reads the order, its lines, the customer, the
+  product names and the customer's tags, so it lists all five. Count the tables in the SQL, not the
+  ones you were thinking about.
+
+- **`queryKey` is a process-wide identity, not a label.** Two mounted queries sharing a key await
+  one request and share its result — right for the same list rendered twice, wrong for two
+  different queries that happen to be named alike, and the second silently receives the first's
+  rows. Framework7 keeps pages mounted, so two instances of one screen genuinely coexist.
+
+  Default to `uniqueQueryKey("prefix")`. A stable literal is opt-in sharing, and anything
+  parameterised by a route param or a ref must never use one.
+
+- **`debounce`** collapses a burst. A loop of twenty inserts should refetch once, not twenty times.
+
+- Reads may take the database directly: `searchOrders(getDatabase().db, term)`. Repositories take
+  the database as a parameter rather than reaching for the singleton, which is what makes them
+  testable — `tests/sales.repository.test.ts` runs them against sql.js.
+
+## Writes
+
+Always `rdb`, never `getDatabase().db`:
+
+```ts
+await saveOrder(rdb, { customerId, reference, lines });   // announces sales_order, order_line
+await saveOrder(getDatabase().db, …);                     // writes, and nothing notices
+```
+
+`rdb` wraps Kysely so a mutation publishes the tables it touched on the change bus. A raw write
+lands in SQLite and no query hears about it, so the screen keeps showing the old rows until
+something unrelated triggers a refetch. There is no error and nothing to see in review.
+
+Anything that must be all-or-nothing goes in one transaction. `saveOrder` writes the order and its
+lines together because a half-written order is worse than no order.
+
+## Forbidden
+
+A module-scope `Map` or `ref` holding fetched rows with neither a TTL nor a bus subscription. Once
+populated it never refreshes for the session, and the next write is invisible until restart.
+In-flight dedup (a `Map<key, Promise>` cleared in `finally`) is concurrency control, not a cache,
+and is fine — `useReactiveQuery` already does it.
+
+## Seed and demo helpers
+
+Anything a person can press twice must survive being pressed twice. `seedSampleData` inserts the
+catalogue only where missing and upserts tags, because a plain insert threw
+`UNIQUE constraint failed: tag.label` on the second press.
+
+## Proof obligations
+
+- A new query: state which tables its SQL touches and that `tables` matches.
+- A new write: state that it goes through `rdb`, and whether it needs a transaction.
+- Either: a test in `tests/` exercising it against sql.js. Type-checking a query proves nothing
+  about what it returns.

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

@@ -0,0 +1,65 @@
+# Schema and migrations
+
+`src/shared/database/schema.ts` is what Kysely type-checks every query against.
+`src/shared/database/migrations.ts` is what actually creates the tables. The two are edited
+together, always: a field in one and not the other is a runtime error the compiler cannot see.
+
+## Migrations
+
+- Keys are ordered lexically and recorded once applied, so they are **numbered and never renamed**.
+  Renaming one makes it run again on a database that already has it.
+- Never edit a migration that has shipped. Add the next one.
+- A synced table is created with `createTableWithDefaults` when it carries the sync contract, or a
+  plain `createTable` when it does not. This template has no server, so plain tables are the norm.
+- Declare foreign keys, and index the columns screens filter and join by. Without them every
+  dashboard aggregate is a full scan, which you will not notice until the table is large and the
+  device is slow.
+- SQLite ignores foreign keys unless asked; `PRAGMA foreign_keys = ON` runs at the end of the
+  migration. It is per-connection, so a cascade is not something to rely on — `deleteOrder` removes
+  the lines explicitly.
+
+## Types
+
+- Money is **integer cents**, named `*_cents`. A float total is a rounding bug waiting for a
+  large-enough order.
+- Timestamps are ISO strings via `nowISO()`.
+- A price copied onto an order line is copied deliberately, so a later catalogue change does not
+  rewrite history.
+
+## Getting an inserted id
+
+Use `insertId`, never `.returning(...)`:
+
+```ts
+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");
+```
+
+The SQLite plugin runs a statement issued inside an open transaction through `query()`, which
+executes it and drops its RETURNING rows. `.returning("id").executeTakeFirstOrThrow()` therefore
+threw `no result` from an insert that had in fact succeeded — a message that sends you hunting for a
+failed write. `@cavulsqa/mobile-db` now throws a message that says so, and fills `insertId` from
+`last_insert_rowid()` on both sides of a transaction boundary. The sql.js test dialect reports it
+too, so a repository written this way behaves the same in tests as on a device.
+
+## The web path is not the device path
+
+On a device the database is a real file behind the Capacitor plugin. In a browser it is sql.js in
+memory, through the dialect `@cavulsqa/mobile-db` ships for its own tests. Two consequences:
+
+- Browser data does not survive a reload. That is expected, not a bug to fix.
+- The plugin's own web mode is deliberately unused: it needs a `jeep-sqlite` element and a
+  `sql-wasm.wasm` whose build must match the glue jeep-sqlite bundles, a pairing outside this
+  template's control that fails as a `WebAssembly LinkError` on an upstream bump.
+
+Measurements taken in a browser do not transfer. Concurrent reads are several times faster than
+sequential ones **on a device**, because the native bridge pipelines them; in memory there is no
+bridge and the ratio sits at 1.
+
+## Proof obligations
+
+A schema change needs a test in `tests/` that runs the migration and the affected queries against
+sql.js. `tests/sales.repository.test.ts` is the pattern: build a Kysely on `createSqlJsDialect()`,
+migrate, then assert on real rows — including the arithmetic. A total that type-checks can still be
+computed wrong.

package/templates/f7-app/.claude/rules/framework7-ui.md

@@ -0,0 +1,79 @@
+# Framework7 UI
+
+Framework7 owns the look. Your job is to compose its components, not to restyle them.
+
+## Components arrive by resolver
+
+`Framework7VueResolver` (in `vite.config.ts`, implemented in
+`src/shared/utils/resolvers/resolvers.ts`) imports each `f7-*` component where it is used. So:
+
+- Never write `import { f7Page } from "framework7-vue"`.
+- Never call `registerComponents`.
+- Use PascalCase tags: `<F7Page>`, `<F7ListItem>`, `<F7BlockTitle>`.
+
+If a component renders as an unknown element, its kebab name is missing from the resolver's list —
+add it there. Do not add a name the installed `framework7-vue` does not export: `f7-toolbar-pane`
+is a Framework7 9 CSS class with no Vue component in framework7-vue 8, and resolving it fails as a
+runtime `SyntaxError`, not a warning. Check the package's exports before adding.
+
+`f7`, `f7ready` and `theme` are auto-imported. `f7route` and `f7router` are **not** — Framework7
+passes them to a route component as props:
+
+```ts
+const props = defineProps<{ f7route: Router.Route; f7router: Router.Router }>();
+```
+
+## Write no CSS
+
+No backgrounds, no heights, no safe-area padding, no font sizes for body text. Framework7's theme
+provides all of it for both iOS and Material, light and dark. `app.css` is one line.
+
+Tailwind is available for layout and spacing inside a component — flex, grid, gaps, a text size on
+a number. The moment you reach for a colour or a background, stop: use a Framework7 component or a
+theme variable.
+
+## Lists
+
+`F7ListItem` renders `subtitle`, `text` and `#media` **only in a media list**. Outside one they are
+dropped silently — the quantity line on the order detail vanished exactly this way.
+
+- Short label + value: a plain `F7List` with `title` and `after`.
+- Anything with a description: `F7List media-list`, value in `subtitle`, prose in `#text`.
+- `item-footer` is sized for a few words. Long text in it overlaps the title, and a long `after`
+  squeezes the text into a one-word-per-line column.
+
+## Icons
+
+framework7-icons is a **ligature font**: a wrong name renders nothing at all — no warning, no
+fallback, no console message. This template has shipped invisible icons twice.
+
+- Verify against the font, never from memory, another icon set, or a filename in the package. The
+  React components in `framework7-icons/react` are SVG wrappers whose names do **not** match the
+  ligatures — trusting them broke four working icons.
+- The name keeps the underscore before a digit: `arrow_2_circlepath`, `square_grid_2x2_fill`.
+- SF Symbols names are not F7 names. It is `search`, not `magnifyingglass`.
+- `tests/icons.test.ts` checks every name in the app against the ttf. It is the authority.
+
+Per-theme icons where the platform look matters: `icon-ios="f7:house_fill"` beside
+`icon-md="material:home"`. Material glyphs need the bundled font in `assets/css/icons.css`, or they
+render as the literal word.
+
+## Gestures
+
+Swipeout inside swipeable tabs claims the same horizontal drag as the tabs. Put
+`swiper-no-swiping` on the list, or one gesture does both.
+
+## Navigation
+
+- Tabs are data in `src/app/tabs.ts`. Each tab is a view with its own history.
+- A pushed page calls `useHiddenTabbar()`. The tab bar belongs to the tab roots; on a detail screen
+  it is navigation to somewhere you are not.
+- A route's `async` is Framework7's hook, not an async function — resolve from a promise, `await`
+  inside it does not compile.
+- Actions on a detail screen belong in an `F7Toolbar bottom`, which spaces links evenly and clears
+  the safe area. A hand-built fixed bar does neither.
+
+## Proof obligations
+
+State that `vp test` passes (it includes the icon check), and say plainly whether you have seen the
+screen render. A screen that type-checks can still be an empty box.

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

@@ -0,0 +1,43 @@
+# Modules, domains and shared
+
+```
+modules/<feature>/router/routes/<feature>.routes.ts   default export, Router.RouteParameters[]
+modules/<feature>/views/<Name>View.vue                thin, presentational
+modules/<feature>/components/*.vue                    props in, emits out
+modules/<feature>/composables/use*.ts                 the feature's state and actions
+domains/<domain>/<domain>.repository.ts               SQL only
+shared/…                                              what two modules genuinely both need
+```
+
+## The seam
+
+A **view** wires a composable to components. If it holds business logic, that logic belongs in the
+composable; if it holds SQL, that belongs in a repository.
+
+A **composable** owns state, queries and actions for one feature. It may import repositories and
+the reactive query helpers. It returns refs and functions, never markup.
+
+A **repository** is plain functions over Kysely. No `ref`, no lifecycle, no Framework7, no imports
+from `modules/`. It takes the database as a parameter — that is what makes it testable, and reaching
+for the singleton instead is what made the first version of this template untestable.
+
+A **component** takes props and emits events. It does not query the database.
+
+## Direction of dependencies
+
+`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.
+2. Its routes in `router/routes/<feature>.routes.ts`, registered in `src/router/index.ts` before the
+   global catch-all.
+3. A tab in `src/app/tabs.ts` only if it is a top-level section. Otherwise it is a pushed page, and
+   pushed pages call `useHiddenTabbar()`.
+4. Strings in **both** `locales/en.json` and `locales/fr.json`. A missing key renders the key.
+
+## shared/ is not a junk drawer
+
+Something goes in `shared/` when two modules import it today. Not when one module might later. The
+test is: can you name the second caller? If not, it lives in the module that uses it.