@roopesh.yadava/qa-pack 1.3.0 → 1.5.0

package/README.md

@@ -31,11 +31,12 @@ After installing:
    (plus `JIRA_BASE_URL` / `JIRA_EMAIL` / `JIRA_API_TOKEN` if you want bug screenshots attached).
 2. Open `CLAUDE.md` and fill in the non-secret project facts (Jira key, environment, auth method).
 
-`.claude/settings.local.json` (seeded once from `settings.local.json.example`) auto-approves
-Playwright MCP tool calls, since those run constantly during test execution and are scoped to
-the app under test. Every Atlassian/Jira MCP call — reading a card, filing a bug, commenting,
-transitioning — and any action needing your input (filing a bug, publishing a charter,
-overwriting product context) still prompts for confirmation.
+`.claude/settings.local.json` (seeded from `settings.local.json.example`, and re-checked on
+every install/update) auto-approves Playwright MCP tool calls, since those run constantly
+during test execution and are scoped to the app under test. Every Atlassian/Jira MCP call —
+reading a card, filing a bug, commenting, transitioning — and any action needing your input
+(filing a bug, publishing a charter, overwriting product context) still prompts for
+confirmation.
 
 Then open the repo in Claude Code and run:
 
@@ -90,19 +91,34 @@ and `/write-acceptance-criteria`, which are also available as explicit slash com
 | `delete files` / `clean up outputs` | delete-files | Prompts to delete/keep files in `outputs/` |
 | `/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 |
+| `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 |
+
+## The toolkit — why these features stay cheap
+
+Several features above (self-improving locator memory, DOM fingerprint caching, duplicate-bug
+detection, PII/secrets scanning, risk-based test ordering, the trust ratchet, and every
+`qa-insights` report) are powered by one dependency-free script:
+`.claude/skills/qa-agent/toolkit/qa-toolkit.cjs`. Skills shell out to it and read back a
+single line — parsing markdown tables, hashing DOM snapshots, scoring bug-title similarity,
+and aggregating every product's history are pure computation, so none of it costs a model
+token beyond the one line of output. This is also why `qa-insights` (dashboard/digest/ROI
+across every product you've ever tested) costs about the same whether you have 2 products or
+200 — the script does the aggregation, not the model.
 
 ## What postinstall does
 
 | File | Behaviour |
 |---|---|
-| `.claude/skills/*/SKILL.md` + companion `.md` files | Always overwritten (versioned logic) |
+| `.claude/skills/*/SKILL.md` + companion `.md`/`.cjs`/`.sh` files (e.g. the toolkit script) | Always overwritten (versioned logic) |
 | `.claude/skills/SKILLS_CONTEXT.md` | Always overwritten + stamped with the installed pack version |
 | `.claude/commands/*.md` | Always overwritten |
 | `.claude/skills/qa-agent/product_context/**` | **Never touched** after first seed |
 | `.claude/settings.json` | Created once, never overwritten |
 | `CLAUDE.md`, `.mcp.json`, `cucumber.cjs`, `.env` | Created once, never overwritten |
 | `.env.example` | Always refreshed (shows latest env keys) |
-| `.claude/settings.local.json` | Created once from example |
+| `.claude/settings.local.json` | Created once from example. Every subsequent install/update also checks for the Playwright MCP auto-approve rule (`mcp__playwright`) and adds it if missing — merged in without touching any other key you've set in the file. If the file isn't valid JSON, this merge is skipped with a warning and the file is left untouched. |
 | `.claude/settings.local.json.example` | Always refreshed (shows latest options) |
 | `.gitignore` | Managed `# >>> qa-pack` block regenerated on every install — ignores all pack-installed skills/commands plus `outputs/`, session files, and local settings |
 

package/bin/postinstall.js

@@ -104,6 +104,37 @@ copyFile(
   { overwrite: true }
 );
 
+// ── 4b. Force-ensure the Playwright MCP auto-approve rule ─────────────────────
+// Runs on every install/update, whether settings.local.json was just created above,
+// already existed from an older pack version that predates this rule, or was hand-
+// edited. Merges in only this one permissions.allow entry — every other key/value in
+// the file (including any other allow/deny/ask rules) is left exactly as it was.
+const PLAYWRIGHT_MCP_RULE = 'mcp__playwright';
+if (fs.existsSync(localSettingsDest)) {
+  try {
+    const settings = JSON.parse(fs.readFileSync(localSettingsDest, 'utf8'));
+    if (typeof settings.permissions !== 'object' || settings.permissions === null) {
+      settings.permissions = {};
+    }
+    if (!Array.isArray(settings.permissions.allow)) {
+      settings.permissions.allow = [];
+    }
+    const hasRule = settings.permissions.allow.some(
+      (rule) => rule === PLAYWRIGHT_MCP_RULE || rule === `${PLAYWRIGHT_MCP_RULE}__*`
+    );
+    if (!hasRule) {
+      settings.permissions.allow.push(PLAYWRIGHT_MCP_RULE);
+      fs.writeFileSync(localSettingsDest, `${JSON.stringify(settings, null, 2)}\n`);
+      log.updated.push(`${path.relative(PROJECT_ROOT, localSettingsDest)} (added Playwright MCP auto-approve rule)`);
+    }
+  } catch (e) {
+    console.warn(
+      `  Warning: could not parse ${path.relative(PROJECT_ROOT, localSettingsDest)} as JSON — left untouched.\n` +
+      `           Add "${PLAYWRIGHT_MCP_RULE}" to its permissions.allow array manually to auto-approve Playwright MCP calls.`
+    );
+  }
+}
+
 // ── 5. One-time templates (never overwrite — user fills these in) ─────────────
 const templates = [
   ['templates/CLAUDE.md',    'CLAUDE.md'],

package/claude/skills/SKILLS_CONTEXT.md

@@ -70,6 +70,45 @@ Structure every skill invocation in this order so the stable prefix can be cache
 The stable block qualifies for Anthropic prompt caching when it exceeds 1024 tokens.
 Cache TTL is 5 minutes. Keep the stable block identical across runs for the same product.
 
+### The Toolkit — the low-token path for anything product_context-shaped
+
+`.claude/skills/qa-agent/toolkit/qa-toolkit.cjs` is a dependency-free Node script, not a
+skill. It exists because parsing a markdown table, hashing a DOM snapshot, scoring string
+similarity, or aggregating dozens of products' history is pure computation — routing it
+through the model (Read the file → reason over it → maybe Edit it back) burns tokens on work
+that doesn't need a model at all. **Any skill needing one of the things below calls the
+toolkit and reads only its one-line result — never Read a whole context.md for this.**
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs <command> [--flags]
+```
+
+| Command | Used by | Purpose |
+|---------|---------|---------|
+| `get-bugs` / `get-runs` / `get-selectors` --product P | any skill | Cheap reads of one context.md table, pipe-delimited rows |
+| `fingerprint` --product P --url U --testids "a,b" | manual-testing, automation, roam-testing | DOM fingerprint cache — `UNCHANGED` means skip re-discovery |
+| `pii-scan` (stdin or `--file`) | bug-reporting, manual-testing, roam-testing | Flags emails/keys/tokens before anything is posted to Jira |
+| `dup-bug` --product P --summary S | bug-reporting, manual-testing, roam-testing | Fuzzy-matches a new bug against Known Bugs, no LLM comparison needed |
+| `cost-estimate` --product P [--phase N] | qa-agent | One-line run-cost estimate from Runs Log history |
+| `risk-score` --product P --modules "a,b" | manual-testing | Orders tests by git churn + past bug density, not AC order |
+| `trust-record` / `trust-status` --product P | automation (record), qa-agent (status) | Trust ratchet on Gate 1/Gate 2 approvals |
+| `locator-record` / `locator-query` --product P --page U | automation | Self-improving locator memory across self-heal fixes |
+| `dashboard` / `digest [--days N]` / `roi` | qa-insights | Cross-product reports — 100% script-generated, zero synthesis |
+
+This file is versioned logic (always overwritten on `npm update`, like every other skill
+file) — never store product data inside it. Its outputs live under
+`product_context/{PRODUCT}/` (`dom-fingerprints.json`, `trust.json`,
+`locator-learnings.md` — all new, all gitignored the same way `context.md` already is) or
+`outputs/` (`dashboard.html`, `qa-weekly-digest-*.md`, `roi-report.md`).
+
+**Never inline arbitrary text into a toolkit shell call.** Bug descriptions, locator
+strings, and anything else that isn't a short agent-controlled token (a card ID, a product
+folder name, a URL) can contain quotes, `` ` ``, `$(...)`, or `|` — inlined into a bash
+argument, that is a command-injection bug, not just an escaping nuisance. Write the text to
+a file with the Write tool first and pass the path: `pii-scan --file`, `dup-bug
+--summary-file`, `locator-record --file <json>`. Only short, structurally-constrained values
+(URLs, card IDs, product folder names) are safe to inline directly.
+
 ---
 
 ## Pipeline Overview
@@ -105,6 +144,10 @@ test-charter   │
     End-to-End Testing complete
 ```
 
+`roam-testing` (card-free exploratory) and `qa-insights` (dashboard/digest/roi) sit outside
+this diagram — they don't take a Jira card, and qa-insights doesn't touch Playwright at all.
+Both are driven by the toolkit rather than by each other.
+
 ## Skills — One-Line Summary
 
 | Skill | Input | Output | MCP Needed |
@@ -116,14 +159,17 @@ test-charter   │
 | `accessibility-testing` | Full page URL + Jira card (optional) | WCAG 2.1 A/AA report + Jira bugs | Playwright (CLI+MCP), Atlassian |
 | `bug-reporting` | Bug description | Bug filed on Jira card | Atlassian |
 | `test-charter` | Execution report MD file | Charter MD + published to API | Playwright (login) |
+| `roam-testing` | App URL, no card required | Roam report + optional bugs + charter | Playwright, Atlassian (optional) |
+| `qa-insights` | Nothing (reads all products) | Dashboard HTML / digest MD / ROI MD | None — pure toolkit |
 
 ## God Nodes (highest connectivity — touch these carefully)
 
-1. `automation` — 13 edges (Gherkin→StepDefs→POM chain, token tracking, Playwright MCP)
-2. `manual-testing` — 12 edges (orchestrates ui-test-figma, bug-reporting, test-charter)
-3. `qa-agent` — 7 edges (dispatches all paths, owns the Phase 3 pipeline)
-4. `test-charter` — 6 edges (reads execution report, publishes to Decision Record API)
-5. `ui-test-figma` — 6 edges (Figma MCP preferred, Playwright CLI fallback)
+1. `automation` — 15 edges (Gherkin→StepDefs→POM chain, token tracking, Playwright MCP, locator memory, trust ratchet)
+2. `manual-testing` — 15 edges (orchestrates ui-test-figma, bug-reporting, test-charter, risk-score, fingerprint, dup-bug)
+3. `qa-toolkit.cjs` — 6 skills call into it (qa-agent, automation, manual-testing, bug-reporting, roam-testing, qa-insights) — not a skill itself, but the single highest-fan-in file in the pack
+4. `qa-agent` — 9 edges (dispatches all paths, owns the Phase 3 pipeline, cost estimate + trust status)
+5. `test-charter` — 7 edges (reads execution report, publishes to Decision Record API; also used by roam-testing)
+6. `ui-test-figma` — 6 edges (Figma MCP preferred, Playwright CLI fallback)
 
 ## Dispatch Map (qa-agent routes)
 
@@ -135,6 +181,8 @@ Phase 3 / "full QA"        → manual-testing THEN automation (hints file reused
 "accessibility test"       → accessibility-testing (standalone, URL + optional Jira card)
 "file bug"                 → bug-reporting   (standalone)
 "charter"                  → test-charter    (standalone)
+"roam mode" / "explore"    → roam-testing    (standalone, no card — routed outside qa-agent)
+"dashboard"/"digest"/"roi" → qa-insights     (standalone, no card — routed outside qa-agent)
 ```
 
 **Input collection happens ONCE in qa-agent.** Sub-skills receive their parameters in the
@@ -236,3 +284,11 @@ First run will always be 0% (cold cache). Second and subsequent runs should cach
 | Token analytics | `~/.claude/token_analytics.png` |
 | Knowledge graph | `graphify-out/graph.html` (open in browser) |
 | Product QA context | `.claude/skills/qa-agent/product_context/[PRODUCT]/context.md` |
+| DOM fingerprint cache | `.claude/skills/qa-agent/product_context/[PRODUCT]/dom-fingerprints.json` |
+| Trust ratchet state | `.claude/skills/qa-agent/product_context/[PRODUCT]/trust.json` |
+| Locator learnings | `.claude/skills/qa-agent/product_context/[PRODUCT]/locator-learnings.md` |
+| Roam session report | `outputs/roam-report-[timestamp].md` |
+| Product health dashboard | `outputs/dashboard.html` |
+| QA weekly digest | `outputs/qa-weekly-digest-[date].md` |
+| Token-spend / ROI view | `outputs/roi-report.md` |
+| Shared toolkit CLI | `.claude/skills/qa-agent/toolkit/qa-toolkit.cjs` |

package/claude/skills/automation/SKILL.md

@@ -269,14 +269,21 @@ Present Gherkin + reuse report and ask:
 >
 > **Type "looks good" or "confirmed" to proceed to step definitions.**
 
-Do not write any `.cjs` files until confirmed. Iterate until approved.
+Do not write any `.cjs` files until confirmed. Iterate until approved. Once approved, record
+the trust ratchet — `clean` if the user approved on first presentation with no revision
+requests this gate, `edited` if they asked for any change before approving:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs trust-record --product {PRODUCT_FOLDER} --gate gate1 --result clean|edited
+```
 
 **If AUTO_APPROVE = true (called from qa-agent full pipeline):**
 
 Display the reuse report + a compact summary — do NOT wait:
 > "Gherkin generated for [CARD-ID]: {N} Rules, {N} scenarios, {X}% step reuse. Auto-approved — proceeding to step definitions."
 
-Immediately move to Phase 2 without waiting for any input.
+Immediately move to Phase 2 without waiting for any input. Do not call `trust-record` here —
+there was no human review to score.
 
 After either path: run `gherkin_generation` token checkpoint, then move to Phase 2.
 
@@ -329,14 +336,19 @@ Present step definitions and ask:
 >
 > **Type "looks good" or "confirmed" to proceed to the POM.**
 
-Do not write the POM until confirmed.
+Do not write the POM until confirmed. Once approved, record the trust ratchet the same way
+as Gate 1:
+
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs trust-record --product {PRODUCT_FOLDER} --gate gate2 --result clean|edited
+```
 
 **If AUTO_APPROVE = true (called from qa-agent full pipeline):**
 
 Display a compact summary only — do NOT wait:
 > "Step definitions generated for [CARD-ID]: {N} steps across {N} files. Auto-approved — proceeding to POM."
 
-Immediately move to Phase 3 without waiting for any input.
+Immediately move to Phase 3 without waiting for any input. Do not call `trust-record` here.
 
 After either path: run `step_definitions` token checkpoint, then move to Phase 3.
 
@@ -356,7 +368,31 @@ class. Only create a new POM class for a page that has none.
 Use the POM class template from BDD_TEMPLATES.md for new classes; match the existing
 class's style when extending.
 
-For every locator:
+**Locator memory check — once per page, before opening Playwright MCP for it:**
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs locator-query --product {PRODUCT_FOLDER} --page "PAGE_URL"
+```
+`NONE` → nothing learned yet for this page, proceed as usual. Rows returned → for each
+listed element, avoid its recorded **Failed Locator** even if it looks like the obvious
+choice; that pattern already broke a real test on this page. Prefer its recorded **Working
+Locator** if the element matches.
+
+**DOM fingerprint check — once per distinct page URL this run:**
+```javascript
+browser_evaluate({ expression: `
+  Array.from(document.querySelectorAll('[data-testid]')).map(el => el.getAttribute('data-testid')).join(',')
+` })
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs fingerprint --product {PRODUCT_FOLDER} --url "PAGE_URL" --testids "RESULT_FROM_ABOVE"
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs get-selectors --product {PRODUCT_FOLDER} --url "PAGE_URL"
+```
+If fingerprint says `UNCHANGED` and `get-selectors` returns rows covering the elements this
+Rule needs, write the POM locators straight from those rows — skip the per-element DOM
+inspection below entirely for this page. Otherwise (`NEW`/`CHANGED`, or a needed element is
+missing from `get-selectors`) fall through to the full inspection:
+
+For every locator not already resolved above:
 1. Navigate to the real page in the live app via Playwright MCP
 2. Inspect the target element in the DOM
 3. Check if `data-testid` already exists
@@ -420,7 +456,18 @@ On failure, diagnose and fix — **never hand off a silently failing test**:
 
 1. Read the failure: locator timeout? assertion mismatch? navigation/auth issue?
 2. Locator failures → re-inspect that element via Playwright MCP, fix the POM locator
-   (respect the locator priority table).
+   (respect the locator priority table). Once the fix passes, record it so no future run on
+   this product repeats the same wrong guess. Locator strings routinely contain quotes and
+   `|` (xpath unions) — never inline them into a shell command; write a small JSON file
+   instead (Write tool) and pass its path:
+   ```
+   Write outputs/.locator-tmp.json containing:
+   {"product": "{PRODUCT_FOLDER}", "page": "PAGE_URL", "element": "ELEMENT_LABEL",
+    "failed": "OLD_LOCATOR", "fixed": "NEW_LOCATOR", "reason": "ONE_LINE_WHY", "card": "{CARD_ID}"}
+   ```
+   ```bash
+   node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs locator-record --file outputs/.locator-tmp.json
+   ```
 3. Assertion failures → check whether expected text/behavior on the card matches the app.
    If the app appears genuinely wrong, this is a **bug, not a test fix** — stop healing
    that scenario, mark it failing, and note it as a bug candidate in the hand-off.

package/claude/skills/bug-reporting/SKILL.md

@@ -27,6 +27,12 @@ Display the list and ask:
 
 Wait for the user to select a project by number or board key. Save the selected project key for the rest of the flow.
 
+**Resolve `PRODUCT_FOLDER` (best-effort — only used by the duplicate check in Step 2a):**
+check whether `.claude/skills/qa-agent/product_context/{KEY}/context.md` exists, or any
+folder under `product_context/` starts with `{KEY}`. Found → store as `PRODUCT_FOLDER`.
+Not found → leave `PRODUCT_FOLDER` unset and skip the duplicate half of Step 2a silently;
+this is not an error, most exploratory-bug filing has no prior product context yet.
+
 ---
 
 ## Step 1A/1B — Ask card type
@@ -110,6 +116,38 @@ Do NOT ask the user for any missing fields. Use what was given and proceed.
 
 ---
 
+## Step 2a — Duplicate + PII/secrets check (script calls, no extra questions unless flagged)
+
+The user typed this text freely — it can contain quotes, `$`, backticks, anything. **Never**
+interpolate it directly into a shell command; write it to a file with the Write tool first
+and pass the file path instead.
+
+**Duplicate check — only if `PRODUCT_FOLDER` was resolved in Step 1:**
+```
+Write outputs/.dupcheck-tmp.txt containing: {Bug Title}
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs dup-bug --product {PRODUCT_FOLDER} --summary-file outputs/.dupcheck-tmp.txt
+```
+`NO_DUPLICATE_FOUND` → proceed silently. `POSSIBLE_DUPLICATE: {BUG-ID} (...) — "{title}"` →
+mention it once above the formatted report in Step 3: `"Heads up — this looks similar to
+{BUG-ID}: \"{title}\" ({status}). File as a new bug anyway, or add to that one instead?"`
+Follow whichever the user picks.
+
+**PII/secrets scan — always, regardless of PRODUCT_FOLDER:**
+```
+Write outputs/.piicheck-tmp.txt containing: {Bug Title}\n{Expected Outcome}\n{Actual Outcome}\n{Steps to Reproduce}
+```
+```bash
+node .claude/skills/qa-agent/toolkit/qa-toolkit.cjs pii-scan --file outputs/.piicheck-tmp.txt
+```
+Delete both temp files once this bug is posted (Step 6). `CLEAN` → proceed silently.
+`FLAGGED: ...` → show the flagged pattern types (never the raw
+match) and ask once: `"This bug report may contain real {types}. Redact before posting, or
+file as-is? (redact / as-is)"`. Apply the choice, then continue to Step 3.
+
+---
+
 ## Step 3 — Display the formatted bug report
 
 Show the bug report in this exact format before posting:

package/claude/skills/k6-framework-scaffold/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: k6-framework-scaffold
+description: Scaffold a ready-to-use k6 load-testing framework (Grafana Cloud) in a repo. Creates the k6-performance-tests/ tree — shared config/ + lib/, a protocol/ (API load) layer with api/flows/tests, and an OPTIONAL browser/ (UI) layer — with commented template files that testers then fill in. Use when someone asks to "set up k6", "create the k6 load testing structure/framework", "scaffold performance tests", or start load testing a new app.
+compatibility: >
+  Standalone skill — not part of the qa-agent pipeline. The bundled scaffold.sh only writes
+  files; the k6 CLI (and a Grafana Cloud account for `k6 cloud run`) is only needed later,
+  when the tester actually runs the generated tests.
+---
+
+# k6 Framework Scaffold
+
+Generates a standard, reusable k6 performance-testing framework so a tester can start from a
+ready structure and just fill in their app's endpoints, weights, and tokens.
+
+## What it creates
+
+```
+k6-performance-tests/
+├── config/     env.js · secrets.js · profiles.js        (shared: URLs, tokens, load shapes)
+├── lib/        http.js · rand.js · browser.js           (shared helpers)
+├── protocol/   api/{userTypeA,userTypeB}/ · flows/ · tests/{smoke,load,spike,breakpoint,endurance}/
+│               ── API / HTTP load — the CORE, needed for every app
+├── browser/    pages/ · flows/ · tests/
+│               ── real-browser UX — OPTIONAL, only for UI-heavy apps (delete if unneeded)
+└── README.md
+```
+
+Design principle: **separate WHAT we test (api → flows) from HOW MUCH load (profiles → tests)**,
+so the same endpoints/journeys are reused across every test type. All files are commented
+templates with `TODO`s.
+
+## How to run it
+
+From the target repo root, run the bundled script:
+
+```bash
+bash .claude/skills/k6-framework-scaffold/scaffold.sh
+```
+
+- It creates `k6-performance-tests/` in the current directory.
+- It is **safe**: if `k6-performance-tests/` already exists it aborts (won't overwrite).
+  Pass `--force` to scaffold into an existing folder (only adds missing files; still never
+  overwrites an existing file).
+
+After it runs, tell the tester the next steps:
+1. `config/env.js` — set `BASE` (API URL), `UI_BASE`s, `PROJECT_ID`, scale numbers, test data.
+2. `config/secrets.js` — paste auth tokens/credentials (git-ignored pattern).
+3. `protocol/api/**` — replace the sample endpoints with the real ones (one function per call).
+4. `protocol/flows/**` — set the weighted action table (feature-usage %) + thresholds (SLA).
+5. Browser layer is **optional** — keep it only for UI-heavy apps; otherwise delete `browser/`.
+6. Install k6, `k6 cloud login --token <token>`, then run from inside `k6-performance-tests/`:
+   `k6 run protocol/tests/smoke/example.smoke.js` (local) or `k6 cloud run ...`.
+
+## Notes
+- The script only writes files; it does not install k6 or run tests.
+- Keep real tokens out of version control (the scaffold's `.gitignore` covers `secrets.local.*`).
+- If the user wants the structure tailored (their user types, real endpoints from a Postman
+  collection), scaffold first, then edit the generated templates to match.