@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-skills/maggie-clone-to-template/SKILL.md

@@ -67,6 +67,32 @@ then stores the prompt as
 `CUSTOMIZATION_PROMPT.md` beside the package. It creates a resumable job under
 `marketplace/.maggie/clone-to-template-jobs/`.
 
+### Neutral display identity
+
+A package's customer-facing identity is separate from its source evidence.
+`template.json` `name` and `id` are internal; `sourceMetadata` records the
+source title only as provenance. Pass a designed, neutral style name and a short
+description when planning:
+
+```bash
+maggie tool maggie_clone_to_template.py plan <url> "<approved brief>" --rename <template-id> \
+  --display-name "Olive Atelier" \
+  --display-description "A light editorial beauty homepage with olive accents."
+```
+
+Packaging forwards both to the marketplace importer. Without them, completion
+derives a name from the measured design (accent hue, display typeface,
+industry). The validator rejects a name that repeats a distinctive source-title
+word, looks like a counter (`Beauty Studio 20 001`), or duplicates another
+catalogue entry. Change it later with `maggie_marketplace.py identity <id>
+--display-name …`. Template pickers must show `displayName` and
+`displayDescription`, never the source business name.
+
+Packaging also measures `DESIGN.md` from the rendered CSS, records
+`screenshotReview`, and lists every asset with its provenance. Review captures
+stay at viewport height; tile any full-page capture as described in the
+`maggie-marketplace` package quality gates.
+
 If the full clone run fails or cannot reach `verified`, stop and report the
 clone checkpoint. Do not invoke the marketplace importer as a fallback. If the
 Maggie design review fails, stop before declaring the template ready.

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

@@ -2,7 +2,7 @@
 name: maggie-content-localization
 description: Manage translation, polish, rewrite, market localization, review, stale detection, and publishing for pages, guides, posts, services, products, and categories.
 metadata:
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Maggie Content Localization
@@ -70,6 +70,20 @@ 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.
 
+## Email and lifecycle email
+
+Localized email is a content surface with its own checks. Resolve the
+recipient locale as user preference > market > account > fallback; never
+hard-code a locale or rely on `Accept-Language` alone in fulfilment paths.
+`maggie localization email-matrix` checks missing locales, untranslated
+values, changed or undeclared variables, HTML/plain-text parity, market CTA
+routes, glossary terms, and approval, and can write fixture-filled previews.
+`maggie localization lifecycle` validates a consent-aware marketing plan
+(consent basis, unsubscribe and preference-centre paths, frequency cap,
+attribution, no send until approved) and `--library` drafts the standard
+template set with nothing sendable. Both are read-only and never send. See
+[email and lifecycle email](references/email-and-lifecycle.md).
+
 ## Invocation lifecycle
 
 At the start, run the memory hook for the current skill and load only relevant
@@ -98,6 +112,8 @@ maggie tool maggie_localization.py review .maggie/localization/<job>.json \
 maggie tool maggie_localization.py publish .maggie/localization/<job>.json --confirm
 maggie tool maggie_localization.py stale --project .
 maggie tool maggie_localization.py glossary --project .
+maggie tool maggie_localization.py email-matrix emails/manifest.json --preview-dir .maggie/localization/email-preview
+maggie tool maggie_localization.py lifecycle emails/lifecycle.json
 ```
 
 Operations are distinct: `translate` preserves meaning, `polish` improves

package/bundled-skills/maggie-content-localization/references/email-and-lifecycle.md

@@ -0,0 +1,83 @@
+# Localized email and consent-aware lifecycle email
+
+Email is a localized content surface. Treat every template × locale × market
+as a reviewable variant, and keep transactional/security messages separate
+from marketing consent. Both commands below are read-only: they never call a
+provider and never send.
+
+## Localized templates (`email-matrix`)
+
+Describe templates in a `maggie-email-localization.v1` manifest (schema:
+`contracts/maggie-content/email-localization-v1.schema.json`, shipped as
+`bundled-contracts/maggie-content/` in the npm package).
+
+Locale precedence is fixed: **user preference > market > account > fallback**.
+A send path must pass the resolved recipient locale. Two patterns fail:
+
+- a hard-coded locale (e.g. a fulfilment path that always renders `en`);
+- `Accept-Language` as the only source for fulfilment or transactional email.
+  For other paths it is only a hint and produces a warning.
+
+Declare each send path under `callSites` with its `localeSource` so the check
+covers code paths, not only templates.
+
+The check fails when:
+
+- a required locale or its subject/HTML/plain text is missing;
+- a translated field is identical to the source text (untranslated);
+- variables differ from the source field, are undeclared, or differ between
+  the HTML and plain-text bodies;
+- a CTA route is not a site path or `https` URL, uses a market whose prefix it
+  does not carry, targets a market that does not serve that locale, or changes
+  the template route's parameters.
+
+It warns about glossary terms not rendered as their approved translation,
+CTA routes missing from a body, unused variables, and unapproved variants.
+A variant is publishable only when its `approval` has `status: approved` and a
+`reviewer`; `--require-approved` turns that into a failure for release gates.
+
+```bash
+maggie localization email-matrix emails/manifest.json \
+  --preview-dir .maggie/localization/email-preview
+maggie localization email-matrix emails/manifest.json --require-approved
+```
+
+`--preview-dir` writes one `.html` and one `.txt` file per template × locale,
+filled from the template's synthetic `fixtures` (HTML-escaped) and labelled as
+a preview. Never put customer data in fixtures.
+
+## Lifecycle and marketing email (`lifecycle`)
+
+A `maggie-lifecycle-email.v1` plan (schema:
+`contracts/maggie-content/lifecycle-email-v1.schema.json`) runs through fixed
+stages: plan → segment → consent-check → preview → approve → schedule → send →
+report. `defaults.send` must be `disabled`: nothing is sent until approved.
+
+Start from the library, which drafts every kind with nothing sendable:
+
+```bash
+maggie localization lifecycle --library > emails/lifecycle.json
+maggie localization lifecycle emails/lifecycle.json
+```
+
+Library kinds: opt-in confirmation, welcome, digest, recommendation, gift /
+voucher / waitlist follow-up, merchant lead digest, campaign announcement,
+re-engagement.
+
+Rules the validator enforces:
+
+- Marketing templates need `consent.basis` (opt-in, double-opt-in,
+  soft-opt-in, or legitimate-interest-b2b) and a preference-centre
+  `consent.category`, an unsubscribe path, a preference-centre path, and
+  attribution fields (source/UTM) so outcomes can be measured.
+- Every template has a frequency cap (`maxPerWindow` + ISO 8601 `window`).
+- The opt-in confirmation is sent before consent exists, so it must be
+  transactional and carry no promotional content.
+- `sendable: true` requires an approval with `status: approved`, `reviewer`
+  and `approvedAt` — on the template and on the campaign.
+- Campaigns using marketing templates require consent, must honour
+  suppression, must deduplicate contacts, and need a schedule before they are
+  sendable. Declare aggregate report metrics; never report per-recipient data.
+
+The host owns consent records, segments, suppression lists, delivery and
+reporting. Maggie validates the plan; it does not send or store addresses.

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

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.4.0
+  version: 1.6.0
 ---
 
 # Maggie Deployment
@@ -88,6 +88,74 @@ not fabricate browser, rendered, or deployment evidence and does not deploy
 from this command. See
 [`readiness-v1.schema.json`](../../bundled-contracts/maggie-deployment/readiness-v1.schema.json).
 
+### Collect host evidence
+
+Instead of hand-written SSH, systemd, and retention scripts per host, declare
+the standard adapters once in `.maggie/deployment/collector.json`
+(`maggie-evidence-collector.v1`) and let one command run them and emit the
+same `maggie-deployment-readiness.v1` report:
+
+```json
+{
+  "schemaVersion": "maggie-evidence-collector.v1",
+  "release": "2026-10-10-a",
+  "adapters": {
+    "canary": {"assets": ["https://example.test/_astro/app.js=<sha256>"], "renderReport": ".maggie/rendered-canary.json"},
+    "health": {"urls": ["https://example.test/robots.txt", "https://example.test/sitemap.xml"]},
+    "rollback": {"evidence": "docs/deployment-rollback-smoke.json", "plan": ".maggie/deployment/vps/deployment-plan.json"},
+    "releaseIdentity": {"command": ["ssh", "-o", "BatchMode=yes", "maggie-deploy@host", "readlink -f /var/www/example/current"]},
+    "authCanary": {"plan": ".maggie/deployment/auth-canary-plan.json"}
+  }
+}
+```
+
+```bash
+maggie deployment collect --project . --config .maggie/deployment/collector.json
+```
+
+Adapters write their evidence under `.maggie/deployment/collected/` and the
+readiness report adds the optional `hostHealth`, `releaseIdentity`,
+`rollbackEvidence`, and `authenticatedCanary` slots next to the five required
+slots. `releaseIdentity` proves the host's `current` release (from an argv
+command such as `readlink -f`, or a `{"url", "field"}` version endpoint)
+equals the expected `release`. Commands are argv lists, never shell strings,
+and are rejected if they contain a literal credential. The report records the
+config SHA-256, the release, and per-adapter run metadata so it can be
+reproduced; it never deploys.
+
+### Authenticated API canaries
+
+Public canaries cannot see failures on signed-in account or business APIs
+(database permission errors, schema mismatches, 403s). Declare role-scoped
+probes in a `maggie-auth-canary-plan.v1` plan:
+
+```json
+{
+  "schemaVersion": "maggie-auth-canary-plan.v1",
+  "baseUrl": "https://example.test",
+  "roles": {"owner": {"tokenEnv": "CANARY_OWNER_TOKEN"}, "staff": {"cookieEnv": "CANARY_STAFF_COOKIE"}},
+  "probes": [
+    {"id": "account", "role": "owner", "path": "/api/account", "expectJsonKeys": ["id", "role"]},
+    {"id": "business", "role": "staff", "path": "/api/business", "expectStatus": [200]},
+    {"id": "fixture-create", "role": "owner", "method": "POST", "path": "/api/canary-fixtures", "fixture": "disposable", "expectStatus": [201]}
+  ]
+}
+```
+
+```bash
+CANARY_OWNER_TOKEN=... maggie deployment auth-canary \
+  --plan .maggie/deployment/auth-canary-plan.json --output .maggie/deployment/auth-canary.json
+```
+
+Credentials come only from the named environment variables of dedicated
+canary accounts; a plan containing a literal token or cookie is rejected.
+Mutating probes must target a `disposable` fixture and run only with
+`--allow-mutations`. Evidence (`maggie-deployment-auth-canary.v1`) records
+probe id, role, method, path, status, and contract-key counts, classifying
+failures as `authorization`, `server`, `route`, `contract`, or `network`;
+it never stores headers, cookies, tokens, response bodies, or personal data.
+A missing credential makes the probe `inconclusive`, not passed.
+
 Classify host/runtime failures before a release can move:
 
 ```bash
@@ -207,7 +275,7 @@ The output contains only the immutable release/current layout, systemd unit,
 Nginx reverse-proxy config, health commands, rollback command, and an ordered
 reviewable release runner. The runner keeps migrations before the symlink flip,
 carries `.agents`/`.claude` state, restarts before verification, and prunes to
-the current release plus one rollback candidate. It never
+the plan's retention policy (default: current plus one rollback candidate). It never
 contains credentials and never SSHs, changes DNS, restarts systemd or deploys.
 
 VPS plans use a dedicated deployer account by default:
@@ -225,9 +293,23 @@ when they are unmarked or stale; use `--check-runner PATH` for a runner stored
 elsewhere. Regenerate from the reviewed VPS plan, inspect the diff, and replace
 the checked-in runner only after review.
 
-VPS plans include a bounded retention policy: keep two immutable releases,
-preserve the `current` target and rollback target, and review prune candidates
-before any operator executes cleanup. Generate a read-only candidate report:
+VPS plans carry one explicit retention policy, `--keep-releases N` (1-5,
+default 2). The same value drives the plan's prune command, the generated
+runner's prune step, `--retention-plan`, preflight, and rollback evidence, so
+Maggie never advertises a rollback target the host deletes:
+
+- `N >= 2` keeps the `current` target plus the release it replaced; the plan's
+  `commands.rollback` switches back to it.
+- `N = 1` keeps only the active release. The plan reports
+  `retention.rollbackAvailable: false` and `commands.rollback: null`, the
+  runner prints `rollback target: unavailable`, and production rollback
+  evidence must declare `codeRollback: "unavailable"` with a `recoveryPlan`
+  (redeploy the previous commit as a new release and restore its data
+  checkpoint). Preflight's `rollback_target_retained` check fails when a plan
+  keeps one release but still advertises a previous-release rollback.
+
+Review prune candidates before any operator executes cleanup. Generate a
+read-only candidate report:
 
 ```bash
 maggie tool maggie_deployment.py --retention-plan \
@@ -236,8 +318,60 @@ maggie tool maggie_deployment.py --retention-plan \
   --keep-releases 2 --output .maggie/deployment/retention-plan.json
 ```
 
-The CLI never deletes release directories and never permits fewer than two
-retained releases.
+The CLI never deletes release directories; only the reviewed runner prunes,
+and only after health checks pass.
+
+### Multi-host secret parity
+
+When several hosts serve the same routes, check that each one holds every
+required secret. The check compares key names and SHA-256 fingerprints and
+never prints, stores, or transmits values:
+
+```bash
+# Local env files (one per host):
+maggie deployment secret-parity \
+  --host api-1=.secrets/api-1.env --host api-2=.secrets/api-2.env \
+  --required SOCIAL_SHARE_ENCRYPTION_KEY
+
+# Or fingerprint manifests produced on each host:
+maggie deployment secret-fingerprint --env-file /etc/example.env \
+  --host api-1 --output api-1.json
+maggie deployment secret-parity --manifest api-1.json --manifest api-2.json \
+  --required SOCIAL_SHARE_ENCRYPTION_KEY
+```
+
+A required key that is missing or differs on any host fails the check. Other
+drifting keys are warnings unless `--strict` is set. A host without Maggie can
+use the no-echo shell snippet in [the VPS reference](references/vps.md); the
+parity command accepts its `KEY <sha256>` output directly. Manifests that
+contain anything other than names and 64-character hex digests are rejected.
+
+### Local and production database isolation
+
+```bash
+maggie deployment env-isolation --project . \
+  --production-env .env.production
+# or: --production-db-host db.example.net
+```
+
+The check fails when the local `.env` points at the production database (same
+host, and port/name when known). The same server with a different database is
+a warning. Deployment preflight runs the check automatically, as a non-blocking
+warning, when `.env.production` exists or `MAGGIE_PRODUCTION_DB_HOST` is set.
+Database URLs are reduced to host/port; credentials are never reported.
+
+### Release ordering for workers and notification templates
+
+Deploy the worker and its templates before any code path can enqueue an event
+that uses a new template. When local development or a staged app shares a
+queue with production, an event that names a template the running worker does
+not know yet must be held and retried, not dead-lettered: an unknown template
+during a rollout is a release-ordering state, not a permanent failure. Check
+that the outbox worker (MaggieDash Booking or the host's own) does not let
+unknown-template deliveries consume the retry budget, and after the release
+confirm the held deliveries were sent.
+If dead-lettered rows already exist, requeue them only after the worker that
+knows the template is live.
 
 Validate the database release separately before a VPS migration:
 

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

@@ -121,6 +121,29 @@ before staging migration and require a successful restore test before a
 production release. Keep the backup artifact and migration version in the
 handover record; never put a database URL or password in the manifest.
 
+### Running migrations as the database owner
+
+`sudo -u postgres psql -f /home/ubuntu/site/releases/<release>/db/073.sql`
+fails with `Permission denied` when the release lives under a deploy user's
+home: the `postgres` account cannot traverse that path. Do not widen
+filesystem permissions. Stream the file from a root-readable read into the
+owner-level `psql` instead (the generated plan's `commands.migrate_as_db_owner`):
+
+```bash
+sudo cat /home/ubuntu/site/releases/<release>/db/073.sql \
+  | sudo -u postgres psql -v ON_ERROR_STOP=1 --single-transaction -d <database> -f -
+```
+
+If a file path is required, copy it to a private temporary file readable only
+by the owner and remove it afterwards:
+
+```bash
+tmp=$(sudo -u postgres mktemp) && sudo cp <migration.sql> "$tmp" \
+  && sudo chown postgres: "$tmp" && sudo chmod 600 "$tmp" \
+  && sudo -u postgres psql -v ON_ERROR_STOP=1 -d <database> -f "$tmp"; \
+  sudo rm -f "$tmp"
+```
+
 ## Release workflow
 
 ```text
@@ -132,6 +155,56 @@ 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.
 
+### Release retention
+
+The retention policy is one explicit number, `--keep-releases N` (default 2),
+shared by the plan, the runner, `--retention-plan`, preflight, and rollback
+evidence. The default keeps the `current` release plus one previous release as
+the rollback target. `N = 1` is allowed for hosts that intentionally keep only
+the active release, but then no on-disk rollback exists: the plan reports
+`rollbackAvailable: false`, the runner says so after pruning, and rollback
+evidence must name a recovery plan (redeploy the previous commit, restore the
+data checkpoint) instead of a previous release.
+
+Prune after every deploy, and only after the new release passed its health
+checks: an unhealthy release must still have its predecessor on disk. The
+generated release runner does this as its final step; it never removes the
+release `current` points at, and with `N >= 2` it also keeps the release it
+replaced. Without pruning,
+`releases/` grows by one full `node_modules` tree per deploy until the disk
+fills. Use `--retention-plan` for a read-only list of prune candidates on hosts
+whose runner predates this step, and review it before deleting anything.
+
+### Multi-host secret parity
+
+When more than one host can serve the same routes (failover, load-balanced API
+nodes, workers), every host must hold the same required secrets. A key that
+exists on only one host is invisible until traffic fails over to another and
+returns 5xx. Compare hosts by name and SHA-256 fingerprint, never by value:
+
+```bash
+# On each host (prints names and digests only; values are never echoed):
+for k in SOCIAL_SHARE_ENCRYPTION_KEY DATABASE_URL; do
+  v=$(sed -n "s/^$k=//p" /etc/example.env | head -1)
+  printf '%s %s\n' "$k" "$(printf %s "$v" | sha256sum | cut -c1-64)"
+done > /tmp/api-1.fingerprints
+
+# Locally, after copying each host's fingerprint file:
+maggie deployment secret-parity \
+  --manifest api-1.fingerprints --manifest api-2.fingerprints \
+  --manifest api-3.fingerprints \
+  --required SOCIAL_SHARE_ENCRYPTION_KEY --required DATABASE_URL
+```
+
+Run it after adding a secret and before enabling a host in a pool.
+
+### Environment isolation
+
+A local `.env` must never point at the production database. Shared databases
+let local test records (vouchers, palettes, emails) appear on live pages and be
+picked up by production workers. `maggie deployment env-isolation` fails when
+the local database host, port, and name match production.
+
 ## Verification and rollback
 
 Verify the homepage, changed service routes, `/robots.txt`, `/sitemap.xml`,
@@ -139,7 +212,7 @@ canonical URLs, booking links, and protected Ops/API routes. Check both apex
 and `www` when configured. Record HTTP status, commit, and release.
 
 Rollback switches `current` to the previous immutable release and restarts the
-service. If migrations are not backward-compatible, stop before deployment and
+service, when the retention policy keeps one. If migrations are not backward-compatible, stop before deployment and
 provide a tested restore or database rollback plan. The first production
 release may declare rollback as not applicable only with `releaseKind: "first"`,
 a non-empty `notApplicableReason`, and `RELEASE_KIND=first`; upgrades still

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

@@ -84,6 +84,61 @@ a successful `assetStatus` (2xx), and a non-empty accessible name. This
 gate is independent from typecheck/build and is read-only apart from its
 explicit output.
 
+### Rendered glyph proof
+
+Collect that browser evidence with the shared collector instead of a
+hand-written report. It renders each route at mobile, tablet, and desktop in
+headless Chrome — through a local GET-only proxy for a running host
+(`--base-url`) or directly from a static build (`--dist`) — and records, per
+representative icon, whether its icon font reached `document.fonts` status
+`loaded`, whether the glyph paints ink that differs from the browser fallback
+font (a missing glyph falls back or paints blank), whether runtime CSS hides
+it (`display`, `visibility`, `opacity`, zero size, or a hidden pseudo-element),
+its font family, accessible name, and the served font asset status:
+
+```bash
+maggie design icon-glyph-check --base-url http://localhost:4321 \
+  --route / --route /contact --family ph=Phosphor \
+  --output .maggie/icon-browser-evidence.json
+```
+
+`--family PREFIX=FAMILY` asserts the expected visual family for a class
+prefix. Evidence from this collector makes `icon-release-gate` also require
+`fontLoaded`, `glyphPainted`, matching family, and an icon at every declared
+viewport; hand-written evidence still passes the original checks but the gate
+reports `glyphIdentityProven: false` with a warning. The collector forwards GET
+requests only and never stores page text beyond icon names and labels.
+
+## Design job verification
+
+`design step` records evidence one step at a time. `design verify` runs every
+step that can be proven automatically against a host adapter and records it
+with durable evidence under `.maggie/design-evidence/<job>/`:
+
+```bash
+# section-scoped job: snapshot before editing, then verify after
+maggie design verify section-<id> --project . --base-url http://localhost:4321 --stage before
+maggie design verify section-<id> --project . --base-url http://localhost:4321
+
+# in-place or author job against a static build, including the host build
+maggie design verify in-place-<id> --project . --dist dist --build-command "npm run build"
+```
+
+Automated steps: `inspect-route`/`inspect-shell`/`inspect-section` (2xx HTML,
+shell landmarks, target section present), `declare-content-source` (no
+unproven catch-all resolution), `capture-before`/`capture-after` (per-section
+structure hashes from `<section id>` or `data-section-id`),
+`assert-unchanged-rest`, `capture-responsive-screenshots` (390/768/1440 PNGs
+with hashes), `accessibility-check` (lang, one h1, alt text, named controls,
+labelled fields, `<main>`), `route-validation` (2xx, title, h1, no template
+placeholders, no accidental `noindex`), and `build-check` only with an explicit
+`--build-command`. A failed check leaves its step pending with `lastCheck`
+evidence. `apply-design-contract`, `implement-*`, `visual-review`, and
+`approval` are never completed by `verify`; record them with `design step` and
+real implementer or reviewer evidence, so a job cannot reach `done` without
+evidence. Client-rendered sections need host-adapter evidence through
+`design step` when the server HTML does not contain them.
+
 ## Hero video playback contract
 
 Hero video is an enhancement, not the only way to see the first-band message.
@@ -285,6 +340,57 @@ all required camera states, and valid PNGs at 390px, 768px, and desktop
 widths. The machine-readable contract is
 [mobile-app-surface-v1.schema.json](../../bundled-contracts/maggie-design/mobile-app-surface-v1.schema.json).
 
+### Onboarding wizards
+
+Use one pattern for multi-step setup (brand, logo, voice, posting hours, and
+similar first-run flows) instead of designing each flow ad hoc:
+
+- A segmented progress bar with one segment per step; the current step is
+  visibly distinct and completed steps are tappable.
+- Each step shows Maggie (or the product guide) with exactly one headline and,
+  at most, one supporting line. Put help in the control, not in paragraphs.
+- Record step state on the server (`pending`, `done`, `skipped`) after every
+  step, and resume from the first unfinished step on any device. Local state
+  alone loses progress on reinstall or a second device.
+- Every optional step offers **Later**. A skipped step reopens on the next
+  sign-in until it is done or explicitly dismissed; never block the app on it.
+- Completed steps keep a redo action (for example "Retrain voice" or
+  "Choose another logo") that reopens that step with the saved value
+  preselected, without restarting the wizard.
+- The primary action stays in the fixed footer; Back never discards saved
+  server state.
+
+### Pickers with previews
+
+For choices that need to be seen (logo styles, templates, palettes, voices):
+
+- The list sheet shows a thumbnail, name, and selection state per row; the
+  row itself selects, and a separate preview control opens a larger view.
+- The large preview opens as a sheet nested in the list sheet, so dismissing
+  it returns to the same scroll position in the list. It offers **Use this**
+  and close; it never replaces the list route.
+- Thumbnails are generated or cached assets, not live renders of every option.
+
+### React Native Web pressables
+
+React Native Web renders `Pressable` and the `Touchable*` family as button-like
+DOM elements. A chip with a nested remove control becomes `<button>` inside
+`<button>`: the DOM is invalid, browsers repair it differently, and taps land
+on the wrong control (for example, removing a tag opens its preview). Render
+the chip body and its remove control as **sibling** pressables inside a plain
+`View`, each with its own accessible label. The same rule applies to `<a>`
+and `<button>` on the web.
+
+Run the static check before browser QA; it scans `.tsx`/`.jsx`, skips build
+and dependency folders, and treats `asChild` wrappers (such as an expo-router
+`Link`) as a pass-through:
+
+    maggie design pressable-check --project . [--pressable Chip --pressable IconButton]
+
+Pass `--pressable` for project components that render a pressable. A rare,
+reviewed exception can carry `maggie-allow-nested-pressable` in a comment on
+the inner element's line.
+
 ## Explicit homepage rebrand mode
 
 The homepage `review` mode only compares screenshots. It does not rebrand a
@@ -543,6 +649,54 @@ collapsed-rail, mobile-drawer, and modal evidence. Sample plans require
 noindex, sitemap exclusion, a visible sample banner, placeholders, and a
 finish checklist.
 
+### Tailwind v4 cascade layers
+
+Tailwind v4 emits utilities inside `@layer utilities`. An unlayered rule beats
+every layered rule regardless of specificity, so an unlayered
+`h1, h2, h3 { font-family: … }` silently defeats template `font-*` utilities,
+and an unlayered icon runtime rule such as `.ph { display: inline-block }`
+defeats `hidden` and `group-open:inline` (a mobile menu then shows both the
+open and close icons). Static class checks pass; only a browser shows it.
+
+- Put app-wide element rules (headings, links, body copy) in `@layer base`.
+- Put icon-font runtime rules and component classes in `@layer components`,
+  or import the icon stylesheet with `@import "./icons.css" layer(components);`.
+- Keep `@theme`, `@utility`, and `@font-face` as they are; they are not
+  competing rules.
+
+Run the static check whenever CSS or the icon package changes:
+
+    maggie design layer-check --project .
+
+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.
+
+### Palette role contract
+
+A template that offers brand colour choices exposes semantic roles instead of
+raw hex values in markup: `canvas`, `panel`, `soft`, `text`, `accent`,
+`accentText`, `onAccent`, `dark`, and `deep`. Bind them to CSS variables (for
+example `--color-canvas`) so a palette swap never edits markup. The generator
+keeps the signature palette and derives named variants by moving hue while
+keeping lightness; neutrals never gain chroma, accent saturation is capped
+(uncapped variants turn garish), `accentText` is forced to 4.5:1 on canvas,
+and `onAccent` is the most legible of white, deep, text, and canvas:
+
+    maggie design palette generate --template <template-id> \
+      --canvas '#F7F3EE' --text '#1F1B16' --accent '#B5651D' \
+      [--roles roles.json] [--count 17] [--max-saturation 0.65] \
+      --output design/palettes.json
+    maggie design palette validate --palette design/palettes.json
+
+Measure the signature roles from the template's rendered CSS, not from a
+reference palette. Generation stops if the signature itself fails the
+contrast rules; fix the signature rather than lowering the threshold. The
+contract is
+[palette-roles-v1.schema.json](../../bundled-contracts/maggie-design/palette-roles-v1.schema.json).
+
 For generated or converted pages, run the markup gate before handing the page
 to a host editor: