@topy-ai/maggie 0.7.52 → 0.7.54

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:`
@@ -206,10 +223,18 @@ leaving contradictory claims current.
 The CLI never submits automatically. After reviewing the draft:
 
 ```bash
-maggie feedback submit .maggie/feedback/<feedback-id>.json \
-  --endpoint https://feedback.noblox.app/api/feedback --confirm
+maggie feedback submit .maggie/feedback/<feedback-id>.json --confirm
 ```
 
+Without `--endpoint` the draft goes to `https://feedback.noblox.app/api/feedback`
+and, only when that host fails before storing it (no connection, timeout, or a
+5xx such as Cloudflare's 526), to `https://feedback.cmo.so/api/feedback`. Both
+accept the same contract and de-duplicate on `feedbackId`, so a retry never
+creates a second record. A 4xx is the host rejecting the draft and is not
+retried elsewhere. The saved `submission` records the `endpoint` that accepted
+the draft and any `failedEndpoints`. Repeat `--endpoint URL` to give your own
+ordered list. Do not hand-edit drafts to point at a different host.
+
 Only HTTPS endpoints are accepted. Project paths, file contents, secrets, and
 logs are excluded by default. `--allow-project-context` is an explicit opt-in;
 even then, send only a short public-safe context note. After submission, the

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 "lakeview" finds "Lake View 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 "lakeview" for "Lake View 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 "lakeview", "Lake-View" and
+ * "Lake View 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)).
@@ -104,11 +110,53 @@ prints the exact commands with the cost notice and runs nothing:
 
 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. Run
-`fingerprint:compare` against the target build before every update; if only
-`eas.json` differs, publish from the build-time `eas.json` (restore it, publish,
-restore the current file) and add `eas.json` to `.fingerprintignore` with the
-next native build so it stops affecting the runtime.
+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.
+
+### Monorepos: publish only to a runtime an installed build has
+
+In a pnpm monorepo the fingerprint also hashes pnpm's virtual-store paths
+(`node_modules/.pnpm/<pkg>@<version>_<peer hash>`), so a dependency change in
+**any** workspace package (React added to the website) can move the app's
+runtime. `eas update` then publishes to a runtime no build has — silently.
+`ignorePaths` and `fileHookTransform` cannot fix it: `@expo/fingerprint` adds
+each native module folder by its real path. Keep the installed builds'
+runtimes in a file and publish through the guard:
+
+```json
+{"ios": [{"build": 7, "eas_build_id": "…", "runtime": "19d7a260e8e2…"}], "android": []}
+```
+
+```bash
+maggie mobile ota-guard --project . --app-dir apps/app --platform ios --runtimes scripts/ota-runtimes.json
+maggie mobile ota-guard … --publish --message "Fix copy" --confirm
+```
+
+It computes the fingerprint (`expo-updates fingerprint:generate`), refuses
+when no installed build has it — naming the two ways out (a native build, or
+publishing from a worktree with the build's lockfile and workspace file after a
+frozen install) — and with `--publish --confirm` runs `eas update` and checks
+that the published runtime is the one it checked. Add a build's runtime to the
+file when it ships; drop it when nobody runs it. At the next native build set
+an explicit `runtimeVersion` with a native-change check, so unrelated
+workspace changes cannot move it. `preflight` warns about a fingerprint
+runtime in a pnpm workspace.
 
 Show the plan's `costNotice` and wait for confirmation before step 1.
 
@@ -123,7 +171,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.

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -124,6 +124,66 @@ It warns, with environment variable names and host classes only, when:
 
 Use `--rotating-refresh-tokens yes|no` when the code scan cannot tell.
 
+After an edit, prove the browser is running it before judging the change:
+`--base-url http://localhost:8081 --expect-symbol ComposerAutoGrow` fetches the
+page's same-origin scripts and fails when the served bundle lacks the name (a
+stale watcher, the wrong folder, or another session's server). For a local
+`--base-url` the report also names the process listening on the port and its
+start time; a server that was killed (exit 137) and replaced by another
+session fails with "port … is held by pid …".
+
+## Driving the browser during QA
+
+These rules come from sessions that rediscovered each of them:
+
+- **Find controls by role and accessible name, not by text.** Icon fonts put
+  private-use glyphs into `innerText` (a React Native Web tab reads
+  `"\nImage"` or `"Home"`), so exact-text matching fails. Match
+  `[role=tab]`, `[role=button]` with `aria-label`, or strip characters in
+  U+E000–U+F8FF before comparing.
+- **Click through the DOM when the automated window is in the background.**
+  Synthetic mouse clicks wait for the window to be visible and time out;
+  `element.click()` (or dispatching the event) works in a background window.
+  Keep real input for checks that are about input itself (hover, drag).
+- **Reuse the app tab.** Opening a new tab per check clutters the user's
+  browser and, with rotating refresh tokens, adds another app instance.
+  Navigate the existing tab, and close any tab you opened.
+- **Phone width when the window cannot be resized.** Some browser extensions
+  ignore window resizing. A same-origin `<iframe>` 390 px wide reuses the
+  signed-in session and is fine for layout checks **one at a time**: create
+  it, measure, remove it, then the next. The "no parallel iframes" rule is
+  about several app instances refreshing a rotating token at once, not about
+  a single frame. `maggie design app-collect` and `maggie qa fit-check` set
+  the size through the DevTools protocol and need no iframe.
+- **Long measurements run in the page, not in one call.** A loop over 30
+  routes inside one script call times out the browser tool. Start the loop in
+  the page (`window.__qa = {done: false, results: []}`; an async function that
+  pushes results), return immediately, then poll `window.__qa` with short
+  calls. Give each call a time budget of a few seconds.
+
+## Check that dashboards fit the screen
+
+When a dashboard must not scroll the page, check every route, tab and drawer
+at a short laptop and a phone viewport:
+
+```bash
+maggie qa fit-check --base-url http://localhost:4321 \
+  --route /merchant/bookings --route /merchant/settings \
+  --profile-dir .maggie/qa-profile --drawer-selector "[data-drawer-trigger]" \
+  --sidebar-selector "nav.sidebar" --output .maggie/qa-runs/fit.json
+```
+
+Default viewports are 1536x687 (a laptop with browser chrome) and 390x844.
+For each route it measures page overflow on both axes, then clicks every
+visible `[role=tab]` (`--tab-selector`) and measures again, then opens each
+drawer trigger on a fresh page and checks the dialog stays inside the
+viewport. Hidden panels are measured only after their tab is active — a
+panel measured while hidden reports zero, which also breaks screen-sized
+pagers that do not re-measure on tab change. Labels ignore icon glyphs.
+Writes are blocked unless `--allow-write <refresh path>` or `--allow-writes`;
+use `--cdp-url` to attach to a signed-in Chrome. Exit 1 lists each failing
+route, viewport and state, with the first element that is too wide.
+
 ## Check CORS for every method the client uses
 
 Before a release that adds or changes API calls from a browser or webview,

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -205,6 +205,39 @@ does not claim keyboard accessibility, network asset correctness or semantic
 content quality unless those checks run separately. Use the installed browser
 path explicitly when Bun is not in PATH.
 
+## Route checks: name the origin
+
+Release checks that crawl routes (dynamic SEO, localization routes, sitemap
+size) must take an explicit base URL — `--base-url` or a required
+`SITE_ORIGIN` that fails when unset — and print the origin they checked. A
+default such as `http://127.0.0.1:4321` silently hits another local project
+on that port and produces false "foreign URL" and sitemap-size failures.
+Prove which site answers first:
+
+```bash
+maggie seo origin-check --base-url http://127.0.0.1:4321 --project .
+```
+
+It compares the page's canonical / `og:url` and the robots sitemap host with
+`site` in `astro.config.*` (or `--expect-host`), fails when another site
+answers, and prints `checked origin: …`.
+
+## Personalised HTML fragments
+
+Per-person partials (recently viewed, recommendations, "your bookings",
+signed-in header fragments) are not public pages. Each must answer
+`Cache-Control: private, no-store` and `X-Robots-Tag: noindex`, with no
+`public`, `s-maxage` or CDN cache header. Global middleware that sets public
+HTML caching for every `text/html` response must leave a route's private
+header alone (check for an existing `Cache-Control` before setting one);
+otherwise a CDN caches one person's fragment and serves it to everyone. The
+public-session cache contract covers full pages; fragments follow this rule:
+
+```bash
+maggie seo fragment-check --url http://127.0.0.1:4321/fragments/recently-viewed \
+  --url http://127.0.0.1:4321/fragments/recommendations --cookie-env QA_SESSION_COOKIE
+```
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -486,6 +486,29 @@ FAQ helper from the first category implementation; it is a known gap and must
 remain marked incomplete until each FAQ record is independently AI-authored and
 reviewed.
 
+## Moving a business: clients, appointments, gift cards
+
+Importing the provider catalogue is not enough to switch a real business.
+Dry-run the exports first (nothing is written):
+
+```bash
+maggie service migrate-check --project . --timezone Europe/London --market uk \
+  --clients clients.csv --appointments appointments.csv --gift-cards gift-cards.csv \
+  --service "Lash lift" --service "Massage" --staff Jo --staff Sam
+```
+
+It recognises Fresha's (and other systems') column names by synonyms and
+lists unmapped columns; de-duplicates clients by e-mail, then by phone in
+E.164; keeps marketing consent only when the export says opted in; keeps
+only future, not-cancelled appointments, converted with the venue's zone,
+and reports clashes and unmatched services or staff instead of forcing them;
+and keeps gift-card codes with their balance in an `IMPORT:` namespace. The
+report holds counts, column names and row numbers only — no client values —
+plus the undo key and plan. Every real import writes an import record first
+so it can be undone (bookings and unused clients/staff deleted, untouched
+imported codes voided), and an optional "we've moved" e-mail goes once, only
+to imported clients with marketing consent, while online booking is live.
+
 ## Payments: Stripe live setup and gift vouchers
 
 Service pages often lead to first-party payments. When the host takes money
@@ -494,9 +517,11 @@ read-only live setup runbook in `docs/maggiedash-booking/STRIPE-INTEGRATION.md`:
 
 - verify live state with list/retrieve (`GET`) calls only; never use a create
   call as a probe — a probe expected to fail can create a real live object;
-- the owner installs webhook and Connect event-destination signing secrets
-  with a no-echo command (`read -rs … | <secret store>`); the agent never sees
-  them;
+- the owner installs webhook signing secrets — and, on a platform that hosts
+  many businesses (Stripe Connect direct charges, see "Platform hosts" in
+  `STRIPE-INTEGRATION.md`), the Connect event-destination secret — with a
+  no-echo command (`read -rs … | <secret store>`); the agent never sees them.
+  A single business needs no Connect;
 - thin-event destination signing secrets cannot be retrieved via the API;
   roll them in the Dashboard if they were not captured;
 - the Stripe Dashboard may be unusable under browser automation, so hand

package/bundled-skills/maggie-social-share/SKILL.md

@@ -22,7 +22,7 @@ and GEO. It is not a second content source of truth.
 Create the reviewable channel contract before generating copy:
 
 ```bash
-maggie tool maggie_social_share.py plan content.json \
+maggie tool maggie_social_share.py plan content.json --workspace-domain example.com \
   --channels linkedin,facebook --output .maggie/social-share-plan.json
 maggie tool maggie_social_share.py validate .maggie/social-share-plan.json
 ```
@@ -30,6 +30,50 @@ maggie tool maggie_social_share.py validate .maggie/social-share-plan.json
 The CLI does not generate copy or publish. It validates identity, canonical
 URL, channel limits, UTM links, approval state, and provider post state.
 
+- **Own domain only.** A workspace shares articles published on its own
+  site. `plan` refuses a source whose canonical URL is not on
+  `--workspace-domain` (or a subdomain), and `validate` refuses an approved
+  draft without `workspace_domain`. Apply the same rule in source selection:
+  an account that manages several sites must not pick another site's
+  articles for this workspace's plan.
+- **Live links only.** Before planning posts from articles, drop the ones
+  whose link is gone. A site that moved platforms leaves old URLs that answer
+  404; posts scheduled with them reach readers as dead links.
+
+  ```bash
+  maggie tool maggie_social_share.py link-check .maggie/candidate-articles.json
+  maggie tool maggie_social_share.py plan content.json --workspace-domain example.com --check-link
+  ```
+
+  Only a definite 404 or 410 (also after redirects) drops an article. Blocked
+  (403/429), failing (5xx) or unreachable pages are kept, so a firewall or an
+  outage cannot empty the list; verdicts are cached for 6 hours
+  (`.maggie/social-link-cache.json`, `--ttl-hours`). Prefer the URL the site
+  reports for a delivered post over an older stored one (maggie-blog, "Where a
+  delivered post went live").
+- **One picture per idea.** Posts written together for several channels from
+  one idea share one picture on every channel, and a later picture change
+  (redraw, replace, rewrite of an idea that had one) is applied to every
+  channel of that idea, not only some. Write all channels of an idea through
+  the same path — an article-sourced channel (often LinkedIn) must join the
+  other channels' idea instead of being written separately. Check with:
+
+  ```bash
+  maggie tool maggie_social_share.py pictures .maggie/social-drafts.json
+  ```
+
+  It groups drafts by `idea_id` and fails a group whose channels carry
+  different pictures or one without; a channel whose picture a person chose
+  records `image_source: "user"`. `validate` applies the same rule to the
+  channels of one draft.
+- **Image posts by default.** When a post has its own image (`image_url`),
+  each channel gets `publish_mode: "image"` with the link in the text;
+  `link_preview` is the default only without an image. A person may switch a
+  post to link preview (record `publish_mode_source: "user"`), and the
+  preview shows the card LinkedIn will show. `validate` fails an image post
+  whose copy lacks the link and an image silently dropped by link-preview
+  mode.
+
 Before connecting providers or scheduling, check the adapter, connection,
 campaign, and queue contracts (shapes and rules in
 [queue and connections](references/queue-and-connections.md)):
@@ -68,7 +112,10 @@ maggie tool maggie_marketing_run.py validate .maggie/marketing-runs/<runId>.json
    optional `not_before`, and local/remote status. Posting hours are slots;
    do not persist a fixed `scheduled_at` per post (it goes stale and strands
    overdue posts). Campaign ideas stay in the idea stage until written, and a
-   campaign starts only through the Start gate.
+   campaign starts only through the Start gate. A series or campaign created
+   only so it can be planned is deleted (or never committed) when the AI plan
+   fails, so a retry does not leave an empty draft per attempt; `campaigns`
+   fails a campaign with `plan_status: failed` and no ideas.
 6. Publish only after the required approval and entitlement checks. Record the
    publication attempt and provider ID; reconcile unknown outcomes against
    readback and retry only with the original idempotency key.
@@ -101,8 +148,13 @@ idempotency, and delete/republish behavior.
   decrypt check on every host that serves social routes.
 - Provider avatar URLs are signed and expire; cache the bytes or refresh on
   readback.
-- Keep model structured-output enums small and validate large vocabularies
-  server-side; see [provider adapter contract](../../references/provider-adapter-contract.md#structured-model-output).
+- Structured-output schemas fail on **complexity**, not only on large enums:
+  no enum inside repeated array items, small `maxItems`, and validate the
+  vocabulary server-side. Run `maggie tool maggie_social_share.py
+  schema-check plan-schema.json` before a release; see [provider adapter
+  contract](../../references/provider-adapter-contract.md#structured-model-output).
+- Posted posts have a lifecycle (Post now, delete, edit and republish); see
+  [queue and connections](references/queue-and-connections.md#posted-post-lifecycle).
 
 ## Safety and commercial boundary