diff --git a/src/modules/bmm/agents/tea.md b/src/modules/bmm/agents/tea.md
index f8bba936..3deb44f9 100644
--- a/src/modules/bmm/agents/tea.md
+++ b/src/modules/bmm/agents/tea.md
@@ -12,8 +12,9 @@
Load into memory {project-root}/bmad/bmm/config.yaml and set variable project_name, output_folder, user_name, communication_language
- Load into memory {project-root}/bmad/bmm/testarch/tea-knowledge.md and {project-root}/bmad/bmm/testarch/test-resources-for-ai-flat.txt for Murat’s latest guidance and examples
- Cross-check recommendations with the current official Playwright, Cypress, Pact, and CI platform documentation when repo guidance appears outdated
+ Load into memory {project-root}/bmad/bmm/testarch/tea-knowledge.md for Murat’s latest heuristics
+ Consult {project-root}/bmad/bmm/testarch/tea-index.csv to select knowledge fragments under `knowledge/` and load only the files needed for the current task
+ Cross-check recommendations with the current official Playwright, Cypress, Pact, and CI platform documentation; fall back to {project-root}/bmad/bmm/testarch/test-resources-for-ai-flat.txt only when deeper sourcing is required
Remember the users name is {user_name}
ALWAYS communicate in {communication_language}
diff --git a/src/modules/bmm/testarch/README.md b/src/modules/bmm/testarch/README.md
index 402c2499..65824de2 100644
--- a/src/modules/bmm/testarch/README.md
+++ b/src/modules/bmm/testarch/README.md
@@ -154,6 +154,8 @@ We keep every Test Architect workflow under `workflows/testarch/` instead of sca
- **Supporting Knowledge:**
- `tea-knowledge.md` – Murat’s testing philosophy, heuristics, and risk scales.
+ - `tea-index.csv` – Catalog of knowledge fragments with tags and file paths under `knowledge/` for task-specific loading.
- `test-levels-framework.md` – Decision matrix for unit/integration/E2E selection.
- `test-priorities-matrix.md` – Priority (P0–P3) criteria and target coverage percentages.
- - `test-resources-for-ai-flat.txt` – Flattened 347 KB bundle of Murat’s blogs, philosophy notes, and training material. Each `FILE:` section can be loaded on demand when the agent needs deeper examples or rationale.
+ - `knowledge/*.md` – Focused summaries (fixtures, network, CI, etc.) distilled from Murat’s external resources.
+ - `test-resources-for-ai-flat.txt` – Raw 347 KB archive retained for manual deep dives when a fragment needs source validation.
diff --git a/src/modules/bmm/testarch/knowledge/ci-burn-in.md b/src/modules/bmm/testarch/knowledge/ci-burn-in.md
new file mode 100644
index 00000000..cfb8cadc
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/ci-burn-in.md
@@ -0,0 +1,9 @@
+# CI Pipeline and Burn-In Strategy
+
+- Stage jobs: install/caching once, run `test-changed` for quick feedback, then shard full suites with `fail-fast: false` so evidence isn’t lost.
+- Re-run changed specs 5–10x (burn-in) before merging to flush flakes; fail the pipeline on the first inconsistent run.
+- Upload artifacts on failure (videos, traces, HAR) and keep retry counts explicit—hidden retries hide instability.
+- Use `wait-on` for app startup, enforce time budgets (<10 min per job), and document required secrets alongside workflows.
+- Mirror CI scripts locally (`npm run test:ci`, `scripts/burn-in-changed.sh`) so devs reproduce pipeline behaviour exactly.
+
+_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples._
diff --git a/src/modules/bmm/testarch/knowledge/component-tdd.md b/src/modules/bmm/testarch/knowledge/component-tdd.md
new file mode 100644
index 00000000..d73af37b
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/component-tdd.md
@@ -0,0 +1,9 @@
+# Component Test-Driven Development Loop
+
+- Start every UI change with a failing component spec (`cy.mount` or RTL `render`); ship only after red → green → refactor passes.
+- Recreate providers/stores per spec to prevent state bleed and keep parallel runs deterministic.
+- Use factories to exercise prop/state permutations; cover accessibility by asserting against roles, labels, and keyboard flows.
+- Keep component specs under ~100 lines: split by intent (rendering, state transitions, error messaging) to preserve clarity.
+- Pair component tests with visual debugging (Cypress runner, Storybook, Playwright trace viewer) to accelerate diagnosis.
+
+_Source: CCTDD repository, Murat component testing talks._
diff --git a/src/modules/bmm/testarch/knowledge/contract-testing.md b/src/modules/bmm/testarch/knowledge/contract-testing.md
new file mode 100644
index 00000000..4bc1c483
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/contract-testing.md
@@ -0,0 +1,9 @@
+# Contract Testing Essentials (Pact)
+
+- Store consumer contracts beside the integration specs that generate them; version contracts semantically and publish on every CI run.
+- Require provider verification before merge; failed verification blocks release and surfaces breaking changes immediately.
+- Capture fallback behaviour inside interactions (timeouts, retries, error payloads) so resilience guarantees remain explicit.
+- Automate broker housekeeping: tag releases, archive superseded contracts, and expire unused pacts to reduce noise.
+- Pair contract suites with API smoke or component tests to validate data mapping and UI rendering in tandem.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog._
diff --git a/src/modules/bmm/testarch/knowledge/data-factories.md b/src/modules/bmm/testarch/knowledge/data-factories.md
new file mode 100644
index 00000000..c7fffea3
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/data-factories.md
@@ -0,0 +1,9 @@
+# Data Factories and API-First Setup
+
+- Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`)—never rely on static fixtures.
+- Seed state through APIs, tasks, or direct DB helpers before visiting the UI; UI-based setup is for validation only.
+- Ensure factories generate parallel-safe identifiers (UUIDs, timestamps) and perform cleanup after each test.
+- Centralize factory exports to avoid duplication; version them alongside schema changes to catch drift in reviews.
+- When working with shared environments, layer feature toggles or targeted cleanup so factories do not clobber concurrent runs.
+
+_Source: Murat Testing Philosophy, blog posts on functional helpers and API-first testing._
diff --git a/src/modules/bmm/testarch/knowledge/email-auth.md b/src/modules/bmm/testarch/knowledge/email-auth.md
new file mode 100644
index 00000000..282eb99a
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/email-auth.md
@@ -0,0 +1,9 @@
+# Email-Based Authentication Testing
+
+- Use services like Mailosaur or in-house SMTP capture; extract magic links via regex or HTML parsing helpers.
+- Preserve browser storage (local/session) when processing links—restore state before visiting the authenticated page.
+- Cache email payloads with `cypress-data-session` or equivalent so retries don’t exhaust inbox quotas.
+- Cover negative cases: expired links, reused links, and multiple requests in rapid succession.
+- Ensure the workflow logs the email ID and link for troubleshooting, but scrub PII before committing artifacts.
+
+_Source: Email authentication blog, Murat testing toolkit._
diff --git a/src/modules/bmm/testarch/knowledge/error-handling.md b/src/modules/bmm/testarch/knowledge/error-handling.md
new file mode 100644
index 00000000..145507ba
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/error-handling.md
@@ -0,0 +1,9 @@
+# Error Handling and Resilience Checks
+
+- Treat expected failures explicitly: intercept network errors and assert UI fallbacks (`error-message` visible, retries triggered).
+- In Cypress, use scoped `Cypress.on('uncaught:exception')` to ignore known errors; rethrow anything else so regressions fail.
+- In Playwright, hook `page.on('pageerror')` and only swallow the specific, documented error messages.
+- Test retry/backoff logic by forcing sequential failures (e.g., 500, timeout, success) and asserting telemetry gets recorded.
+- Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+_Source: Murat error-handling patterns, Pact resilience guidance._
diff --git a/src/modules/bmm/testarch/knowledge/feature-flags.md b/src/modules/bmm/testarch/knowledge/feature-flags.md
new file mode 100644
index 00000000..f0b6e3bb
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/feature-flags.md
@@ -0,0 +1,9 @@
+# Feature Flag Governance
+
+- Centralize flag definitions in a frozen enum; expose helpers to set, clear, and target specific audiences.
+- Test both enabled and disabled states in CI; clean up targeting after each spec to keep shared environments stable.
+- For LaunchDarkly-style systems, script API helpers to seed variations instead of mutating via UI.
+- Maintain a checklist for new flags: default state, owners, expiry date, telemetry, rollback plan.
+- Document flag dependencies in story/PR templates so QA and release reviews know which toggles must flip before launch.
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes._
diff --git a/src/modules/bmm/testarch/knowledge/fixture-architecture.md b/src/modules/bmm/testarch/knowledge/fixture-architecture.md
new file mode 100644
index 00000000..0004443b
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/fixture-architecture.md
@@ -0,0 +1,9 @@
+# Fixture Architecture Playbook
+
+- Build helpers as pure functions first, then expose them via Playwright `extend` or Cypress commands so logic stays testable in isolation.
+- Compose capabilities with `mergeTests` (Playwright) or layered Cypress commands instead of inheritance; each fixture should solve one concern (auth, api, logs, network).
+- Keep HTTP helpers framework agnostic—accept all required params explicitly and return results so unit tests and runtime fixtures can share them.
+- Export fixtures through package subpaths (`"./api-request"`, `"./api-request/fixtures"`) to make reuse trivial across suites and projects.
+- Treat fixture files as infrastructure: document dependencies, enforce deterministic timeouts, and ban hidden retries that mask flakiness.
+
+_Source: Murat Testing Philosophy, cy-vs-pw comparison, SEON production patterns._
diff --git a/src/modules/bmm/testarch/knowledge/network-first.md b/src/modules/bmm/testarch/knowledge/network-first.md
new file mode 100644
index 00000000..4d26064d
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/network-first.md
@@ -0,0 +1,9 @@
+# Network-First Safeguards
+
+- Register interceptions before any navigation or user action; store the promise and await it immediately after the triggering step.
+- Assert on structured responses (status, body schema, headers) instead of generic waits so failures surface with actionable context.
+- Capture HAR files or Playwright traces on successful runs—reuse them for deterministic CI playback when upstream services flake.
+- Prefer edge mocking: stub at service boundaries, never deep within the stack unless risk analysis demands it.
+- Replace implicit waits with deterministic signals like `waitForResponse`, disappearance of spinners, or event hooks.
+
+_Source: Murat Testing Philosophy, Playwright patterns book, blog on network interception._
diff --git a/src/modules/bmm/testarch/knowledge/playwright-config.md b/src/modules/bmm/testarch/knowledge/playwright-config.md
new file mode 100644
index 00000000..5f942a3c
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/playwright-config.md
@@ -0,0 +1,9 @@
+# Playwright Configuration Guardrails
+
+- Load environment configs via a central map (`envConfigMap`) and fail fast when `TEST_ENV` is missing or unsupported.
+- Standardize timeouts: action 15s, navigation 30s, expect 10s, test 60s; expose overrides through fixtures rather than inline literals.
+- Emit HTML + JUnit reporters, disable auto-open, and store artifacts under `test-results/` for CI upload.
+- Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+- Use global setup for shared auth tokens or seeding, but prefer per-test fixtures for anything mutable to avoid cross-test leakage.
+
+_Source: Playwright book repo, SEON configuration example._
diff --git a/src/modules/bmm/testarch/knowledge/selective-testing.md b/src/modules/bmm/testarch/knowledge/selective-testing.md
new file mode 100644
index 00000000..2f78f2bd
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/selective-testing.md
@@ -0,0 +1,9 @@
+# Selective and Targeted Test Execution
+
+- Use tags/grep (`--grep "@smoke"`, `--grep "@critical"`) to slice suites by risk, not directory.
+- Filter by spec patterns (`--spec "**/*checkout*"`) or git diff (`npm run test:changed`) to focus on impacted areas.
+- Combine priority metadata (P0–P3) with change detection to decide which levels to run pre-commit vs. in CI.
+- Record burn-in history for newly added specs; promote to main suite only after consistent green runs.
+- Document the selection strategy in README/CI so the team understands when full regression is mandatory.
+
+_Source: 32+ selective testing strategies blog, Murat testing philosophy._
diff --git a/src/modules/bmm/testarch/knowledge/visual-debugging.md b/src/modules/bmm/testarch/knowledge/visual-debugging.md
new file mode 100644
index 00000000..5468f8dd
--- /dev/null
+++ b/src/modules/bmm/testarch/knowledge/visual-debugging.md
@@ -0,0 +1,9 @@
+# Visual Debugging and Developer Ergonomics
+
+- Keep Playwright trace viewer, Cypress runner, and Storybook accessible in CI artifacts to speed up reproduction.
+- Record short screen captures only-on-failure; pair them with HAR or console logs to avoid guesswork.
+- Document common trace navigation steps (network tab, action timeline) so new contributors diagnose issues quickly.
+- Encourage live-debug sessions with component harnesses to validate behaviour before writing full E2E specs.
+- Integrate accessibility tooling (axe, Playwright audits) into the same debug workflow to catch regressions early.
+
+_Source: Murat DX blog posts, Playwright book appendix on debugging._
diff --git a/src/modules/bmm/testarch/tea-index.csv b/src/modules/bmm/testarch/tea-index.csv
new file mode 100644
index 00000000..f312b3f2
--- /dev/null
+++ b/src/modules/bmm/testarch/tea-index.csv
@@ -0,0 +1,13 @@
+id,name,description,tags,fragment_file
+fixture-architecture,Fixture Architecture,"Composable fixture patterns (pure function → fixture → merge) and reuse rules","fixtures,architecture,playwright,cypress",knowledge/fixture-architecture.md
+network-first,Network-First Safeguards,"Intercept-before-navigate workflow, HAR capture, deterministic waits, edge mocking","network,stability,playwright,cypress",knowledge/network-first.md
+data-factories,Data Factories & API Setup,"Factories with overrides, API seeding, cleanup discipline","data,factories,setup,api",knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",knowledge/component-tdd.md
+playwright-config,Playwright Config Guardrails,"Environment switching, timeout standards, artifact outputs","playwright,config,env",knowledge/playwright-config.md
+ci-burn-in,CI & Burn-In Strategy,"Staged jobs, shard orchestration, burn-in loops, artifact policy","ci,automation,flakiness",knowledge/ci-burn-in.md
+selective-testing,Selective Test Execution,"Tag/grep usage, spec filters, diff-based runs, promotion rules","risk-based,selection,strategy",knowledge/selective-testing.md
+feature-flags,Feature Flag Governance,"Enum management, targeting helpers, cleanup, release checklists","feature-flags,governance,launchdarkly",knowledge/feature-flags.md
+contract-testing,Contract Testing Essentials,"Pact publishing, provider verification, resilience coverage","contract-testing,pact,api",knowledge/contract-testing.md
+email-auth,Email Authentication Testing,"Magic link extraction, state preservation, caching, negative flows","email-authentication,security,workflow",knowledge/email-auth.md
+error-handling,Error Handling Checks,"Scoped exception handling, retry validation, telemetry logging","resilience,error-handling,stability",knowledge/error-handling.md
+visual-debugging,Visual Debugging Toolkit,"Trace viewer usage, artifact expectations, accessibility integration","debugging,dx,tooling",knowledge/visual-debugging.md
diff --git a/src/modules/bmm/testarch/tea-knowledge.md b/src/modules/bmm/testarch/tea-knowledge.md
index 21e7ae5c..e1fdc636 100644
--- a/src/modules/bmm/testarch/tea-knowledge.md
+++ b/src/modules/bmm/testarch/tea-knowledge.md
@@ -2,7 +2,7 @@
# Murat Test Architecture Foundations (Slim Brief)
-This brief distills Murat Ozcan's testing philosophy used by the Test Architect agent. Use it as the north star while executing the TEA workflows.
+This brief distills Murat Ozcan's testing philosophy used by the Test Architect agent. Use it as the north star while executing the TEA workflows, and rely on `tea-index.csv` to pull deeper fragments on demand.
## Core Principles
@@ -325,34 +325,35 @@ history:
## Reference Capsules (Summaries Bundled In)
-- **Fixture Architecture Quick Wins**
+- **Fixture Architecture Quick Wins** (`knowledge/fixture-architecture.md`)
- Compose Playwright or Cypress suites with additive fixtures; use `mergeTests`/`extend` to layer auth, network, and telemetry helpers without inheritance.
- Keep HTTP helpers framework-agnostic so the same function fuels unit tests, API smoke checks, and runtime fixtures.
- Normalize selectors (`data-testid`/`data-cy`) and lint new UI code for missing attributes to prevent brittle locators.
-- **Playwright Patterns Digest**
+- **Network & Playwright Patterns** (`knowledge/network-first.md`, `knowledge/playwright-config.md`)
- Register network interceptions before navigation, assert on typed responses, and capture HAR files for regression.
- Treat timeouts and retries as configuration, not inline magic numbers; expose overrides via fixtures.
- Name specs and test IDs with intent (`checkout.complete-happy-path`) so CI shards and triage stay meaningful.
-- **Component TDD Highlights**
+- **Component TDD Highlights** (`knowledge/component-tdd.md`, `knowledge/data-factories.md`)
- Begin UI work with failing component specs; rebuild providers/stores per spec to avoid state bleed.
- Use factories to exercise prop variations and edge cases; assert through accessible queries (`getByRole`, `getByLabelText`).
- Document mount helpers and cleanup expectations so component tests stay deterministic.
-- **Contract Testing Cliff Notes**
+- **Contract Testing Cliff Notes** (`knowledge/contract-testing.md`)
- Store consumer contracts alongside integration specs; version with semantic tags and publish on every CI run.
- Enforce provider verification prior to merge to act as a release gate for service integrations.
- Capture fallback behaviour (timeouts, retries, circuit breakers) inside contracts to keep resilience expectations explicit.
-- **End-to-End Reference Flow**
+- **End-to-End Reference Flow** (`knowledge/ci-burn-in.md`, `knowledge/selective-testing.md`)
- Prime end-to-end journeys through API fixtures, then assert through UI steps mirroring real user narratives.
- Pair burn-in scripts (`npm run test:e2e -- --repeat-each=3`) with selective retries to flush flakes before promotion.
-- **Philosophy & Heuristics Articles**
- - Use long-form articles for rationale; extract checklists, scripts, and thresholds back into this brief whenever teams adopt new practices.
+- **Special Topics** (`knowledge/feature-flags.md`, `knowledge/email-auth.md`, `knowledge/error-handling.md`, `knowledge/visual-debugging.md`)
+ - Feature flag governance, targeted email-auth flows, resilient error handling, and visual debugging ergonomics captured as separate fragments.
+ - Use the Murat knowledge bundle only when these fragments need deeper sourcing.
-These capsules distil Murat's sample repositories (Playwright patterns, Cypress vs Playwright comparisons, CCTDD, Pact examples, Tour of Heroes walkthrough) captured in the `test-resources-for-ai` knowledge pack so the TEA agent can operate offline while reflecting those techniques.
+These capsules map to focused fragments stored under `knowledge/`. Each fragment is catalogued in `tea-index.csv` so workflows can load only what they need.
## Reference Assets
@@ -360,4 +361,5 @@ These capsules distil Murat's sample repositories (Playwright patterns, Cypress
- [Test Levels Framework](./test-levels-framework.md) — choose the right level for each scenario.
- [Test Priorities Matrix](./test-priorities-matrix.md) — assign P0–P3 priorities consistently.
- [TEA Workflows](../workflows/testarch/README.md) — per-command instructions executed by the agent.
-- [Murat Knowledge Bundle](./test-resources-for-ai-flat.txt) — 347 KB flattened snapshot of Murat’s blogs, philosophy notes, and course material. Sections are delimited with `FILE:` headers; load relevant portions when deeper examples or rationales are required.
+- [TEA Knowledge Index](./tea-index.csv) — tags each knowledge fragment and the supporting markdown file under `knowledge/` for on-demand loading.
+- [Murat Knowledge Bundle](./test-resources-for-ai-flat.txt) — raw 347 KB archive of blogs and course notes; consult manually when a fragment needs deeper sourcing.
diff --git a/src/modules/bmm/workflows/testarch/atdd/instructions.md b/src/modules/bmm/workflows/testarch/atdd/instructions.md
index c5d0355a..cede9c23 100644
--- a/src/modules/bmm/workflows/testarch/atdd/instructions.md
+++ b/src/modules/bmm/workflows/testarch/atdd/instructions.md
@@ -33,6 +33,7 @@
Reference `{project-root}/bmad/bmm/testarch/tea-knowledge.md` for heuristics that shape this guidance.
+ Consult `{project-root}/bmad/bmm/testarch/tea-index.csv` to load only the relevant knowledge fragments under `knowledge/`.
Start red; one assertion per test; keep setup visible (no hidden shared state).
Remind devs to run tests before writing production code; update checklist as tests turn green.
diff --git a/src/modules/bmm/workflows/testarch/automate/instructions.md b/src/modules/bmm/workflows/testarch/automate/instructions.md
index cd1aae95..70cfce47 100644
--- a/src/modules/bmm/workflows/testarch/automate/instructions.md
+++ b/src/modules/bmm/workflows/testarch/automate/instructions.md
@@ -17,6 +17,7 @@
Review story source/diff to confirm automation targets.
Review quality heuristics from `{project-root}/bmad/bmm/testarch/tea-knowledge.md` before proposing additions.
+ Use `{project-root}/bmad/bmm/testarch/tea-index.csv` to pull supporting fragments from `knowledge/` as needed.
Ensure fixture architecture exists (Playwright `mergeTests`, Cypress commands); add apiRequest/network/auth/log fixtures if missing.
Map acceptance criteria using `{project-root}/bmad/bmm/testarch/test-levels-framework.md` and avoid duplicate coverage.
Assign priorities using `{project-root}/bmad/bmm/testarch/test-priorities-matrix.md`.
@@ -35,6 +36,7 @@
Never create page objects; keep tests under 300 lines and stateless.
Forbid hard waits/conditional flow; co-locate tests near source.
Flag flaky patterns immediately.
+ Reference `tea-index.csv` tags (e.g., fixture-architecture, selective-testing, ci-burn-in) to load the right fragment instead of the entire knowledge bundle.
Consult `{project-root}/bmad/bmm/testarch/tea-knowledge.md` for the latest risk heuristics before scoring.
+ Use `{project-root}/bmad/bmm/testarch/tea-index.csv` to pull targeted fragments (risk heuristics, fixture guidance, etc.) from `knowledge/` as needed.
Filter requirements to isolate genuine risks; review PRD/architecture/story for unresolved gaps.
Classify risks across TECH, SEC, PERF, DATA, BUS, OPS; request clarification when evidence is missing.
Score probability (1 unlikely, 2 possible, 3 likely) and impact (1 minor, 2 degraded, 3 critical); compute totals and highlight scores ≥6.
@@ -34,6 +35,7 @@
Category definitions: TECH=architecture flaws; SEC=missing controls; PERF=SLA risk; DATA=loss/corruption; BUS=user/business harm; OPS=deployment/run failures.
+ Leverage `tea-index.csv` tags to find supporting evidence (e.g., fixture-architecture, selective-testing) without loading unnecessary files.
Rely on evidence, not speculation; tie scenarios back to mitigations; keep scenarios independent and maintainable.