@topy-ai/maggie 0.7.51 → 0.7.53

package/bundled-skills/maggie-deployment/references/cloudflare.md

@@ -45,6 +45,7 @@ From the Astro starter:
 npm run build:cloudflare
 npx wrangler d1 migrations apply DB --local
 npx wrangler dev
+maggie deployment cloudflare-preflight --env production --env-file .env --verify-zone
 npx wrangler deploy --env staging
 npx wrangler deploy --env production
 ```
@@ -74,3 +75,21 @@ After deploy, check:
 - D1 migration version, R2/media delivery, KV/session behavior, API Pull,
   rewrite queue, and scheduled triggers are observable;
 - staging has no production analytics or email recipients.
+
+## Deploy preflight: never fall back to another account
+
+When `CLOUDFLARE_API_TOKEN` or `CLOUDFLARE_ACCOUNT_ID` is empty — for example
+a deploy script reading `CF_API_TOKEN` from `.env` — wrangler silently uses its
+cached OAuth login, which may belong to another Cloudflare account. It uploads
+a stray Worker there and then fails with `Can't infer zone from route ...
+[code: 10082]`; the live site keeps the old build and the stray Worker has to
+be deleted by hand.
+
+`maggie deployment cloudflare-preflight` fails before `wrangler deploy` when
+either variable is empty (from the environment or `--env-file`), names
+near-miss variables that are set instead, warns about a cached OAuth login,
+fails when the config's `account_id` differs from `CLOUDFLARE_ACCOUNT_ID`, and
+with `--verify-zone` checks with read-only API calls that the token verifies
+and that the account owns the zone of every route. Put `account_id` in
+`wrangler.jsonc` so wrangler itself refuses another account, and run
+`wrangler logout` on machines that only deploy with tokens.

package/bundled-skills/maggie-deployment/references/vps.md

@@ -155,6 +155,35 @@ inspect → plan → backup/migrate → npm ci → npm run build
 Deploy staging first. A passing build does not prove Nginx, systemd, DNS, TLS,
 robots, sitemap, or private-route correctness.
 
+### One command per release
+
+```bash
+maggie deployment vps-release --host deploy@203.0.113.10 \
+  --release-root /srv/site --service site --env-file /etc/site.env \
+  --subdir app --ref main --health-url https://www.example.com/ \
+  --health-url https://www.example.com/sitemap.xml            # dry run
+# review the printed remote script, then add --confirm
+```
+
+It names the release `<UTC timestamp>-<commit>` (never reused), uploads a
+`git archive` of that commit (no local build artefacts), installs and builds
+on the host **as the deploy user** with the server env file loaded, refuses
+files owned by anyone else, switches `current` atomically, restarts through
+the narrow sudoers rule, checks each health URL (retrying only 000/502/503/504)
+and then sends `--warm` requests before timing one, prunes to `--keep`
+releases, and prints a roadmap line. `--install`, `--build` and `--restart`
+override the defaults (`npm ci`, `npm run build`,
+`sudo -n systemctl restart <service>`).
+
+**Build as the deploy user, never with sudo.** `sudo bash -c 'set -a; .
+/etc/app.env; npx astro build'` leaves root-owned `dist/` and cache files;
+the retention prune then fails with "Permission denied" and the narrow sudoers
+contract (systemctl only) cannot remove them. Make the env file readable by
+the deploy group (`chgrp deploy /etc/app.env; chmod 640 /etc/app.env`)
+instead. `vps-release` refuses to run as root, refuses an unreadable env
+file, and reports releases it cannot prune with the one-time fix
+(`sudo chown -R deploy: <release>`).
+
 ### Release retention
 
 The retention policy is one explicit number, `--keep-releases N` (default 2),
@@ -198,6 +227,69 @@ maggie deployment secret-parity \
 
 Run it after adding a secret and before enabling a host in a pool.
 
+### Surgical multi-host copies
+
+When a fix copies a few built files to several hosts instead of a full
+release, first prove every host still holds the copies of the deployed
+commit, so the copy does not hide a hand edit or a half-finished earlier
+deploy:
+
+```bash
+maggie deployment file-parity --host api-1 --host api-2 --host api-3 \
+  --root /srv/api/current --subdir api --ref <deployed commit> \
+  --path dist/server/entry.mjs --path dist/server/chunks/routes.mjs
+```
+
+Each host's files are hashed over ssh (stdin script, no quoting through
+ssh) and compared with `git show <ref>:<path>` and with the other hosts; a
+file that differs or is missing fails, a file that does not exist at the ref
+is reported as `new-file`.
+
+### Judge latency after warm-up
+
+The first requests after a restart start the workers (often 8-16 s with
+several workers). Warm each host before deciding a release is slow:
+
+```bash
+maggie deployment warm-check --url https://api.example.com/health --warm 4 --samples 5 --budget-ms 800
+```
+
+`--warm` should be at least the number of worker processes; only the later
+samples are judged.
+
+### Failover must not replay writes
+
+An edge or proxy with ordered upstreams may retry the next host when one is
+down. Retrying is only safe when the first host never ran the request:
+
+- Fail over on **connection errors and timeouts before a response**, and on
+  502/503/504 **only when the body is the gateway's own error page**
+  (HTML/non-JSON from the proxy). An application's JSON 5xx ("the AI plan
+  failed") is the app's answer: relay it to the client.
+- **Never re-send a non-idempotent request** (POST/PATCH/DELETE) to another
+  upstream unless it carries an `Idempotency-Key` the app honours. nginx does
+  not retry non-idempotent requests unless `proxy_next_upstream
+  non_idempotent` is set — do not set it; keep `proxy_next_upstream error
+  timeout` for writes.
+- Let the app mark its own errors (for example `X-App-Error: 1` or
+  `Content-Type: application/json`) so the edge can tell them apart.
+
+A JSON 502 treated as "upstream down" replayed a create on a second host and
+left an orphan record per failover.
+
+### Local servers in checks
+
+Start local servers with a pid file and stop them by pid; never
+`pkill -f '<pattern>'` from the same shell command — the pattern also matches
+the shell running the command, which kills it, and later steps silently do
+not run:
+
+```bash
+node dist/server/entry.mjs & echo $! > .maggie/server.pid
+# ... checks ...
+kill "$(cat .maggie/server.pid)" && rm -f .maggie/server.pid
+```
+
 ### Environment isolation
 
 A local `.env` must never point at the production database. Shared databases

package/bundled-skills/maggie-design/SKILL.md

@@ -333,7 +333,13 @@ the project's auth or device-capability implementation:
 - `--viewport tablet=768x1024` overrides a plan viewport; the evidence and
   screenshots must then match it.
 - `--pattern` attaches acceptance rules from
-  [app UI patterns](references/app-ui-patterns.md) to the QA scenarios.
+  [app UI patterns](references/app-ui-patterns.md) to the QA scenarios:
+  `tabbed-modal`, `editor-sheet-assistant`, `usage-hero`, `site-switcher`,
+  `background-job` (slow media generation: a job per workspace, Stop or
+  replace, one toast), `chat-composer` (one-line auto-grow composer), and the
+  no-page-scroll dashboard set `hash-tabs`, `right-drawer`,
+  `two-column-sheet`, `screen-pager` (check those with `maggie qa
+  fit-check`).
 
 Expo Router files (`app/<route>.tsx`, `app/<route>/index.tsx`) are detected as
 the route source. The plan never collects credentials or copies private data.
@@ -370,9 +376,27 @@ when `fullPage: true`). A top-level `shell.scrollOwnerCount` is ignored with a
 warning, and a signature-only or scaled screenshot fails. The machine-readable
 contract is
 [mobile-app-surface-v1.schema.json](../../bundled-contracts/maggie-design/mobile-app-surface-v1.schema.json).
+Native iOS modals need one more check. `<SafeAreaView>` inside an Expo Router
+modal route (`presentation: "transparentModal"`, `"modal"`, …) or a React
+Native `<Modal>` can measure a 0 top inset on iOS, putting the header and
+Close under the notch or Dynamic Island; web screenshots at 390/768/1440
+cannot show it:
+
+    maggie design safe-area-check --project apps/app
+
+It flags those uses; pad with `useSafeAreaInsets()` from the root
+`SafeAreaProvider` instead (`// maggie-allow-safe-area-view` marks a reviewed
+exception). `app-init` adds an `ios-safe-area` scenario that needs a notched
+device or simulator screenshot.
+
 Keep `maggie design pressable-check` in the same loop for React Native Web
 apps: together they caught nested pressables and shell regressions during
-repeated sheet and modal changes.
+repeated sheet and modal changes. Add `maggie design textinput-check`: a
+`multiline` `TextInput` renders a 2-row `<textarea>` on web unless it has
+`numberOfLines` or an explicit height, and auto-grow driven only by
+`onContentSizeChange` grows but never shrinks on web (measure `scrollHeight`
+after collapsing; see the `chat-composer` pattern). `// maggie-allow-textinput`
+marks a reviewed exception.
 
 ### Onboarding wizards
 
@@ -706,7 +730,10 @@ It runs only when an `@import "tailwindcss"` entry exists (or with
 `--tailwind-v4`), honours `@layer` blocks and `layer(...)` imports, and fails on
 unlayered element or icon rules that set utility-competing properties.
 Unlayered `html`/`body` rules and class rules that set `display` are reported
-as warnings. Keep `css-cascade-check` for the rendered-browser proof.
+as warnings. In every project (Tailwind or not) it also warns about
+`width: max-content` rules and `w-max` classes without `max-width`/overflow
+handling: a tab strip or toolbar sized to its content makes a 390 px page
+scroll sideways — give it `overflow-x: auto` inside a `min-width: 0` parent. Keep `css-cascade-check` for the rendered-browser proof.
 
 ### Palette role contract
 

package/bundled-skills/maggie-design/references/app-ui-patterns.md

@@ -64,3 +64,82 @@ The first block of an inbox or account screen when usage limits matter.
   accessible name.
 - Account-level actions (add a site) are visually separated from per-site
   rows, and are audited at account scope, not under the open site.
+
+## `background-job` — slow media generation as a background job
+
+Image or video generation can take 1-2 minutes (more on a user's own
+ChatGPT plan). Never run it inside the request that started it.
+
+- **Start returns a job**: `POST .../generate` answers at once with
+  `{job: {id, itemId, startedAt}}`; the work runs in the background.
+- **One job per workspace** (or per user): a second start answers
+  `409 {busy: {jobId, itemId}}`; the UI asks "Stop it and start this one?"
+  and, on yes, calls start with `replace: true`, which interrupts the old job.
+- **State carries the job**: the item/list GET includes the running job, so
+  a reload, a second device or another tab shows it. Poll that GET every few
+  seconds while a job runs (no extra polling endpoint); stop polling when it
+  ends.
+- **On the item**: a spinner over its thumbnail or preview, and the same
+  action button becomes **Stop**.
+- **One toast** on done or failed (with the reason, e.g. "Your ChatGPT image
+  limit is used up"), never one per poll.
+- **Stale jobs expire** (for example after 10 minutes without progress) so a
+  crashed worker never locks the workspace.
+
+## `chat-composer` — one-line auto-grow composer (React Native Web)
+
+A `multiline` `TextInput` on web renders a `<textarea>` with the browser's
+default 2 rows, so an empty composer is ~56 px tall with the placeholder high
+and 40 px buttons low.
+
+- Give it an explicit single-line height (`numberOfLines={1}` or a
+  `style.height` equal to one line plus padding) and centre the row items.
+- Auto-grow on web by measuring: set the height to the minimum, read
+  `scrollHeight`, then set `min(scrollHeight, max)`. `onContentSizeChange`
+  never reports a smaller size on web, so a composer driven only by it grows
+  but never shrinks after text is deleted.
+- Align send/attach buttons to the bottom (`alignItems: "flex-end"`) so they
+  stay on the last line as it grows.
+- `maggie design textinput-check` flags multiline inputs without a height and
+  `onContentSizeChange`-only auto-grow.
+
+## Web dashboards that never scroll the page
+
+For dense desktop dashboards (settings, bookings, reports) where the owner
+wants no page scroll at a laptop viewport (1536x687 with browser chrome)
+and a usable 390 px phone layout. Check with `maggie qa fit-check`.
+
+### `hash-tabs` — tabs that keep state in the URL hash
+
+- `role="tablist"` / `role="tab"` / `role="tabpanel"`; the active tab is
+  `#tab-id` in the URL, restored on load and on `hashchange` (back/forward).
+- Emit a change event (for example `tabs:change` with the tab id) so
+  components inside a panel can re-measure when they become visible — a
+  hidden panel measures zero.
+- The tab strip scrolls sideways on phones (`overflow-x: auto`,
+  `min-width: 0` on the flex parent); never `width: max-content` without a
+  scroll container (`maggie design layer-check` warns).
+
+### `right-drawer` — details and forms in a drawer
+
+- A `role="dialog"` panel from the right (`min(480px, 100vw)` wide, full
+  height) that owns its scroll; the page behind does not scroll.
+- Disclosures with a lot of content ("Edit opening hours") open as a drawer
+  instead of expanding the page.
+- Escape, the close button and the backdrop close it and return focus to the
+  opener.
+
+### `two-column-sheet` — large modal with section quick-nav
+
+- A large modal (about 1100 px, max 90 vh) for long settings: sections in two
+  columns from 1024 px, one column below; the body is the only scroll owner.
+- A quick-nav (chips or a side list) scrolls the sheet to each section and
+  marks the current one.
+
+### `screen-pager` — page size from the viewport
+
+- The page size is the number of rows that fit the list's visible height;
+  re-measure on resize and on `tabs:change` when the list sits in a tab.
+- Use it only for client-side lists. When the server already pages, use the
+  server pager — two pagers on one list showed half pages and double
+  "next" buttons.

package/bundled-skills/maggie-feedback/SKILL.md

@@ -175,6 +175,23 @@ maggie feedback session-summary --project . \
 Evidence then reads `commit:<label>@<sha>`; unlabeled repositories become
 `repo1`, `repo2`, so local folder names never leave the machine.
 
+Each repository is read at `HEAD` unless you name a revision. Commits made in
+a temporary worktree and pushed with `git push origin HEAD:main` are not on a
+stale local `main`; the output then warns "local HEAD is N commit(s) behind
+origin/main". Fetch, then read the remote branch with `--repo
+api=../api@origin/main` (or `--rev origin/main` for every repository).
+
+`Area: sentence` subjects ("Booking: waitlist offers expire after two hours")
+are drafted as changes in that area, and the area or conventional-commit
+scope is kept. A busy product repository is mostly project work, not skill
+feedback: `--skill-relevant` keeps only commits that mention Maggie, a skill,
+a CLI, MCP or the `--skill` name, and reports the rest as
+`projectOnlyCommits`. A batch holds at most 50 items; when more commits
+qualify, the draft groups them into one item per scope (with up to 20 commit
+references each) and says so in `warnings`, instead of silently keeping the
+first 50. The draft's `commits` block records how many were seen, drafted,
+skipped and project-only.
+
 Review the file: delete items that concern the project rather than a Maggie
 skill or CLI, and replace every `REVIEW:` field (expected, actual, validation).
 `maggie feedback batch` rejects a file that still contains `REVIEW:`

package/bundled-skills/maggie-marketplace/SKILL.md

@@ -223,6 +223,18 @@ maggie skills smoke --out dist/marketplace --claude
 Nothing is published; push the output folder to the marketplace repository
 yourself after review.
 
+## Directory towns and name search
+
+A marketplace that lists businesses by town and lets people search names
+uses one shared module, [`directory.mjs`](references/directory.mjs),
+imported by the server and every node script (town pages, sitemaps, maps) —
+never a copy. It parses UK post towns and US "City, ST", falls back to the
+town field plus the state from the ZIP prefix when a US profile saved only
+the street, keeps non-US places in a US market ("Kingston, Jamaica"), and
+gives a normalised search key so "moonlake" finds "Moon Lake Spa", ranked
+exact → prefix → word prefix → contains. See [directory towns and
+search](references/directory-search.md) for the generated-column SQL.
+
 ## Rules
 
 1. Extract the template detail page first and save title, description,

package/bundled-skills/maggie-marketplace/references/directory-search.md

@@ -0,0 +1,51 @@
+# Marketplace directory: towns and name search
+
+Use [`directory.mjs`](directory.mjs) as **one** module that the server and
+every node script import (town pages, sitemaps, maps). It is plain
+JavaScript so `node scripts/x.mjs` can import it without a build step; a
+script that keeps its own copy drifts (a map script's copy had lost a rule
+the site had fixed).
+
+## Towns
+
+`parseTown(address, market, locality, postcode)` returns
+`{slug, name, label, region}` or `null`:
+
+- UK: the post town before the postcode ("…, Leeds LS1 4AB" → Leeds),
+  skipping fragments such as "Unit 3", "Rear", "Farm" or "…Road"; falls back
+  to the separate town field.
+- US: "City, ST 12345" → "City, ST". When the profile form saved only the
+  street, the separate town field plus the **state from the ZIP prefix**
+  ("503 Maple Avenue West" + Vienna + 22180 → "Vienna, VA").
+- Places listed in a US market but outside the US keep their country
+  ("…, Kingston, Jamaica" → "Kingston, Jamaica").
+
+Profile forms must store street, town and postcode/ZIP (and state when the
+form has it); a form that saves only "street" drops the business from every
+town page. Re-run the town build after changing the parser and compare
+counts per town.
+
+## Name search
+
+People type "moonlake" for "Moon Lake Spa". Compare a normalised key —
+lower case, accents removed, letters and digits only (`searchKey`) — as well
+as the plain `ILIKE` match, and rank exact and prefix matches first
+(`nameMatchRank`). In Postgres keep the key in a generated column with an
+index:
+
+```sql
+ALTER TABLE businesses ADD COLUMN name_key text
+  GENERATED ALWAYS AS (regexp_replace(lower(unaccent_immutable(name)), '[^a-z0-9]+', '', 'g')) STORED;
+CREATE INDEX businesses_name_key_trgm ON businesses USING gin (name_key gin_trgm_ops);
+
+SELECT id, name,
+  CASE WHEN name_key = $2 THEN 0 WHEN name_key LIKE $2 || '%' THEN 1
+       WHEN name ILIKE $1 || '%' OR name ILIKE '% ' || $1 || '%' THEN 2 ELSE 3 END AS rank
+FROM businesses
+WHERE name ILIKE '%' || $1 || '%' OR name_key LIKE '%' || $2 || '%'
+ORDER BY rank, name LIMIT 20;
+-- $1 = the trimmed query, $2 = searchKey(query)
+```
+
+(`unaccent` is not immutable; wrap it in an immutable SQL function, or drop
+it when names are ASCII.) Suggestions use the same ranking.

package/bundled-skills/maggie-marketplace/references/directory.mjs

@@ -0,0 +1,112 @@
+/**
+ * Maggie marketplace directory helpers: town parsing and name search.
+ *
+ * One plain-JavaScript module (no build step) imported by both the server and node scripts (sitemaps, maps,
+ * town pages), so the directory and every generated artefact count the same towns. Copies drift: a map script's
+ * private copy of the parser had already lost a rule when the site's was fixed.
+ *
+ * @typedef {{ slug: string, name: string, label: string, region: string | null }} Town
+ */
+
+const UK_POSTCODE = /\s*\b[A-Z]{1,2}\d[A-Z\d]?\s*\d[A-Z]{2}\b\s*$/i;
+const COUNTRY_PART = /^(uk|united kingdom|usa|us|united states|england|scotland|wales|northern ireland|ireland)$/i;
+// Address fragments that sometimes sit where the post town should be.
+const NOT_A_TOWN = /^(above|below|behind|rear|inside|within|retail|retail park|unit|suite|floor|ground floor|first floor|farm)$|\s(rd|road|lane|ln|street|st|avenue|ave|drive|dr|close|way|parade|terrace)\.?$/i;
+
+/** @param {string} value */
+export const slugifyTown = (value) => value
+  .normalize("NFKD").replace(/[̀-ͯ]/g, "")
+  .toLowerCase().replace(/&/g, " and ").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+// First three ZIP digits → state, for US addresses saved without one (forms that keep street, town and ZIP only).
+/** @type {Array<[number, number, string]>} */
+const ZIP3_STATES = [
+  [10, 27, "MA"], [28, 29, "RI"], [30, 38, "NH"], [39, 49, "ME"], [50, 59, "VT"], [60, 69, "CT"], [70, 89, "NJ"],
+  [100, 149, "NY"], [150, 196, "PA"], [197, 199, "DE"], [200, 200, "DC"], [201, 201, "VA"], [202, 205, "DC"],
+  [206, 219, "MD"], [220, 246, "VA"], [247, 268, "WV"], [270, 289, "NC"], [290, 299, "SC"], [300, 319, "GA"],
+  [320, 349, "FL"], [350, 369, "AL"], [370, 385, "TN"], [386, 397, "MS"], [398, 399, "GA"], [400, 427, "KY"],
+  [430, 459, "OH"], [460, 479, "IN"], [480, 499, "MI"], [500, 528, "IA"], [530, 549, "WI"], [550, 567, "MN"],
+  [569, 569, "DC"], [570, 577, "SD"], [580, 588, "ND"], [590, 599, "MT"], [600, 629, "IL"], [630, 658, "MO"],
+  [660, 679, "KS"], [680, 693, "NE"], [700, 714, "LA"], [716, 729, "AR"], [730, 732, "OK"], [733, 733, "TX"],
+  [734, 749, "OK"], [750, 799, "TX"], [800, 816, "CO"], [820, 831, "WY"], [832, 838, "ID"], [840, 847, "UT"],
+  [850, 865, "AZ"], [870, 884, "NM"], [885, 885, "TX"], [889, 898, "NV"], [900, 961, "CA"], [967, 968, "HI"],
+  [970, 979, "OR"], [980, 994, "WA"], [995, 999, "AK"],
+];
+
+/** @param {string | null | undefined} zip @returns {string | null} */
+export const stateFromZip = (zip) => {
+  const match = (zip || "").trim().match(/^(\d{3})\d{2}(-\d{4})?$/);
+  if (!match) return null;
+  const prefix = Number(match[1]);
+  return ZIP3_STATES.find(([from, to]) => prefix >= from && prefix <= to)?.[2] || null;
+};
+
+// Places listed in a US market but outside the US ("…, Kingston, Jamaica"). Extend per market.
+/** @type {Record<string, string>} */
+export const OTHER_COUNTRIES = { jamaica: "JM", "puerto rico": "PR", bahamas: "BS", canada: "CA", mexico: "MX" };
+
+/**
+ * The post town (UK: "…, Leeds LS1 4AB") or city + state (US: "…, Allen, TX 75013, United States") of a place.
+ * A US address saved as street only falls back to the place's town and ZIP fields
+ * ("503 Maple Avenue West" + "Vienna" + "22180" → "Vienna, VA"); a non-US place in a US market keeps its country.
+ *
+ * @param {string | null} address formatted address
+ * @param {"uk" | "us"} market
+ * @param {string | null} [locality] the separate town/city field, when the form has one
+ * @param {string | null} [postcode] the separate postcode/ZIP field
+ * @returns {Town | null}
+ */
+export function parseTown(address, market, locality, postcode) {
+  const parts = (address || "").split(",").map((part) => part.trim()).filter((part) => part && !COUNTRY_PART.test(part));
+  if (market === "us") {
+    const stateIndex = parts.findIndex((part) => /^[A-Z]{2}(\s+\d{5}(-\d{4})?)?$/.test(part));
+    if (stateIndex >= 1) {
+      const name = parts[stateIndex - 1].replace(/^\d+\s+/, "");
+      const region = parts[stateIndex].slice(0, 2);
+      return { slug: slugifyTown(`${name}-${region}`), name, label: `${name}, ${region}`, region };
+    }
+    const country = OTHER_COUNTRIES[(parts.at(-1) || "").toLowerCase()];
+    if (country && parts.length >= 2) {
+      const name = /** @type {string} */ (parts.at(-2));
+      return { slug: slugifyTown(`${name}-${country}`), name, label: `${name}, ${parts.at(-1)}`, region: country };
+    }
+    const region = stateFromZip(postcode || parts.join(" ").match(/\b\d{5}(?:-\d{4})?\b/)?.[0]);
+    const name = (locality || "").trim();
+    return region && name ? { slug: slugifyTown(`${name}-${region}`), name, label: `${name}, ${region}`, region } : null;
+  }
+  for (let index = parts.length - 1; index >= 0; index -= 1) {
+    const name = parts[index].replace(UK_POSTCODE, "").replace(/^\d+[A-Z]?\s+/, "").trim();
+    if (!name || NOT_A_TOWN.test(name)) continue;
+    if (/\d/.test(name)) break;
+    return { slug: slugifyTown(name), name, label: name, region: null };
+  }
+  const name = (locality || "").trim();
+  return name ? { slug: slugifyTown(name), name, label: name, region: null } : null;
+}
+
+/**
+ * Name search key: lower case, accents removed, letters and digits only, so "moonlake", "Moon-Lake" and
+ * "Moon Lake Spa" meet. Store it in a generated column (see directory-search.md) and compare both forms.
+ * @param {string | null | undefined} value
+ */
+export const searchKey = (value) => (value || "").normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+
+/**
+ * Rank names for a query: exact (0) → prefix (1) → word prefix (2) → contains (3); null when it does not match.
+ * Plain ILIKE on the display name and the normalised key are both tried.
+ * @param {string} name
+ * @param {string} query
+ * @returns {number | null}
+ */
+export function nameMatchRank(name, query) {
+  const key = searchKey(name);
+  const q = searchKey(query);
+  if (!q) return null;
+  const plain = (name || "").toLowerCase();
+  const raw = query.trim().toLowerCase();
+  if (key === q) return 0;
+  if (key.startsWith(q)) return 1;
+  if (plain.split(/[^a-z0-9]+/i).some((word) => word.startsWith(raw))) return 2;
+  if (key.includes(q) || plain.includes(raw)) return 3;
+  return null;
+}

package/bundled-skills/maggie-mobile-app/SKILL.md

@@ -25,6 +25,12 @@ auth, payments, or data; the host app does.
 - Before browser QA, run `maggie qa app-preflight --project . --app-dir apps/app`.
   It catches both mistakes and warns about rotating refresh tokens and
   production-backed local servers (see `maggie-qa-workflow`).
+- After an edit, prove the browser runs it: add `--base-url
+  http://localhost:8081 --expect-symbol <name from the edit>`. The preflight
+  fetches the served entry bundle and fails when the name is missing (stale
+  watcher, wrong folder, another session's server), and reports which process
+  holds the port and when it started — a server killed (exit 137) and
+  replaced by another session shows up as a different pid or start time.
 - Design and validate signed-in routes with `maggie design app-init`,
   `app-collect` and `app-validate` (see `maggie-design`, including the
   [app UI patterns](../maggie-design/references/app-ui-patterns.md)).
@@ -58,6 +64,11 @@ with `--config-json` when the config is dynamic), `eas.json` and
   future binary would accept any JS update, including one that needs a new
   native module. Use one top-level `{"policy": "fingerprint"}`.
 
+It also fails when a `package.json` script runs `eas update --non-interactive`
+without `--environment` (EAS refuses it), and warns when an update script has
+no `eas fingerprint:compare` gate or when `eas.json` is not in
+`.fingerprintignore` under the fingerprint policy.
+
 It warns about missing export-compliance (`usesNonExemptEncryption`), an
 unpinned `cli.version`, per-platform-only runtime versions (what
 `eas update:configure` writes) and tab-indented `app.json` that
@@ -88,10 +99,35 @@ prints the exact commands with the cost notice and runs nothing:
    → TestFlight (iOS) or the Play internal track (Android). Add testers in
    App Store Connect / Play Console; internal testing needs no review.
 2. Without `--auto-submit`: `npx eas-cli submit -p ios --profile production --latest`.
-3. JS-only fixes: `npx eas-cli update --channel production --platform ios --message "…"`.
-   A native change (new module, permission, SDK upgrade) needs a new build;
-   the fingerprint policy stops an incompatible update from reaching old
-   binaries.
+3. JS-only fixes: first `npx eas-cli fingerprint:compare --build-id <installed build>`
+   — it must report no difference — then
+   `npx eas-cli update --channel production --environment production --platform ios --non-interactive --message "…"`.
+   `--environment` is mandatory in non-interactive mode. A native change (new
+   module, permission, SDK upgrade) needs a new build; the fingerprint policy
+   stops an incompatible update from reaching old binaries.
+
+### The fingerprint includes `eas.json`
+
+Editing `eas.json` after a build — even only adding `submit.ios.ascAppId` —
+changes the local fingerprint. An update published from that tree targets a
+runtime no installed build has, and EAS reports no error. Add `eas.json` to
+`.fingerprintignore` with the next native build so it stops affecting the
+runtime; until then, publish with the build's own config files:
+
+```bash
+maggie mobile plan --project . --app-dir apps/app --platform ios --build-ref <build commit>
+maggie mobile ota  --project . --app-dir apps/app --platform ios \
+  --build-ref <build commit> --build-id <installed EAS build id> --message "Fix copy"   # dry run
+# add --confirm to run it
+```
+
+`plan --build-ref` lists which of `eas.json` / `package.json` differ from the
+build commit. `ota --confirm` puts the build commit's copies in place, runs
+`eas fingerprint:compare --json` and compares the two hashes (the command
+exits 0 even when they differ), publishes the update only on a match, and
+always restores the working copies — checked by hash — even when a step
+fails. A mismatch with the build's own files means the change needs a new
+native build. `MAGGIE_MOBILE_EAS` overrides the `npx eas-cli` invocation.
 
 Show the plan's `costNotice` and wait for confirmation before step 1.
 
@@ -106,7 +142,18 @@ Show the plan's `costNotice` and wait for confirmation before step 1.
   and every permission's purpose string.
 - Account deletion must be reachable in the app when sign-up is.
 
-## 6. Readiness report
+## 6. In-person payments and push
+
+Tap to Pay and push notifications are server features with a native client;
+the host's payment and notification code stays the source of truth. See
+[payments and push](references/payments-and-push.md) for Stripe Terminal
+(Tap to Pay on iPhone entitlement, Android NFC, one Terminal location per
+branch, the connection-token endpoint on the business's connected account)
+and Expo push as one more channel of the host's notification worker (device
+table, tickets and receipts, pruning `DeviceNotRegistered` tokens, actionable
+notifications).
+
+## 7. Readiness report
 
 Before a store submission, record: preflight passed, app-validate passed for
 each signed-in route, QA run summary (`maggie qa summary`), the build and

package/bundled-skills/maggie-mobile-app/references/payments-and-push.md

@@ -0,0 +1,78 @@
+# In-person payments and push for an Expo business app
+
+Both features need a development or store build (not Expo Go) and a server
+that already owns payments and notifications. The app is a thin client.
+
+## Tap to Pay and card readers (Stripe Terminal)
+
+Server-driven readers (WisePOS E, S700) need no app at all: the server sends
+the amount to the reader and records the payment when Stripe reports the
+PaymentIntent succeeded. Tap to Pay turns the phone itself into the reader
+and needs the native SDK.
+
+**Account.** Payments go to the business's own connected account (direct
+charges). Every Terminal call — locations, readers, connection tokens,
+PaymentIntents — passes `stripeAccount: <connected account>`. Refuse reader
+setup until the account can take charges ("Connect payments first").
+
+**Locations.** One Terminal location per branch, created once from the
+branch address and stored on the branch (`stripe_terminal_location_id`).
+Readers and Tap to Pay sessions are registered to the branch the device is
+used at; never share one location across branches (receipts, reporting and
+reader discovery are per location).
+
+**Connection token endpoint.** `POST /api/.../terminal/connection-token`,
+signed-in staff only, returns `stripe.terminal.connectionTokens.create({location},
+{stripeAccount})`. Scope it to the staff member's business and branch; never
+cache a token server-side.
+
+**App.** `@stripe/stripe-terminal-react-native` with its Expo config plugin:
+
+- iOS: Tap to Pay on iPhone needs the
+  `com.apple.developer.proximity-reader.payment.acceptance` entitlement,
+  requested from Apple for the team and added to the provisioning profile,
+  iPhone XS or later on a current iOS, and Apple's merchant education screens
+  on first use. Location permission is required by the SDK.
+- Android: NFC hardware, a supported Android version, Google Play services,
+  and no developer options / rooted device in live mode; the SDK refuses
+  otherwise — show a clear "this phone can't take cards" message.
+- Discover with the Tap to Pay discovery method, connect to the branch's
+  location, collect and confirm the PaymentIntent created **by the server**
+  (amount and metadata come from the sale, never from the app).
+
+**Testing.** Test mode with the simulated reader (`simulated-wpe` for
+server-driven readers; the SDK's simulated Tap to Pay reader on device). Keep
+a test case per outcome: approved, declined, cancelled on the device,
+network lost after the tap (reconcile from the webhook, never charge twice).
+
+**Store review.** Services consumed outside the app (a treatment at the
+salon) must not use in-app purchase (App Store guideline 3.1.3(e), goods and
+services outside of the app); do not sell digital goods through the reader.
+
+## Push as a notification channel
+
+Push is one more channel of the host's notification worker (beside e-mail and
+SMS), not a separate system.
+
+- **Device table**: `user_id`, `business_id`, `expo_push_token`, `platform`,
+  `app_version`, `last_seen_at`, `disabled_at`. Register after sign-in and
+  permission, re-register on every app start (tokens change), and delete on
+  sign-out. One user may have several devices.
+- **Sending**: the worker batches up to 100 messages per request to the Expo
+  push API with the project's access token, and stores each **ticket id**
+  with the outbox row. Use the same once-only guard as e-mail (outbox key per
+  event + recipient + device).
+- **Receipts**: about 15 minutes later, fetch receipts for the stored ticket
+  ids. `DeviceNotRegistered` → disable the token; `MessageTooBig`,
+  `MessageRateExceeded`, `InvalidCredentials` → alert, do not retry blindly.
+- **Pruning**: disable tokens not seen for 90 days and tokens that failed
+  with `DeviceNotRegistered`; never keep sending to dead tokens.
+- **Actionable notifications**: register categories in the app
+  (`setNotificationCategoryAsync`, e.g. Accept / Decline for a booking
+  request). The action calls the normal API with the signed-in session; a
+  notification action is never an approval by itself for anything risky.
+- **Content**: no private details on the lock screen by default ("New booking
+  request" rather than the client's name and treatment); let the business
+  opt in to details.
+- **Preferences**: per event type and channel, stored server-side, honoured
+  by the worker before queueing.