@roopesh.yadava/qa-pack 1.6.0 → 1.6.1

package/README.md

@@ -92,6 +92,8 @@ and `/write-acceptance-criteria`, which are also available as explicit slash com
 | `/write-acceptance-criteria PROJ-123` | write-acceptance-criteria | Generates AC, appends to the Jira card description |
 | `/impacted-tests` / `which tests are impacted by this pull` | impacted-tests | After pulling dev changes into a test branch, reports which Cucumber feature files are at risk — report-only, no card needed |
 | `set up k6` / `scaffold performance tests` | k6-framework-scaffold | Scaffolds a `k6-performance-tests/` framework (Grafana Cloud, protocol + optional browser layers) with commented templates to fill in — no card needed |
+| `set up mobile testing` / `set up mobilewright` / `scaffold mobile BDD tests` | mobilewright-setup | Scaffolds Cucumber.js + Mobilewright + a living-documentation HTML reporter into a mobile app repo (Expo, bare React Native, or native iOS/Android), plus one real smoke feature/step file — no card needed. Run once, before `mobile-automation` has anything to plug into |
+| `automate mobile PROJ-123` / `write mobile automation for this card` | mobile-automation | Reuse-first Gherkin → step defs → Screen POM → real device run + self-heal for native iOS/Android apps, via Mobile MCP + Mobilewright — the mobile counterpart to `automation` (web) |
 | `roam mode` / `explore the app` | roam-testing | Card-free exploratory testing — capped breadth-first crawl, report + optional bug filing + charter |
 | `qa dashboard` / `weekly digest` / `token roi` | qa-insights | Cross-product health dashboard, weekly digest, or token-spend/ROI view — 100% script-generated, no card needed |
 

package/claude/commands/bug-report.md

@@ -1,185 +1,11 @@
-You are a Jira bug reporting assistant. Follow these steps precisely and in order.
-
----
-
-## Step 1 — Select a project
-
-Use the Atlassian MCP tool (`getVisibleJiraProjects`) to fetch all visible projects immediately — do not wait for user input.
-
-Display the list and ask:
-"Which board are you working on? You can reply with the number or the board key:
-1. [KEY] — [Project Name]
-2. [KEY] — [Project Name]
-..."
-
-Wait for the user to select a project by number or board key. Save the selected project key for the rest of the flow.
-
----
-
-## Step 1A/1B — Ask card type
-
-Ask the user:
-"Is this an **Exploratory Bug** (create a new card) or an **Existing Card** (add bugs to an existing one)?"
-
-Wait for the user's choice before proceeding.
-
-- If the user chooses **Exploratory Bug** → go to Step 1A
-- If the user chooses **Existing Card** → go to Step 1B
-
----
-
-## Step 1A — Create a new Exploratory Bug card
-
-Ask the user: "Please enter a name for the Exploratory Bug card."
-
-Wait for the user's input.
-
-Use the Atlassian MCP tool (`createJiraIssue`) to create a new Jira issue in the selected project with:
-- **Issue Type:** Bug
-- **Summary:** [Card name entered by the user]
-- **Labels:** Exploratory
-
-After creating the issue, use `getTransitionsForJiraIssue` to fetch available transitions, then use `transitionJiraIssue` to move the card to **Backlog** status.
-
-Once created and moved to Backlog, display:
-
-> **Exploratory Bug card created:** [CARD-NUMBER] — [Card Name]
-> [Link to card]
-
-Save this card number as the active card for the rest of the flow. Then proceed to Step 2.
-
----
-
-## Step 1B — Use an existing card
-
-Ask the user: "Please enter the card number (e.g. 123 or [KEY]-123) to attach this bug report to."
-
-Wait for the user's input.
-
-If the user enters only a number (e.g. `2446`), construct the full card number using the selected project key (e.g. QE-2446).
-
-Use the Atlassian MCP tool (`getJiraIssue`) to fetch the card details. Display:
-
-> **Card found:** [CARD-NUMBER] — [Card Summary/Title]
-
-If the fetched card's issue type is **Bug**, ask:
-"Do you want to add the bugs to the **Description** or as a **Comment**?"
-
-Wait for the user's choice and save it as the **save mode** (Description or Comment) for use in Step 6.
-
-Save this card number as the active card for the rest of the flow. Then proceed to Step 2.
-
----
-
-## Step 2 — Collect bug details
-
-Ask the user: "Please describe the bug."
-
-Wait for the user's input. Accept whatever they provide — a sentence, a paragraph, or structured text.
-
-From the input, infer and derive all necessary fields:
-- **Bug Title** — extract or summarise from what was given
-- **Expected Outcome** — infer from context if not explicitly stated
-- **Actual Outcome** — extract the described problem
-- **Steps to Reproduce** — extract or derive from the description
-
-Do NOT ask the user for any missing fields. Use what was given and proceed.
-
 ---
-
-## Step 3 — Display the formatted bug report
-
-Show the bug report in this exact format before posting:
-
-### Bug No. [n]: [Bug Title]
-
-### Expected Outcome:
-[Expected Outcome]
-
-### Actual Outcome:
-[Actual Outcome]
-
-### Steps to Reproduce:
-[Steps]
-
-After showing the report, ask:
-"Is this the only bug, or do you have another bug to add?"
-
-- If the user says **yes (another bug)** — go back to Step 2 and collect the next bug. Append it to the report using the same format with an incremented Bug No. Repeat until the user says no more bugs.
-- If the user says **no more bugs** — proceed to Step 4.
-
+name: bug-report
+description: File a bug to Jira — new Exploratory Bug card or attached to an existing card.
+argument-hint: "[bug description | Jira card ID]"
+user-invocable: true
 ---
 
-## Step 4 — Ask who to mention
-
-Before posting, ask:
-"Who should I notify about this bug? Please enter the person's name, or type **none** to skip."
-
-Wait for the user's input.
-
-- If the user types **none** (or says no one / skip) → set mention as empty, skip Step 5, and proceed directly to Step 6. Do NOT add any mention or "Please check this" line in the report.
-- Otherwise → proceed to Step 5.
-
----
-
-## Step 5 — Search for the person in Jira
-
-Use the Atlassian MCP tool (`lookupJiraAccountId`) to search for the name the user entered.
-
-If multiple results are found, list them and ask:
-"Is this the right person? [Name — Account ID]"
-
-If only one result is found, display that person's name and ask:
-"Found: [Full Name]. Is this the right person? (yes / no)"
-
-Wait for confirmation before proceeding.
-
----
-
-## Step 6 — Save the bug report to Jira
-
-### If the card is an Exploratory Bug (created in Step 1A):
-
-Use the Atlassian MCP tool (`editJiraIssue`) to update the **Description** field of the card with the full bug report AND the mention at the end.
-
-The description body must follow this structure:
-
-```
-h3. Bug No. [n]: [Bug Title]
-
-h3. Expected Outcome:
-[Expected Outcome]
-
-h3. Actual Outcome:
-[Actual Outcome]
-
-h3. Steps to Reproduce:
-[Steps]
-
-(repeat the above block for each additional bug if more than one was collected)
-
-(only include the line below if a person was confirmed in Step 5 — omit it entirely if the user chose none)
-@[confirmed person's display name], Please check.
-```
-
-Do NOT post a comment. Write everything into the Description field of the card.
-
----
-
-### If the card is an Existing Card (from Step 1B):
-
-- If the user chose **Description** → use `editJiraIssue` to update the Description field with the full bug report and mention. Do NOT post a comment.
-- If the user chose **Comment** → use `addCommentToJiraIssue` to post one single comment with the full bug report and mention. Do NOT post a second separate comment.
-
-In both cases the content structure is the same as above.
-
----
-
-## Step 7 — Confirm completion
-
-Show a summary:
-- Jira card: [Card number with link]
-- Bug report posted: ✓
-- Notified: [Confirmed person's name]
+Invoke the `bug-reporting` skill.
 
-Done.
+If the user provided an argument (e.g. a bug description or a Jira card ID), pass it
+directly into the skill as the initial intent so it does not re-ask for input already given.

package/claude/commands/write-acceptance-criteria.md

@@ -14,8 +14,9 @@ user-invocable: true
 ## Core Workflow
 
 0. **Detect Jira card ID** — If the argument matches the pattern `[A-Z]+-[0-9]+` (e.g. `FF-420`, `AA-12`),
-   fetch the issue using the `getJiraIssue` tool with cloudId `853e134e-6574-491a-a075-1b06f7d4b478`.
-   Use the issue summary and description as the feature input for the next steps.
+   fetch the issue using the `getJiraIssue` tool. Use the issue summary and description as the
+   feature input for the next steps. Store the card's own URL (returned by the fetch) for the
+   confirmation step later — never hardcode a Jira domain.
    If the issue has no description, use the summary only and note this in the Assumptions section.
    If the argument is not a Jira card ID, treat it as a raw feature description and skip to step 1.
 
@@ -33,8 +34,8 @@ user-invocable: true
    - Fetch the current description of the issue using `getJiraIssue`
    - Preserve the full existing description exactly as-is (do NOT remove or overwrite any content, including COS or any other existing sections)
    - Append the generated acceptance criteria at the very bottom of the existing description, separated by a divider line (`---`)
-   - Update the issue description using `editJiraIssue` with cloudId `853e134e-6574-491a-a075-1b06f7d4b478`
-   - After updating, confirm to the user with the Jira issue URL: `https://7edge.atlassian.net/browse/<CARD-ID>`
+   - Update the issue description using `editJiraIssue`
+   - After updating, confirm to the user with the card's own URL (from the fetch in step 0) — never a hardcoded domain
 
 ---
 
@@ -125,43 +126,3 @@ If the feature description is vague:
 ---
 
 *Assumed: web-based product with a registered user model and a transactional email provider already in place. Adjust if this is a mobile or API-only context.*
-
-
-
-<!-- Created by Roopesh Yadava
-
-Generate detailed documentation for the feature: {{feature_description}}
-
-Follow these steps:
-
-1. **Identify scenarios** — Analyze the feature description and derive all possible user flows, including standard usage and edge cases.
-
-2. **Understand expected behavior** — Determine:
-
-   * What the user is trying to achieve
-   * System responses for valid and invalid inputs
-   * Possible failure points or UX gaps
-
-3. **Generate output** with the following structure:
-
-## Acceptance Criteria
-
-(Leave this section empty — do not list or rewrite anything here.)
-
-## Happy Paths
-
-* List all happy paths using numbered bullets.
-* Each step should describe one clear user action or system result.
-* Keep steps concise, realistic, and sequential.
-
-## Unhappy Paths
-
-* List all unhappy paths using numbered bullets.
-* Include:
-
-  * User errors
-  * Validation failures
-  * System issues
-  * Edge cases
-  * Missing or incorrect feedback
-  * Be specific and practical in each scenario. -->

package/claude/skills/SKILLS_CONTEXT.md

@@ -161,6 +161,13 @@ skill (same status as `roam-testing`/`k6-framework-scaffold`), not wired into qa
 Phase 2 dispatch, which remains web/Playwright-only via `automation`. Trigger it by name
 ("automate mobile PROJ-123", "mobile test PROJ-123") rather than through the qa-agent phase menu.
 
+`mobilewright-setup` sits outside this diagram too — a one-time scaffolder (same role as
+`k6-framework-scaffold`, but for a mobile app's BDD test stack instead of a perf-test stack),
+not a Jira-card-driven skill and not wired into qa-agent. It's what a repo needs *before*
+`mobile-automation` has anything to plug into — run it once on a repo with no existing
+Cucumber/Mobilewright setup, then use `mobile-automation` for ongoing card-driven test
+authoring against what it scaffolded.
+
 ## Skills — One-Line Summary
 
 | Skill | Input | Output | MCP Needed |
@@ -168,6 +175,7 @@ Phase 2 dispatch, which remains web/Playwright-only via `automation`. Trigger it
 | `qa-agent` | Jira card ID or menu choice | Dispatches to correct skill | Atlassian |
 | `automation` | Jira card ID | Reuse audit + Gherkin + Step Defs + POM + real run (reuse % reported) | Atlassian, Playwright |
 | `mobile-automation` | Jira card ID | Reuse audit + mobile Gherkin + Step Defs + Screen POM + real device run (reuse % reported) | Atlassian, Mobile MCP, MobileWright/mobilecli |
+| `mobilewright-setup` | Nothing (a repo to scaffold into) — no card needed | Cucumber.js + Mobilewright + living-documentation HTML reporter installed and wired into `package.json`, plus one real smoke feature/step file | None — pure file scaffolding + `npx mobilewright doctor`/local test run |
 | `manual-testing` | Jira card ID + app URL | Execution report + bugs + charter | Atlassian, Playwright |
 | `ui-test-figma` | Figma URL + app URL | UI mismatch report, Jira comment | Playwright (CLI+MCP), Figma (optional) |
 | `accessibility-testing` | Full page URL + Jira card (optional) | WCAG 2.1 A/AA report + Jira bugs | Playwright (CLI+MCP), Atlassian |

package/claude/skills/mobilewright-setup/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: mobilewright-setup
+description: >
+  Scaffolds a complete BDD end-to-end test automation setup for a mobile app repo —
+  Cucumber.js (Gherkin feature files + step definitions), Mobilewright (a
+  Playwright-style device automation framework for iOS/Android, native or
+  React Native/Expo), and a "living documentation" HTML report generator
+  (multiple-cucumber-html-reporter). Works on any mobile app project: Expo,
+  bare React Native, native iOS (UIKit/SwiftUI), or native Android
+  (Views/Jetpack Compose) — it detects the project shape and adapts.
+  Use this skill when the user asks to "set up mobile testing", "add BDD /
+  Cucumber tests", "set up mobilewright", "scaffold e2e tests for the mobile
+  app", "add a living documentation / test report generator", "wire up
+  test:report / living-doc script", or generally wants end-to-end mobile UI
+  test automation added to a repo from scratch. Also use it as a reference
+  when adding new feature files or step definitions to a project that
+  already has this setup, so conventions stay consistent.
+---
+
+# Mobile BDD Test Setup
+
+Sets up a full BDD test-automation stack for a mobile app repo, end to end:
+**Gherkin features → step definitions → Mobilewright device driver → Cucumber
+JSON reports → an HTML "living documentation" report.** Everything is created
+fresh in a single pass, adapted to whatever mobile project you're dropped into.
+
+This skill does the scaffolding. It does not know the target app's screens —
+budget time to explore the app's source (or a running build) to write the
+first real feature/step files with correct locators.
+
+## 0. Mental model
+
+- **Cucumber.js** runs `.feature` files (Gherkin) against step definitions in
+  `test/step-definitions/**/*.mjs`. It owns test discovery, execution, and
+  JSON report output.
+- **Mobilewright** (`mobilewright` npm package) is the device driver —
+  Playwright's API (`getByRole`, `getByText`, `expect(...).toBeVisible()`,
+  auto-waiting) but pointed at a real/emulated/simulated mobile device
+  instead of a browser. One config file (`mobilewright.config.mjs`) declares
+  which platform/device/app to drive; Cucumber's `World` uses it to launch
+  the app before each scenario.
+- **multiple-cucumber-html-reporter** turns the Cucumber JSON output into a
+  browsable "living documentation" HTML report — this is the `report` /
+  `living-doc.mjs` script.
+- Nothing here is React-Native-specific. Mobilewright drives the OS
+  accessibility tree, so this setup works for native iOS/Android apps too —
+  only the locators change (see §6).
+
+## 1. Discover the target project
+
+Before writing anything, gather facts. Do this with direct reads/greps, not
+guesses:
+
+1. **Package manager & repo shape** — read `package.json`. Note the `name`
+   and `version` (used later for report branding). Check for `expo` in
+   dependencies (Expo/RN project) vs. presence of `ios/`/`android/` native
+   folders only (bare RN or native project).
+2. **Bundle / package identifier** — look in this order and stop at the
+   first match:
+   - `app.config.ts` / `app.config.js` / `app.json` (Expo) — read
+     `ios.bundleIdentifier` and `android.package`. These are sometimes
+     computed by a function (env-variant based, like a `getBundleIdentifier()`
+     helper) rather than a plain string — if so, read the function to find
+     the actual default value, don't just grab the string "getBundleIdentifier()".
+   - `ios/*/Info.plist` → `CFBundleIdentifier`, or `*.xcodeproj` → `PRODUCT_BUNDLE_IDENTIFIER`.
+   - `android/app/build.gradle` (or `.kts`) → `applicationId`.
+   - If genuinely ambiguous (multiple variants/flavors: dev/qa/preprod/prod),
+     ask the user which build variant to test against — don't silently pick one.
+3. **Existing test setup** — check for `test/`, `e2e/`, `cucumber.js`,
+   `*.feature` files, or an existing `mobilewright.config.*`. If any of this
+   already exists, this is an **update**, not a fresh scaffold: read what's
+   there and extend it rather than overwriting. Never blindly clobber an
+   existing `mobilewright.config.*`, `cucumber.js`, or `world.mjs`.
+4. **Testing platform** — infer if possible (e.g. only `android/` present →
+   android; only `ios/` → ios). If both exist and the user didn't say, ask.
+
+Only ask the user (via a clarifying question) for facts you could not
+determine from the repo: target **platform** (`ios`/`android`), a
+**device** to run against (a specific simulator/emulator name, or "use
+auto-discovery"), and the **bundle/app id** if it's genuinely ambiguous.
+Everything else, infer and proceed — this skill runs under an
+auto/no-interruption workflow by default, so don't stop for things you can
+reasonably derive.
+
+## 2. Install dependencies
+
+Detect the package manager from the lockfile present (`package-lock.json` →
+npm, `yarn.lock` → yarn, `pnpm-lock.yaml` → pnpm, `bun.lockb` → bun) and
+install as **devDependencies**:
+
+```bash
+npm install -D @cucumber/cucumber mobilewright multiple-cucumber-html-reporter
+```
+
+(swap `npm install -D` for the equivalent `yarn add -D` / `pnpm add -D` /
+`bun add -d` as appropriate). Do not add these as runtime `dependencies`.
+
+## 3. Create `mobilewright.config.mjs`
+
+Write to the project root. Fill in the platform/bundleId/device values
+discovered or confirmed in step 1 — never leave placeholder text in the
+committed file.
+
+```javascript
+import { defineConfig } from 'mobilewright';
+
+export default defineConfig({
+  platform: '{{PLATFORM}}', // 'android' | 'ios'
+  bundleId: '{{BUNDLE_ID}}', // e.g. com.example.myapp(.qa)
+  deviceId: '{{DEVICE_ID}}', // named emulator/simulator profile, if the user gave one — omit this line if using auto-discovery instead
+  deviceType: '{{DEVICE_TYPE}}', // 'emulator' | 'simulator' | 'real-device' — omit if unknown
+  timeout: 30_000,
+});
+```
+
+Notes:
+- `deviceId`/`deviceType` are optional — Mobilewright auto-discovers the
+  first booted device matching `platform` if omitted. Prefer auto-discovery
+  unless the user specifically named a device/profile.
+- If the project already targets both platforms via CI, consider the
+  `projects` array (Mobilewright's multi-device/platform matrix — see the
+  `projects` option in the mobilewright package's own `README.md` under
+  `node_modules/mobilewright/README.md`, or https://mobilewright.dev) instead
+  of a single flat config. Only do this if the user asks for multi-platform
+  runs; default to a single flat config otherwise.
+- A one-line comment noting *why* a value was picked (e.g. "QA build shared
+  for testing") is fine and matches existing convention, but keep it to one
+  line.
+
+## 4. Create `cucumber.js`
+
+Root-level Cucumber profile. This wires feature discovery, step import, and
+report output:
+
+```javascript
+module.exports = {
+  default: [
+    'test/features/**/*.feature',
+    '--import test/step-definitions/**/*.mjs',
+    `--format json:reports/cucumber-report-${Date.now()}.json`,
+    '--format summary',
+    '--format progress-bar',
+  ].join(' '),
+};
+```
+
+Keep the feature/step-definition globs as-is unless the target repo already
+uses a different test root (e.g. `e2e/` instead of `test/`) — match whatever
+already exists rather than introducing a second convention.
+
+## 5. Create `test/step-definitions/support/world.mjs`
+
+This is the Cucumber `World` — it owns the device lifecycle (launch before
+each scenario, close after). This file is intentionally app-agnostic; do not
+add app-specific logic here.
+
+```javascript
+import { setWorldConstructor, setDefaultTimeout, Before, After } from '@cucumber/cucumber';
+import { ios, android } from 'mobilewright';
+import config from '../../../mobilewright.config.mjs';
+
+setDefaultTimeout(config.timeout ?? 30_000);
+
+class MobileWorld {
+  async launch() {
+    const launcher = config.platform === 'android' ? android : ios;
+    this.device = await launcher.launch({
+      bundleId: config.bundleId,
+      deviceId: config.deviceId,
+      deviceName: config.deviceName,
+      installApps: config.installApps,
+    });
+    this.screen = this.device.screen;
+  }
+
+  async teardown() {
+    await this.device?.close();
+  }
+}
+
+setWorldConstructor(MobileWorld);
+
+Before(async function () {
+  await this.launch();
+});
+
+After(async function () {
+  await this.teardown();
+});
+```
+
+Every step definition gets `this.device` and `this.screen` from this World —
+step files never construct their own device connection.
+
+## 6. Write the first feature + step definitions
+
+Don't hand-wave this — a setup with zero real assertions isn't done. Find one
+real, stable entry point in the app under test and write one smoke scenario
+against it:
+
+1. **Find a locator.** Grep the app source for existing test hooks in
+   priority order (this matches Mobilewright's own locator priority:
+   `getByTestId` > `getByRole` > `getByLabel` > `getByText`):
+   - React Native/Expo: search for `testID=`, `accessibilityLabel=`,
+     `accessibilityRole=` props on the first/home screen's root and key
+     interactive elements.
+   - Native iOS: `accessibilityIdentifier` / `accessibilityLabel` in
+     SwiftUI/UIKit source.
+   - Native Android: `contentDescription` / view `id`s, or Compose
+     `Modifier.testTag(...)` / `semantics { }`.
+   - If nothing is tagged yet, don't invent testIDs blindly — either add a
+     minimal `testID`/`accessibilityIdentifier` to the one element you need
+     (small, targeted, and tell the user you did it), or fall back to
+     `getByText('...')` against real on-screen copy you found in source.
+2. **If you can run a booted simulator/emulator**, `npx mobilewright inspect`
+   opens a live element inspector against the connected device — use it to
+   confirm real locators instead of guessing from source alone.
+3. Write `test/features/<area>.feature`:
+
+```gherkin
+Feature: <Screen or flow name>
+
+  Scenario: <one concrete, observable outcome>
+    Given <a starting state, e.g. "the app has launched">
+    Then <an assertion tied to a real locator>
+```
+
+4. Write the matching `test/step-definitions/<area>.steps.mjs`:
+
+```javascript
+import { Given, When, Then } from '@cucumber/cucumber';
+import { expect } from 'mobilewright';
+
+Given('the app has launched', async function () {
+  await expect(this.screen.getByTestId('<real-test-id>')).toBeVisible();
+});
+```
+
+Step conventions to follow:
+- One `Given`/`When`/`Then` per file topic; keep step text reusable across
+  scenarios in the same feature area rather than one-off phrasing per
+  scenario.
+- Prefer `getByTestId` / `getByRole` over `getByText`/coordinate taps —
+  they're the least brittle across locale and copy changes.
+- Never hardcode secrets (passwords, tokens) directly in `.feature` files if
+  the repo has an env/secrets convention already (`.env`, CI variable
+  groups, etc.) — follow that repo's existing pattern instead. If unsure, ask.
+
+## 7. Create `scripts/living-doc.mjs`
+
+Generates the browsable HTML report from the Cucumber JSON output. Pull
+branding from `package.json` — never hardcode a project name:
+
+```javascript
+import { readFileSync } from 'fs';
+import { generate } from 'multiple-cucumber-html-reporter';
+import config from '../mobilewright.config.mjs';
+
+const { name, version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)));
+
+const displayName = '{{DISPLAY_NAME}}'; // human-readable project name, e.g. derived from package.json `name`
+
+generate({
+  jsonDir: 'reports/',
+  reportPath: 'living-documentation/',
+  pageTitle: displayName,
+  pageFooter: `<div class="created-by"><p>${displayName} QA</p></div>`,
+  reportName: displayName,
+  metadata: {
+    device: config.deviceName ?? config.deviceId,
+    platform: { name: config.platform === 'ios' ? 'iOS' : 'Android', version: '' },
+    app: { name, version },
+  },
+  customData: {
+    title: 'Run info',
+    data: [{ label: 'Project', value: name }],
+  },
+});
+```
+
+Derive `displayName` from `package.json`'s `name` (title-cased, hyphens/
+underscores replaced with spaces) unless the repo already has an obvious
+human-readable product name elsewhere (README title, app display name in
+`app.config.*`/`app.json`) — prefer that if present.
+
+## 8. Wire up `package.json` scripts
+
+Add (don't replace unrelated existing scripts):
+
+```json
+{
+  "scripts": {
+    "test": "cucumber-js",
+    "test:doctor": "mobilewright doctor",
+    "report": "node scripts/living-doc.mjs",
+    "test:report": "npm run test && npm run report"
+  }
+}
+```
+
+If a `test` script already exists for a different test runner (unit tests,
+etc.), don't clobber it — use a distinct name instead
+(`test:e2e`/`test:bdd`/`test:mobile`) and say so to the user, then adjust
+`test:report` to reference the new name.
+
+## 9. Update `.gitignore`
+
+Ensure generated test artifacts aren't committed. Add if missing:
+
+```
+# cucumber JSON reports + generated living documentation
+reports
+living-documentation
+
+# test app binaries (built artifacts, not source)
+test/app/
+```
+
+Only add the `test/app/` line if the repo's test setup installs app binaries
+locally (check whether `installApps` is used in the config); skip it
+otherwise.
+
+## 10. Verify the environment
+
+Run the doctor check and report its output to the user — don't just assume
+success:
+
+```bash
+npx mobilewright doctor
+```
+
+This validates Xcode/Android SDK/emulator-simulator availability and tells
+you exactly what's missing. Surface any failures verbatim; don't try to
+silently work around a missing SDK/toolchain.
+
+If a device is booted and reachable, also do a real run to confirm the
+scaffold works end to end:
+
+```bash
+npm run test:report
+```
+
+## 11. Summary to the user
+
+After setup, tell the user concretely:
+- What was installed and created (file list).
+- Which platform/device/bundle id the config targets, and why (inferred vs.
+  user-provided).
+- The doctor check result.
+- How to run tests day to day: `npm test` (or the chosen script name),
+  `npm run report` / `npm run test:report`, and where the living-doc report
+  lands (`living-documentation/index.html`).
+- That new features go in `test/features/*.feature` with matching
+  `test/step-definitions/*.steps.mjs`, and that `world.mjs` under
+  `test/step-definitions/support/` should stay app-agnostic — device
+  lifecycle only, no scenario-specific logic.
+
+## Reference
+
+Full Mobilewright API (locators, assertions, config options, CLI commands)
+is documented in the installed package at `node_modules/mobilewright/README.md`
+and `node_modules/mobilewright/reference.md` once installed — read those
+directly rather than relying on memory when writing non-trivial step
+definitions (e.g. WebView bridging, multi-device `projects` config, role
+mapping tables).

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@roopesh.yadava/qa-pack",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "AI-powered QA agent skills for Claude Code — manual testing, BDD automation, accessibility, UI/Figma diff, bug reporting",
   "scripts": {
-    "postinstall": "node bin/postinstall.js"
+    "postinstall": "node bin/postinstall.js",
+    "test": "node --test test/"
   },
   "files": [
     "bin/",