wize-dev-kit 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,81 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-06-11
+
+First release that delivers the lifecycle end-to-end. Workflows have real bodies; CLI commands work for real; the team has a Walkthrough to follow.
+
+### Added — CLI
+
+- **`wize-dev-kit update`** — refreshes an installed kit to the version resolved by `node_modules/wize-dev-kit`. Re-runs every active IDE adapter, preserves `.wize/config/user.toml`, re-applies the suggested `.gitignore` block, and writes the new `kit_version` into `.wize/config/project.toml`. Prints the relevant CHANGELOG excerpt between the previous and current version.
+- **`wize-dev-kit sync`** — re-renders adapter outputs for whatever `ide_targets` the project opted into. Cheap idempotent call after editing config or running `agent create`.
+- **`wize-dev-kit agent list`** — lists every built-in agent (9) plus any custom or override agents the project added.
+- **`wize-dev-kit agent create`** — interactive scaffold of a new custom agent. Validates `code` shape, checks for collisions with built-ins, does a dry-run write+read, then persists to `.wize/custom/agents/{code}/{agent.yaml, persona.md}`. Non-TTY callers can pass a spec via API (`fromSpec`).
+- **`wize-dev-kit agent edit <code>`** — writes a `customize.toml` override for an existing built-in agent into `.wize/custom/agents/{code}/`.
+
+### Added — UX
+
+- **End-of-install message** now ends with: "Restart your IDE — many harnesses load skills only at startup." plus a quick-reference to the new CLI commands (`update`, `sync`, `agent list`).
+- **README walkthrough** — a complete end-to-end slash-command map from `/wize-orchestrator` through `/wize-tea-gate`, plus a new "CLI commands" reference section.
+
+### Changed — workflows now have real bodies
+
+22 workflows that were ≈ 30–50-line stubs in 0.1.x now ship 100–250 lines of working method, examples, anti-patterns, and YAML schemas. Tone aligned with the 0.1.5 playbooks (dense, opinionated, citable).
+
+- **Analysis (Pepper):** `wize-product-brief`, `wize-trigger-map`, `wize-research`, `wize-prfaq`, `wize-document-project`.
+- **Plan (Maria Hill + Mantis):** `wize-create-prd`, `wize-validate-prd`, `wize-ux-scenarios`, `wize-ux-design`.
+- **Strategy + Solutioning (Fury + Tony + Mantis):** `wize-tech-vision`, `wize-nfr-principles`, `wize-create-architecture`, `wize-design-system`, `wize-create-epics-and-stories`, `wize-check-implementation-readiness`.
+- **TEA gates (Hawkeye):** `wize-tea-risk`, `wize-tea-design`, `wize-tea-trace`, `wize-tea-nfr`, `wize-tea-review`, `wize-tea-gate` — each with canonical YAML frontmatter + concrete examples.
+- **Implementation (Shuri + Hill + Wizer):** `wize-create-story`, `wize-dev-story`, `wize-quick-dev`, `wize-sprint-planning`, `wize-sprint-status`, `wize-retrospective`, `wize-code-review`.
+
+### Added — engineering
+
+- `tools/installer/commands/{update,sync,agent}.js` — modular command implementations with a minimal TOML reader for the `project.toml` subset.
+- `test/cli-commands.test.js` — coverage for update / sync / agent list / agent create / agent edit (10 tests).
+- `test/workflow-bodies.test.js` — guards that every workflow.md has ≥ 1.5 KB body and ≥ 4 H2 sections, with an explicit allow-list for intentionally short workflows (overlay scaffolds, builder helpers, orchestrator helpers).
+- Test count: **87 passing** (was 33).
+
+### Notes
+
+This release closes JTBD backlog categories 3 (CLI commands real) and 2 (workflows with body) plus 4 (end-of-install UX, README walkthrough). Categories 5 (CI hygiene incl. smoke E2E) and 6 (monorepo routing, TEA enforcing helper) remain on the roadmap.
+
+## [0.1.5] — 2026-06-01
+
+### Added — promises kept
+
+All files that previous releases declared in `module.yaml` but never shipped are now in the kit, with real content (not placeholders).
+
+**Web overlay playbooks** (`src/web-overlay/playbooks/`):
+
+- `wcag-aa.md` — WCAG 2.2 AA checklist for Mantis, with the newer SCs (2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7, 3.3.8) and an audit toolchain.
+- `responsive-breakpoints.md` — mobile-first stack with container queries, fluid typography (`clamp`), layout primitives (Stack/Cluster/Switcher/Sidebar/Grid/Cover/Frame), image strategy.
+- `semantic-html.md` — landmarks, headings, the 12 must-reach-first elements, ARIA rules, common widget patterns with minimum ARIA, anti-patterns.
+- `playwright-vitest.md` — Hawkeye's split (70/20/10), Vitest + Testing Library + MSW setup, Playwright POM pattern, selector hierarchy (role → label → text → testid), CI sketch, anti-patterns.
+- `web-perf-budgets.md` — Core Web Vitals targets, baseline budgets per resource class, image/font strategy, third-party audit checklist, critical rendering path snippet, lighthouse-ci config, field measurement via `web-vitals` beacon.
+
+**App overlay playbooks** (`src/app-overlay/playbooks/`):
+
+- `apple-hig.md` — POUR-equivalent four principles, layout (status bar/nav/tab/safe-area), navigation patterns, SF Symbols, Dynamic Type, motion, common idioms, iPad specifics, do-not list.
+- `material-design-3.md` — pillars, color/type/shape tokens, elevation-by-color, component starter set, adaptive windows (Compact/Medium/Expanded/Large), motion + reduced motion, Material You theming.
+- `touch-targets-and-gestures.md` — minimums per platform (iOS 44pt / Android 48dp / web 24px), hit-area snippets per stack, thumb reach zones, reserved gestures, multi-touch, drag-and-drop with keyboard fallback, haptics, reduce-motion.
+- `permissions-ux.md` — the four states (not-determined/granted/denied/limited), pre-flight pattern, per-permission guidance (camera/photos/location/notifications/contacts/BLE/health/tracking), denied-state UI + Settings deep-link, copy template.
+- `detox-maestro.md` — when to pick each, Maestro YAML + cloud, Detox config + `testID` discipline, cross-platform CI sketch, flakiness rules, critical journeys to cover.
+- `mobile-perf-budgets.md` — cold/warm start, TTI, FPS, jank, app size, memory, battery; per-platform targets; size reductions that work; build-time + field measurement.
+- `device-matrix.md` — three buckets (floor/volume/ceiling), 2026 iOS + Android matrices, cloud farm comparison, accessibility runs, network conditions, locale coverage.
+
+**Stack catalogs**:
+
+- `src/web-overlay/stack-catalog.md` — Tony's reference for the web architecture interview: frameworks (Next/Nuxt/SvelteKit/Astro/Remix/SPA/Laravel-Inertia), back-end (Supabase/PlanetScale/Drizzle/Prisma/tRPC/GraphQL), auth, hosting, styling, state, forms; ADR record path.
+- `src/app-overlay/stack-catalog.md` — Tony's mobile architecture reference: frameworks (RN+Expo / RN bare / Flutter / SwiftUI / Compose / Compose-Multiplatform / Capacitor / native+KMP), build & release, auth, data/sync, state, storage, push, analytics, anti-patterns; ADR record path.
+
+### Added — tests
+
+- `test/playbooks-and-catalogs.test.js`: guards that every playbook declared in an overlay `module.yaml` exists on disk, has frontmatter, and is non-trivial (> 400 chars). Stack catalog presence + size also asserted. Total tests now: **39** (was 33).
+
+### Notes
+
+This release closes Category 1 of the backlog ("promessas vazias"). Categories 2–6 (workflow bodies, `update`/`sync`/`agent create` CLI, polish, Node-24 CI, OIDC return, monorepo & TEA-enforcing) remain on the roadmap.
+
 ## [0.1.4] — 2026-06-01
 
 ### Added
@@ -102,7 +177,9 @@ Ignore (handled by the suggested block): `.wize/config/user.toml`, `.wize/scratc
 - Inspired by [BMAD Method v6.8.0](https://github.com/bmad-code-org/BMAD-METHOD).
 - WDS module inspired by [bmad-method-wds-expansion](https://github.com/bmad-code-org/bmad-method-wds-expansion).
 
-[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/qwize-br/wize-development-kit/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/qwize-br/wize-development-kit/compare/v0.1.1...v0.1.2

package/README.md

@@ -72,6 +72,55 @@ See [`ROSTER.md`](ROSTER.md) for personas, styles and BMAD equivalences.
 
 ---
 
+## Walkthrough — a full project, end to end
+
+Below is the canonical flow Wizer drives in a real session. Each step is a slash command in your IDE; each persona reads the previous artifact before writing its own. Nothing is mocked.
+
+```
+1.  /wize-orchestrator          Wizer greets, reads .wize/config/{project,user}.toml.
+                                Detects the project state and routes you.
+
+2.  /wize-product-brief         Pepper turns raw demand into brief.md.
+    /wize-trigger-map           Pepper maps user psychology → business goals (WDS).
+    /wize-research              Pepper synthesizes external evidence (optional).
+
+3.  /wize-create-prd            Maria Hill writes prd.md (goals, scope, ACs).
+    /wize-validate-prd          Maria Hill (+ Mantis/Fury) signs off.
+
+4.  /wize-ux-scenarios          Mantis runs the 8-question WDS dialog.
+    /wize-ux-design             Mantis writes page specs (one .md per screen).
+
+5.  /wize-tech-vision           Fury picks the stack family + non-negotiables.
+    /wize-nfr-principles        Fury writes the NFR budget (perf, sec, a11y…).
+
+6.  /wize-create-architecture   Tony writes architecture.md + ADRs.
+    /wize-design-system         Mantis writes design-system/ (tokens + components).
+    /wize-create-epics-and-stories
+                                Tony slices epics → stories (each has ACs).
+
+7.  /wize-tea-risk              Hawkeye builds the global risk profile.
+    /wize-tea-design            Hawkeye writes test design for the next story.
+    /wize-dev-story             Shuri implements (TDD, AC IDs in commits).
+    /wize-tea-trace             Hawkeye maps each AC → tests.
+    /wize-tea-review            Hawkeye runs story review.
+    /wize-tea-gate              Hawkeye emits PASS / CONCERNS / FAIL / WAIVED.
+
+8.  /wize-sprint-status         Maria Hill keeps the daily snapshot updated.
+    /wize-retrospective         Wizer facilitates retro at end of each sprint.
+    /wize-tea-nfr               Hawkeye assesses NFRs at epic boundary.
+
+Cross-cutting:
+    /wize-help                  Wizer figures out where you are and proposes
+                                the next step (use anytime).
+    /wize-quick-dev             Shuri takes a small fix without the full ride.
+    /wize-party-mode            Wizer convenes multi-persona for hard calls.
+```
+
+> Use `/wize-help next` whenever you're unsure — it inspects `.wize/` and tells
+> you the single next action.
+
+---
+
 ## Output layout (in the target repo)
 
 ```
@@ -86,6 +135,21 @@ See [`ROSTER.md`](ROSTER.md) for personas, styles and BMAD equivalences.
 
 ---
 
+## CLI commands
+
+```bash
+npx wize-dev-kit install         # interactive setup
+npx wize-dev-kit update          # bring an installed kit up to the current package version
+npx wize-dev-kit sync            # re-render IDE adapters after editing config
+npx wize-dev-kit agent list      # list built-in + custom agents
+npx wize-dev-kit agent create    # scaffold a new custom agent (validated + dry-run)
+npx wize-dev-kit agent edit <code>  # override a built-in via .wize/custom/agents/<code>/customize.toml
+npx wize-dev-kit validate        # structural checks on the kit assets
+npx wize-dev-kit uninstall       # remove .wize/ (your code is left untouched)
+```
+
+---
+
 ## Documentation
 
 - [`ARCH.md`](ARCH.md) — full architecture: distribution, fluxos, layout, installer.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

package/src/app-overlay/playbooks/apple-hig.md

@@ -0,0 +1,112 @@
+---
+playbook: apple-hig
+owner: wize-agent-ux-designer   # Mantis
+applies_when: app-overlay active (iOS / iPadOS / macOS)
+status: ready
+---
+
+# Apple HIG — Mantis Playbook (iOS / iPadOS)
+
+The HIG isn't a rulebook to memorize — it's a vocabulary. Design so the app feels native first, branded second.
+
+## 1. The four design principles to lead with
+
+1. **Hierarchy** — one primary action per screen. Demote everything else.
+2. **Harmony** — visual language aligned with the system: SF Symbols, system colors, dynamic type.
+3. **Consistency** — same gesture, same outcome, across the app.
+4. **Deference** — content over chrome; let the OS chrome breathe.
+
+## 2. Layout fundamentals
+
+| Region | Rule |
+|---|---|
+| Status bar | Never overlap critical content. Match content scheme (light/dark). |
+| Navigation bar | Use the system component. Title sits in `Large Title` on top, collapses on scroll. |
+| Tab bar | 3–5 tabs. Each is a top-level destination, not a flow step. |
+| Safe area | Always respect; never paint behind home indicator unless intentional. |
+| Touch targets | **44×44 pt minimum** (HIG SC). Spacing ≥ 8 pt between adjacent targets. |
+
+## 3. Navigation patterns
+
+| Pattern | Use when |
+|---|---|
+| **Tab bar** | 3–5 distinct content areas (Home/Search/Library/Profile). |
+| **Navigation stack** | Hierarchical drill-down. Back gesture must work. |
+| **Modal sheet** | Self-contained task (compose, settings detail). Dismissible with swipe-down. |
+| **Full-screen modal** | Multi-step task that needs focus (onboarding, payment flow). |
+| **Page sheet** (iPad) | Inspector-like UI alongside content. |
+| **Popover** (iPad/Mac) | Contextual options anchored to a control. |
+
+## 4. SF Symbols (use them)
+
+- 6000+ glyphs with weights, hierarchical variants, and palette modes.
+- Match symbol weight to your text weight.
+- Use multicolor sparingly — only when meaning depends on color.
+- Never embed glyphs as PNG; SwiftUI/UIKit handle scaling.
+
+```swift
+Image(systemName: "heart.fill")
+  .font(.system(size: 24, weight: .semibold))
+  .foregroundStyle(.tint)
+```
+
+## 5. Typography — Dynamic Type
+
+- Use semantic text styles (`.title`, `.headline`, `.body`, `.callout`, `.footnote`). Never hardcode `font-size`.
+- Support all 7 default text sizes and the 5 accessibility sizes (xxxL → A11Y_XXXL).
+- Test at the largest accessibility size: critical UI must reflow, not clip.
+
+## 6. Color
+
+- Start from **system colors** (`.label`, `.systemBackground`, `.systemBlue`). They handle light/dark/contrast.
+- Brand color stays as a single accent (`tintColor`). Don't recolor system controls.
+- Run in dark mode + Increase Contrast + Reduce Transparency at least once per epic.
+
+## 7. Motion
+
+- Respect `Reduce Motion`. Replace `slide`/`scale` with `cross-fade`.
+- Standard durations: 0.25s (transient), 0.35s (navigation), 0.4s (modal present).
+- Springs over linear curves; physics > eased linear.
+
+## 8. Common idioms
+
+| Idiom | When |
+|---|---|
+| **Pull-to-refresh** | Lists where freshness matters (mail, feed). |
+| **Swipe actions** | Quick row actions (archive, delete). Always pair with a tap-reveal alternative. |
+| **Context menu (long press)** | Secondary actions on a tile. Never the only path. |
+| **Action sheet** | 2–6 mutually exclusive choices on a small screen. |
+| **Confirmation dialog** | Destructive actions — always confirm; phrase the verb on the button. |
+
+## 9. Permissions
+
+- Ask in context, not at launch. (See `permissions-ux.md`.)
+- Provide a pre-flight UI explaining the *why* before the system prompt.
+
+## 10. Privacy nutrition + tracking
+
+- `App Tracking Transparency` prompt is mandatory if you track across other apps/sites.
+- Privacy nutrition label is required on the App Store.
+- Mantis writes the user-facing explanations; Tony coordinates the technical entries.
+
+## 11. iPad specifics
+
+- **Sidebar + content split** when content is hierarchical and lateral nav matters.
+- Support Stage Manager + multitasking (responsive layout, no fixed pixel widths).
+- Apple Pencil hover (iPad Pro) — design hover affordances even for touch-only apps.
+
+## 12. Don'ts
+
+- Custom back arrows. Use the platform's.
+- Hidden gestures as the only path to a feature. Provide a visible tap.
+- Splash screen with branding for > 1 second. Use the launch screen, not a "loading" splash.
+- Reinventing the share sheet. Use `UIActivityViewController` / `ShareLink`.
+- Toast notifications. iOS doesn't have them; use sheets, banners, or system notifications.
+
+## 13. Cross-platform note
+
+If the project also ships Android, **build to platform**, not lowest common denominator. Each idiom (back button vs back gesture, tab bar vs bottom nav, alert vs dialog) belongs to its OS. See `material-design-3.md`.
+
+## 14. Hand-off
+
+Mantis annotates each screen spec with the Apple system component name (`UIKit` or `SwiftUI`), Dynamic Type style, system color tokens. Tony picks UIKit vs SwiftUI vs React Native; Shuri implements against the named components.

package/src/app-overlay/playbooks/detox-maestro.md

@@ -0,0 +1,179 @@
+---
+playbook: detox-maestro
+owner: wize-agent-test-architect   # Hawkeye
+applies_when: app-overlay active
+status: ready
+---
+
+# Mobile E2E — Detox + Maestro Playbook
+
+Two tools, different angles. **Detox** integrates deep into RN/Expo with a real JS bridge and runs on real devices/simulators. **Maestro** is YAML-declarative, multi-platform (RN, Flutter, native), and exceptional for smoke + visual flows. Most teams want one of each, not both heavy.
+
+## 1. Pick one (or both, lean)
+
+| Need | Pick |
+|---|---|
+| RN / Expo only, deep state introspection, fastest iteration | **Detox** |
+| Native, Flutter, RN — mixed shop | **Maestro** |
+| Smoke flow you run on every PR | **Maestro** |
+| Detailed assertions on bridge state, mocks at JS layer | **Detox** |
+| Cross-platform visual regression | **Maestro** snapshots (Cloud) |
+| Tight CI matrix (iOS sim + Android emulator + cloud devices) | **Maestro Cloud** or **MagicPod / BrowserStack** |
+
+Default split (Hawkeye `tea-design.md`):
+
+- **Vitest / Jest** for unit + component (≥ 70%).
+- **Maestro** for smoke (3–8 critical flows on every PR).
+- **Detox** for RN-specific deep flows (auth, deep links, push handling).
+
+## 2. Maestro — getting started
+
+```yaml
+# .maestro/flows/sign-in.yml
+appId: com.qwize.app
+---
+- launchApp
+- assertVisible: "Sign in"
+- tapOn:
+    text: "Email"
+- inputText: "qa@qwize.io"
+- tapOn:
+    text: "Password"
+- inputText: "test1234"
+- tapOn: "Sign in"
+- assertVisible:
+    id: "home-tab"
+    timeout: 10000
+```
+
+Run locally:
+
+```bash
+maestro test .maestro/flows/sign-in.yml
+maestro studio                         # record flows visually
+maestro cloud .maestro/                # run on Maestro Cloud
+```
+
+Tips:
+
+- One flow per file. Compose with `runFlow` for shared steps (sign-in fixture).
+- Prefer `id`-based selectors over text — text changes with locale.
+- Wrap network-dependent waits in `extendedWaitUntil` so they fail loud, not flaky.
+- Snapshots: `takeScreenshot` then commit baseline; Maestro Cloud handles diffing.
+
+## 3. Detox — getting started (RN / Expo)
+
+```bash
+npx detox init -L jest
+```
+
+```jsonc
+// .detoxrc.js (sketch)
+module.exports = {
+  testRunner: 'jest',
+  apps: {
+    'ios.debug':     { type: 'ios.app', binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/App.app', build: 'xcodebuild ...' },
+    'android.debug': { type: 'android.apk', binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk', build: 'cd android && ./gradlew assembleDebug assembleAndroidTest' }
+  },
+  devices: {
+    'ios.sim':  { type: 'ios.simulator', device: { type: 'iPhone 15 Pro' } },
+    'android.emu': { type: 'android.emulator', device: { avdName: 'Pixel_7_API_34' } }
+  },
+  configurations: {
+    'ios.debug':     { device: 'ios.sim',  app: 'ios.debug' },
+    'android.debug': { device: 'android.emu', app: 'android.debug' }
+  }
+};
+```
+
+```ts
+// e2e/sign-in.test.ts
+describe('Sign in', () => {
+  beforeAll(async () => { await device.launchApp(); });
+  beforeEach(async () => { await device.reloadReactNative(); });
+
+  it('lets a known user in', async () => {
+    await element(by.id('email')).typeText('qa@qwize.io');
+    await element(by.id('password')).typeText('test1234');
+    await element(by.id('signin-cta')).tap();
+    await expect(element(by.id('home-tab'))).toBeVisible();
+  });
+});
+```
+
+Hawkeye rules for Detox:
+
+- Always use `testID`. Never text selectors.
+- Reset state between tests (`device.reloadReactNative()`); never share login state silently.
+- Network: prefer **MSW-RN** or in-app mock layer. Don't hit prod.
+- Set `Detox.setReachability` to simulate offline scenarios.
+
+## 4. Cross-platform CI sketch
+
+```yaml
+# .github/workflows/mobile-e2e.yml (sketch)
+jobs:
+  maestro-ios:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - run: brew tap mobile-dev-inc/tap && brew install maestro
+      - run: yarn install --frozen-lockfile
+      - run: yarn build:ios
+      - run: maestro test .maestro/flows/
+  maestro-android:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 34
+          target: google_apis
+          arch: x86_64
+          profile: pixel_7
+          script: |
+            curl -Ls "https://get.maestro.mobile.dev" | bash
+            maestro test .maestro/flows/
+  detox-ios:
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v4
+      - run: yarn install --frozen-lockfile
+      - run: brew tap wix/brew && brew install applesimutils
+      - run: yarn detox build -c ios.debug && yarn detox test -c ios.debug --headless
+```
+
+## 5. Flakiness — non-negotiable rules
+
+1. **No `sleep(N)`.** Use built-in waits (`waitFor`, `extendedWaitUntil`).
+2. Tests must pass 50× in a row in CI before they're trusted.
+3. Reset app state between tests; don't share login.
+4. Don't depend on network for unit/component layer — mock at the boundary.
+5. If a test is flaky once, fix or quarantine it the same day. Don't `retries: 5`.
+
+## 6. Critical journeys to cover (always)
+
+Even MVPs should ship E2E for:
+
+- First-run onboarding through to the home tab.
+- Sign-up + sign-in + sign-out.
+- Primary "value moment" action (the one PRD success criterion exists for).
+- Push notification deep link.
+- Network-failure UX (offline mode, retry).
+
+Everything else is nice-to-have until the team has signal that the critical flows are stable.
+
+## 7. Device matrix
+
+See `device-matrix.md`. Maestro Cloud and BrowserStack expose matrices Hawkeye can declare in YAML and run weekly.
+
+## 8. Don'ts
+
+- E2E tests in the same job as unit tests (slow, blocks faster signal).
+- Selectors by visible text in a multilingual app.
+- Running E2E only at release; broken paths get found at the worst time.
+- "Manual smoke" replacing automated smoke. Maestro flows take a day to write and save weeks per year.
+
+## 9. Hand-off
+
+Tony picks RN / native / Flutter; that decides the Detox feasibility. Hawkeye writes the Maestro flow files alongside the story `tea-design.md`. Shuri owns the `testID`s and accessibility identifiers and treats them as a public API of the app — renaming one is a contract change.

package/src/app-overlay/playbooks/device-matrix.md

@@ -0,0 +1,121 @@
+---
+playbook: device-matrix
+owner: wize-agent-test-architect   # Hawkeye
+applies_when: app-overlay active
+status: ready
+---
+
+# Device Matrix — Hawkeye Playbook
+
+You can't test on every device. You can test on the right ones. Decide the matrix once per release; rotate quarterly.
+
+## 1. The three buckets
+
+Every release ships on three device classes:
+
+| Bucket | Why |
+|---|---|
+| **Floor** (oldest supported / lowest-spec) | Performance & memory pressure catches regressions invisible on flagship. |
+| **Volume** (most-used by your audience) | Where users actually live. Drive default UX decisions here. |
+| **Ceiling** (latest flagship + newest OS) | New-feature opportunity (Live Activities, Predictive Back, etc.) + verify no flagship-only assumption breaks. |
+
+## 2. iOS matrix (2026, generic SaaS audience)
+
+| Bucket | Device | iOS | Notes |
+|---|---|---|---|
+| Floor | iPhone SE (2nd gen, A13) | iOS 17 | 4.7" non-Retina XDR, no Dynamic Island. |
+| Floor | iPhone 11 | iOS 17 | Wide audience tail. |
+| Volume | iPhone 14 | iOS 18 | Mid-range volume sweet spot. |
+| Volume | iPhone 15 | iOS 18 | Dynamic Island, USB-C. |
+| Ceiling | iPhone 17 Pro | iOS 26 (current dev) | ProMotion, latest APIs. |
+| iPad floor | iPad (10th gen) | iPadOS 17 | Non-ProMotion. |
+| iPad ceiling | iPad Pro M4 | iPadOS 18 | Stage Manager, hover, Pencil hover. |
+
+**Min OS:** iOS 17 (cuts ~5% of installed base; recovers a lot of API surface). Adjust per audience.
+
+## 3. Android matrix (2026, generic SaaS audience)
+
+| Bucket | Device | OS | Notes |
+|---|---|---|---|
+| Floor | Pixel 6a or Samsung A14 | Android 13 | 4 GB RAM, Snapdragon 6-series. |
+| Volume | Samsung Galaxy A55 | Android 14 | Mid-range. Big volume in emerging markets. |
+| Volume | Pixel 8 | Android 14 / 15 | Reference device for API behavior. |
+| Ceiling | Pixel 9 Pro / Galaxy S25 Ultra | Android 15 | Foldable / large-screen, edge gestures. |
+| Foldable | Samsung Galaxy Z Fold 6 | Android 14 / 15 | Adaptive layout signal. |
+| Tablet | Pixel Tablet | Android 14 | Window-size-class testing. |
+
+**Min OS:** Android 13 (API 33) — covers ~85% of active devices. Verify via Play Console statistics for your audience.
+
+## 4. Hybrid / web-in-app matrix
+
+If the app uses webviews (Capacitor, Ionic, embedded web docs):
+
+- iOS: WKWebView (always system Safari engine).
+- Android: System WebView (Chromium-based, updated separately). Test on **last 3 Chromium versions**.
+
+## 5. Choosing the volume tier
+
+Don't guess. Pull from:
+
+- **App Store Connect → Analytics → Sources → Devices** (after release).
+- **Google Play Console → Statistics → Devices**.
+- For pre-release: pick the top 3 devices in your target market via StatCounter / DeviceAtlas / Crashlytics-baseline market data.
+
+Rotate volume devices every two quarters as field data shifts.
+
+## 6. How to run the matrix in CI
+
+### Cloud farms
+
+| Provider | iOS | Android | Notes |
+|---|---|---|---|
+| BrowserStack App Live / Automate | ✓ | ✓ | Largest catalog; integrates Detox + Maestro. |
+| Sauce Labs Mobile | ✓ | ✓ | Strong on Appium; price ladder. |
+| Maestro Cloud | ✓ | ✓ | YAML-native; visual diff included. |
+| Firebase Test Lab | (limited) | ✓ | Android-first; cheap, large. |
+| AWS Device Farm | ✓ | ✓ | Real devices; AWS billing. |
+| LambdaTest | ✓ | ✓ | Mid-tier price. |
+
+### Local
+
+- iOS: Xcode simulators for development; **at least one real device per bucket** before release.
+- Android: emulators (`avdmanager` + `system-images;android-34;google_apis;x86_64`); real device per bucket.
+
+### What runs where
+
+- **Every PR:** smoke flow (Maestro) on emulator iOS + Android (volume bucket).
+- **Every merge to main:** full smoke matrix (floor + volume + ceiling).
+- **Nightly:** full E2E suite (Detox + Maestro) on real devices via cloud farm.
+- **Weekly:** perf benchmark suite (cold start, memory, FPS) on the floor + volume buckets.
+
+## 7. Accessibility runs
+
+Add to the device matrix:
+
+- iOS: VoiceOver + Dynamic Type at largest accessibility size.
+- Android: TalkBack + 130% font scale.
+- Color contrast checks at the OS level (Smart Invert / Dark Mode forced).
+- Switch Control (iOS) / Switch Access (Android) on the most-used flow.
+
+## 8. Network conditions
+
+Hawkeye samples network at:
+
+| Condition | Tool |
+|---|---|
+| Offline | Airplane mode flag in CI. |
+| 3G slow | Charles / Proxyman / Maestro `setProxy` + bandwidth throttle. |
+| Lossy WiFi | `tc qdisc` on Linux runner; Network Link Conditioner on Mac. |
+| Captive portal | Manual on weekly cycle. |
+
+A surprising % of production crashes come from network edge cases. Cover at least offline + slow.
+
+## 9. Locale
+
+- Always test **English + the two largest non-English locales** for the audience.
+- RTL (Arabic or Hebrew) at least once per release if the app ships in those markets.
+- Date / number / currency formatting in the relevant locales.
+
+## 10. Hand-off
+
+The device matrix lives at `.wize/planning/app/device-matrix.md` once Mantis + Tony agree on the audience. Hawkeye references it in every `tea-design.md`; CI configs (Maestro / Detox / BrowserStack) read the same matrix to avoid drift.