@topy-ai/maggie 0.7.52 → 0.7.54

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

@@ -21,9 +21,9 @@ temporary project detail, secret, or unverified guess into active memory.
 
 ## Contract and safety boundary
 
-Read [`../../bundled-references/maggiedash-booking/README.md`](../../bundled-references/maggiedash-booking/README.md),
-[`TASKS.md`](../../bundled-references/maggiedash-booking/TASKS.md), and the task's linked
-reference before changing code. MaggieDash owns the manager UI and versioned
+Read the [PRD](../../bundled-references/maggiedash-booking/PRD.md), the
+[host adapter contract](../../bundled-references/maggiedash-booking/HOST-ADAPTER.md) and the
+task's linked reference before changing code. MaggieDash owns the manager UI and versioned
 contracts. The host owns routes, traditional email/password sessions,
 PostgreSQL connection/transaction lifetime, tenant authorization, provider
 credentials, payment webhooks, notifications, and deployment. MaggieDash also
@@ -32,11 +32,12 @@ booking, customer, configuration, schedule, health, audit, hold, and lifecycle
 persistence; it does not replace host connection ownership or payment/public-
 checkout adapters.
 
-For implementation work, use the leaf board and runbook:
-[`EXECUTION-BOARD.json`](../../bundled-references/maggiedash-booking/EXECUTION-BOARD.json)
-and [`TASK-RUNBOOK.md`](../../bundled-references/maggiedash-booking/TASK-RUNBOOK.md). Do not
-mark a task passed until its implementation gate, docs update, and evidence
-record are complete.
+Maintainers changing MaggieDash Booking itself work from the delivery board
+and runbook in the Maggie source repository (`docs/maggiedash-booking/`
+`EXECUTION-BOARD.json`, `TASK-RUNBOOK.md`, `TASKS.md`, `PROGRESS.md`); they are
+not installed with the skill. Do not mark a task passed until its
+implementation gate, docs update, and evidence record are complete. A host
+project records its own evidence in its own repository.
 
 Never put provider secrets, database credentials, payment card data, or a
 customer export in UI props, browser bundles, fixtures, screenshots, or
@@ -76,6 +77,47 @@ recovery-rehearsal evidence together with the runtime/browser/board gates.
 It applies the host-only evidence rule; fixture, test, and local environments
 cannot satisfy a required operational release artifact.
 
+## Booking rules every host implements the same way
+
+[`RULES.md`](../../bundled-references/maggiedash-booking/RULES.md) fixes the rules hosts kept
+rediscovering, each with shared test vectors
+([`booking-rules-v1.json`](../../bundled-contracts/maggiedash/booking-rules-v1.json)):
+the client manage-link state guard, payment after an expired hold (reinstate
+or refund in full), venue-time schedule inputs, bigint money from Postgres,
+till maths (add-ons already in the item price are not charged twice, service
+charge, vouchers, packages, split tips), deposit policies only with payments
+connected, reminder offsets with once-only markers and who-cancelled
+notices, `.ics` escaping and per-staff feeds, availability (split hours,
+rotas, per-staff durations, any-staff choice, gaps, groups, peak pricing,
+DST), roles and permissions with a PIN switch that only lowers the role and
+applies to pages, menus and actions, client safety (patch tests, blocked
+clients, health data), loyalty and memberships, team pay, and customer
+accounts.
+
+```bash
+maggie booking rules-vectors                      # reference implementation
+maggie booking rules-vectors --host-command "node scripts/booking-rules.mjs"
+```
+
+Wire `--host-command` to the host's own engine in CI: it reads one
+`{"rule", "input"}` JSON line and prints the result.
+
+A platform that hosts many businesses takes payments with Stripe Connect
+direct charges on each business's account (no application fee is a valid
+choice); see [Platform hosts](../../bundled-references/maggiedash-booking/STRIPE-INTEGRATION.md#platform-hosts-stripe-connect).
+Prepare an end-to-end test-mode run with:
+
+```bash
+maggie booking connect-qa --project . --detect
+```
+
+It refuses live keys, finds a test-mode connected account that can take
+charges (read-only), prints the `stripe listen --forward-connect-to …`
+command and lists the payment cases (deposit, 3-D Secure, decline, late
+payment, saved card no-show fee, package, membership, refund, simulated
+reader, dispute). Keep a hidden production smoke business for release smoke
+bookings (RULES.md, "Release smoke business").
+
 For local CLI regression, the sanitized no-customer fixture is
 [`fixtures/maggiedash/booking-runtime.v1.json`](../../bundled-contracts/maggiedash/booking-runtime.v1.json).
 
@@ -86,6 +128,12 @@ Booking installer:
 maggie booking install --project . --confirm
 ```
 
+Booking is an optional MaggieDash module: this installs the core (if it is
+not there yet) plus Booking, the same as `maggie dash add booking --confirm`.
+Install it only when the business takes bookings — `maggie dash install`
+alone gives a content site the core without payment or booking files, and
+`maggie dash recommend` says whether the site looks like it sells services.
+
 For a host project that does not already contain the Booking runtime packages,
 let the installer add only the missing dependencies through the package manager
 already declared by the project (`npm`, `pnpm`, `yarn`, or `bun`):
@@ -115,9 +163,12 @@ Use `--schedule systemd` or `--schedule cron` with `--ready` only to generate a
 reviewable scheduler artifact; enabling it remains an operator action after
 backup, migration, and release evidence checks.
 
-The default installer source is the public MaggieDash `0.2.8` distribution. It
-contains the released Astro `hostBootstrap` manifest and 47-route Booking
-source, including the tenant-scoped treatment package catalogue. A fresh public-source install, `maggie booking inspect`, and
+The default installer source is MaggieDash `main` (currently `0.2.14`; pin
+another release with `--ref`). It contains the released Astro `hostBootstrap`
+manifest and 47-route Booking source, including the tenant-scoped treatment
+package catalogue, and follows the booking rules above (manage-link state
+guard, late-payment reinstate/refund, reminder stages, who-cancelled and
+business notices, `.ics` attachments, permission-based own-bookings scope). A fresh public-source install, `maggie booking inspect`, and
 `astro build` are the release evidence; a local-source result alone is not.
 
 For a new host with a reviewed `DATABASE_URL`, the explicit one-command
@@ -320,7 +371,7 @@ settings, reports, and audit. If `permissions_json` is absent on a legacy role,
 apply the safe role defaults server-side; never treat a missing object as full
 read access. Explicitly granted staff capabilities must be honored by the
 route handler, while staff mutations remain limited to approved lifecycle
-transitions. Keep the access contract, Astro host, reference host, ORA mirror,
+transitions. Keep the access contract, Astro host, reference host, installed host copies,
 and CLI validator synchronized whenever a route capability changes.
 The bootstrap now uses the host's server-side Resend configuration to send
 single-use invitation and password-reset links; raw tokens are never stored.
@@ -475,8 +526,9 @@ Follow the task board rather than building a disconnected calendar first:
 6. Add the provider-neutral payment port and a test-mode adapter. Reconcile
    signed duplicate/out-of-order webhooks before enabling capture.
 7. Run the UI source gate, contract gate, host runtime conformance, browser
-   journeys, and release gate. Record each command in
-   [`PROGRESS.md`](../../bundled-references/maggiedash-booking/PROGRESS.md).
+   journeys, and release gate. Record each command in the host project's own
+   progress log (maintainers: `docs/maggiedash-booking/PROGRESS.md` in the
+   Maggie source repository).
 
 8. Verify the scheduled worker queues and delivers a reminder once for a
    confirmed booking inside the 24-hour window. Check the notification

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -70,6 +70,32 @@ Norwegian, Finnish, Greek, Hebrew, Czech, Romanian, Hungarian, Thai, Persian,
 and Swahili. Use BCP 47 regions such as `es-MX`, `pt-BR`, `ar-SA`, or `ja-JP`
 when market-specific copy is required.
 
+## Text keys are site-wide; generated pages need position keys
+
+A translation stored under its source text (a text hash) applies to **every
+page** that shows that text. That is right for a shared header and wrong for
+generic phrases on generated pages: "your practice" is 诊所 on a dental page
+and 事务所 on an accountants page, and only one translation can exist per
+text. For generated or templated pages (one page per industry, city or
+product), render the source page, then store each node's translation under a
+**per-page position key** (page + node position, with the source text hash so
+a changed source shows as stale). Keep text keys only as a fallback for text
+that is genuinely the same everywhere.
+
+```bash
+maggie localization key-check rows.json [--locale zh-hans]
+maggie localization fragments --html dist --brand "Maggie"
+```
+
+`key-check` reads per-page rows (`page`, `position`, `text`, `translation`)
+and lists source texts translated differently on different pages — each one
+needs position keys. `fragments` reads rendered HTML and lists text split
+around an inline brand span into one- or two-word pieces ("Can", "No.",
+"What") that cannot be translated alone; translate the whole sentence with
+the span as a placeholder instead. Agents writing in parallel must use one
+glossary for short shared fragments, or the same piece gets different
+translations from different writers.
+
 ## Email and lifecycle email
 
 Localized email is a content surface with its own checks. Resolve the

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

@@ -31,9 +31,35 @@ must already be configured for the project owner.
 maggie dash install --project . --confirm
 ```
 
+This installs **only the core**: the dashboard, the auth boundary
+(email/password sign-in, first-owner registration, password reset), the
+`/_maggie/admin` route, navigation and the core schema. It then reads the host
+(framework, existing sign-in, database, payments, whether the site sells
+services or publishes a blog, locales) and prints `recommendations`, one per
+optional module or companion skill with a reason. Install a module only after
+the user agrees:
+
+```bash
+maggie dash recommend --project .                 # analysis only, writes nothing
+maggie dash add booking --project . --confirm     # same as: maggie booking install --confirm
+```
+
+Booking is the optional code module MaggieDash ships (workspace, backend,
+schema, Stripe adapter, worker, env example). Blog, localization, social
+sharing and ops are Maggie skills that use the core panels; the
+recommendations name them. Never pass `--with booking` or `--all-modules` for
+a site that has not asked for bookings: a content-only site must not receive
+payment and booking files. A release without the module split (MaggieDash
+0.2.13 or older) still installs everything and says so in `notices`.
+
+Server settings in the Astro scaffold are read at run time
+(`src/lib/maggie/env.ts`). Never read a secret through `import.meta.env.X` in
+host code: Vite inlines it into the build output.
+
 The command is idempotent, preserves existing files unless `--force` is
-explicitly supplied, and records the resolved revision in
-`.maggie/dash-install.json`. It never accepts or stores a GitHub token as a
+explicitly supplied, and records the resolved revision and installed
+`modules` in `.maggie/dash-install.json` (a later `install` keeps refreshing
+modules that were added). It never accepts or stores a GitHub token as a
 CLI argument. For local development or a pinned checkout, use
 `--source /path/to/MaggieDash` or `--source URL --ref REF`.
 

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

@@ -17,9 +17,41 @@ metadata:
 - A multi-tenant assistant bridge host on a VPS is declared and checked with
   `maggie deployment bridge-plan`, `bridge-collect-script` and `bridge-check`;
   see [bridge host](../maggie-assistant-tools/references/bridge-host.md).
+  Declare `workloads` (`chat`, `photos`, `image-generation`) and
+  `network.proxyLimits`; `bridge-check` reads the effective nginx
+  `client_max_body_size` / `proxy_read_timeout` of the server block that
+  proxies to the bridge port and fails below 25m / 360 s for photos and image
+  jobs (a 512k / 300 s proxy cut them off).
 - Product CLI and MCP packages: `maggie product release-check|smoke|mcp-check`
   ([product release](../maggie-assistant-tools/references/product-release.md)).
 
+## Downstream surfaces after a major product release
+
+A product change is not released while an agent-facing surface still
+describes the old product. After any major change to the app, the dashboard or
+the backend API (a new feature or channel, a renamed tab, a changed rule or
+limit), walk every surface below and either update it or record "no change":
+
+| Surface | Check | Evidence |
+|---|---|---|
+| Remote MCP tools | New or changed API params and response fields have tools; descriptions use the product's words | `tools/list` on the live server: count and the new names |
+| Agent system prompts | In-app assistant and any hosted bridge/agent prompt name tabs, channels and rules as the app does | One question about the change answered correctly |
+| Skills catalog and marketplace | Grep skills for the old wording; `mcp_tools` lists only real tool names; any tool-name allowlist is in sync with the tool source | Validator passes; marketplace repo pushed; agent hosts re-synced and recycled |
+| CLI and MCP npm packages | Commands/columns for the new data; both package versions bumped together | `npm view <pkg> version` |
+| Third-party plugins (ChatGPT, IDE) | Usually nothing if they use the remote MCP; re-review when tool names or auth change | Plugin lists the new tools |
+| SDK / API client types | New response fields typed | Workspace typecheck |
+| Mobile app | Web deploy plus OTA when the native fingerprint matches; a new build when it does not | Fingerprint compare; update id |
+| Assistant memory | A new channel or surface gets its own memory channel | Memory read for that channel |
+| Docs | PRD task list, progress log and the deployment runbook | — |
+| Preview host protection | Before (or after) adding basic auth to a preview host, every workflow, script or webhook that sends to it is repointed to production or sends the preview's basic-auth credentials from a secret — a bearer token does not pass basic auth | `maggie deployment preview-auth-check --host preview.example.com --repo . --live` passes; the next run of each listed workflow is green and the public surfaces it feeds show the new version |
+| npm staged publishes | A just-published version can stay invisible as `latest` for minutes; do not report it until it is. `Cannot publish over previously staged version` means the earlier attempt was already accepted, not a failure | `maggie product published --package-name NAME --version X --publish-log publish.log` reports `live` |
+
+Run the walk in the release order (schema → backend → dashboard → app →
+MCP/agent → bridge → npm → skills) and record which surfaces changed in the
+release record. Keep publish tokens in an env file and pass them through a
+temporary npmrc (`NPM_CONFIG_USERCONFIG`) that is deleted afterwards; never
+print them.
+
 ## Edge and rendered canary
 
 After staging or production deployment, verify that the edge serves the
@@ -562,6 +594,12 @@ is on a request path; follow [cloudflare.md](references/cloudflare.md) to move
 the database to D1 and media to R2/Cloudflare Images or an explicitly selected
 external adapter.
 
+Run `maggie deployment cloudflare-preflight --env production --env-file .env
+--verify-zone` before every `wrangler deploy`: an empty
+`CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` makes wrangler fall back to its
+cached OAuth login, possibly another account, and upload a stray Worker
+there.
+
 ## VPS target
 
 Use `--target vps` for direct VPS hosting or
@@ -571,6 +609,16 @@ immutable releases, the `current` symlink, staging-first rollout, HTTPS
 verification, and rollback. Remote checks remain pending until the host,
 credentials, and explicit deployment confirmation are provided.
 
+For an SSR Node app with release folders, `maggie deployment vps-release`
+runs the whole release as one reviewed command (dry run by default): archive
+of a commit, install and build as the deploy user with the server env file,
+atomic switch, restart, health with warm-up, prune, roadmap line. Before a
+surgical copy to several hosts, `maggie deployment file-parity` proves every
+host still holds the deployed commit's files; `maggie deployment warm-check`
+judges latency only after warm-up requests. Failover between hosts must
+never replay a write: see "Failover must not replay writes" in
+[vps.md](references/vps.md).
+
 ## Provider boundary
 
 Deployment providers implement the same conceptual operations:

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

@@ -262,6 +262,59 @@ maggie design step author-<id> --project . \
 An author plan is not complete until every `requiredSteps` entry has matching
 evidence and the explicit approval step is recorded.
 
+### Bulk author mode (many similar pages)
+
+For a family of similar pages (one use-case page per industry, one page per
+city), use one bulk job instead of hand-built scripts:
+
+```bash
+maggie design bulk plan --project . --targets targets.json --brief BRIEF.md --facts FACTS.md \
+  --validator '["python3", "scripts/validate-page.py"]' --check links --check prices --confirm
+maggie design bulk next <job> --stage write          # next batch (default 8) with each page's currentHash
+maggie design bulk record <job> --target ID --stage written --expect-hash HASH
+maggie design bulk validate <job>                    # project validator + built-in checks
+maggie design bulk next <job> --stage picture        # only pages validated and unchanged since
+maggie design bulk record <job> --target ID --stage pictured
+maggie design bulk status <job>
+maggie design bulk seed <job> --confirm              # only when every page passed
+```
+
+The job enforces what goes wrong in a parallel run: a picture is drawn only
+for a page that validated and has not changed since (a picture worker must
+never rewrite a page a writer is still editing); a writer records with the
+hash it read and is refused if the page changed meanwhile (re-read, re-apply,
+record again); changing the brief, facts or validator mid-run sends every
+earlier pass back to `revalidate`; nothing is seeded until all pages are
+validated and pictured. Built-in checks: every internal link points at a page
+of the job or a `--known-routes` entry, and every price appears in the facts
+file. The project validator checks structure, counts, facts and translation
+coverage. Share one glossary between writers for short repeated fragments
+(see maggie-content-localization, position keys).
+
+### Page pictures: choose the engine before a large run
+
+`maggie media generate` draws one picture with either engine; `maggie media
+engine-plan` states time and cost first. Show the plan and wait for a yes
+before a run of more than a handful of pictures.
+
+```bash
+maggie media engine-plan --count 510 --size 2400x1000 --gemini-unit-cost <price>
+maggie media generate --engine gemini --size 2400x1000 --prompt "..." --output hero.png --confirm
+maggie media generate --engine codex --image screen.png --prompt "Redraw as a clean step picture" --output step.png --confirm
+```
+
+| Engine | Billing | Speed (observed) | Reference pictures |
+|---|---|---|---|
+| `codex` | the ChatGPT plan's quota via the local `codex` CLI, no per-picture charge | about 75 s | yes (`--image`, before `--`) |
+| `gemini` | the project's own `GEMINI_API_KEY` (its Google account) | about 19 s at 2K | no |
+
+For 510 pictures that is hours versus minutes. Gemini takes the nearest
+aspect ratio and a size from the target (2400x1000 → 21:9 at 2K; 1K up to
+1300 px, 2K up to 2600 px, else 4K); crop to the exact size and convert to
+WebP afterwards. `engine-plan` leaves the Gemini cost empty until you pass
+`--gemini-unit-cost` from the current price list. Only transient Gemini
+errors (429, 5xx, network) are retried.
+
 ## Content UI initialization
 
 Use content UI initialization when `maggie-blog` or
@@ -333,7 +386,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.
@@ -385,7 +444,40 @@ 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.
+
+Closing a modal sheet is the third iOS-only trap. Closing a sheet and, in the
+same tick, showing a toast, refreshing or writing query data, navigating,
+opening another sheet, or changing what the closing sheet shows can leave the
+sheet's transparent window on top of the app: it looks fine but takes no
+touches until the app is killed. Close first, then do the rest once it has
+slid away:
+
+    export const SHEET_CLOSE_MS = 450;   // the slide-out duration
+    export function afterSheetCloses(fn: () => void) {
+      if (Platform.OS === "web") fn(); else setTimeout(fn, SHEET_CLOSE_MS);
+    }
+    // setSheet(null); afterSheetCloses(() => { toast(...); refresh(); });
+
+    maggie design sheet-check --project apps/app
+
+`sheet-check` finds closes (`setSheet(null)`, `setXOpen(false)`, `onClose()`,
+and the setter of any state used in a sheet's `open`/`visible` prop) followed
+in the same block by a toast, a refetch/invalidate/`setQueryData`,
+`router.*`/`*.open(…)` or another sheet opening; work inside
+`afterSheetCloses`, `setTimeout`, `requestAnimationFrame`, a local helper that
+wraps them, or after `await new Promise(r => setTimeout(r, …))` is deferred and
+passes. Errors fail the check. Warnings: a parent callback (`onDone()`) right
+after a close, and a sheet whose content reads the same state as its `open`
+prop (`open={Boolean(item)} title={item?.label}`), which empties the sheet
+while it slides away — keep a separate open flag. `// maggie-allow-sheet-close`
+marks a reviewed exception. Keep it with pressable-check, safe-area-check and
+textinput-check in the app's lint loop.
 
 ### Onboarding wizards
 
@@ -719,7 +811,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.