docs: addressed review comments

docs/explanation/tea/fixture-architecture.md

@@ -21,7 +21,7 @@ Fixture architecture is TEA's pattern for building reusable, testable, and compo
 - Composition happens at fixture level
 - Reusability maximized
 
-#### Fixture Architecture Flow
+### Fixture Architecture Flow
 
 ```mermaid
 %%{init: {'theme':'base', 'themeVariables': { 'fontSize':'14px'}}}%%
@@ -217,11 +217,11 @@ import { test, expect } from '../support/fixtures';
 test('should update profile', async ({ apiRequest, authToken, log }) => {
   log.info('Starting profile update test');
 
-  // Use API request fixture with auth token
+  // Use API request fixture (matches pure function signature)
   const { status, body } = await apiRequest({
     method: 'PATCH',
-    path: '/api/profile',
+    url: '/api/profile',  // Pure function uses 'url' (not 'path')
-    body: { name: 'New Name' },  // 'body' not 'data'
+    data: { name: 'New Name' },  // Pure function uses 'data' (not 'body')
     headers: { Authorization: `Bearer ${authToken}` }
   });
 
@@ -232,6 +232,8 @@ test('should update profile', async ({ apiRequest, authToken, log }) => {
 });
 ```
 
+**Note:** This example uses the vanilla pure function signature (`url`, `data`). Playwright Utils uses different parameter names (`path`, `body`). See [Integrate Playwright Utils](/docs/how-to/customization/integrate-playwright-utils.md) for the utilities API.
+
 **Note:** `authToken` requires auth-session fixture setup with provider configuration. See [auth-session documentation](https://seontechnologies.github.io/playwright-utils/auth-session.html).
 
 **Benefits:**

docs/explanation/tea/knowledge-base-system.md

@@ -203,6 +203,7 @@ Benefits it provides
 - [Link to related fragment]
 ```
 
+<!-- markdownlint-disable MD024 -->
 ### Example: test-quality.md Fragment
 
 ```markdown
@@ -246,6 +247,7 @@ await page.waitForTimeout(3000);
 ```
 
 **Total:** 24.5 KB, 12 code examples
+<!-- markdownlint-enable MD024 -->
 
 ## How TEA Uses the Knowledge Base
 

docs/explanation/tea/network-first-patterns.md

@@ -324,21 +324,30 @@ await expect(page.locator('.order-confirmation')).toContainText(order.id);
 ### HAR Recording for Offline Testing
 
 **Vanilla Playwright (Manual HAR Handling):**
+
 ```typescript
-test('offline testing', async ({ page, context }) => {
+// First run: Record mode (saves HAR file)
-  // Record mode: Save HAR manually
+test('offline testing - RECORD', async ({ page, context }) => {
+  // Record mode: Save network traffic to HAR
   await context.routeFromHAR('./hars/dashboard.har', {
     url: '**/api/**',
     update: true  // Update HAR file
   });
 
   await page.goto('/dashboard');
+  // All network traffic saved to dashboard.har
+});
 
-  // Playback: Load HAR manually
+// Subsequent runs: Playback mode (uses saved HAR)
+test('offline testing - PLAYBACK', async ({ page, context }) => {
+  // Playback mode: Use saved network traffic
   await context.routeFromHAR('./hars/dashboard.har', {
     url: '**/api/**',
-    update: false  // Use existing HAR
+    update: false  // Use existing HAR, no network calls
   });
+
+  await page.goto('/dashboard');
+  // Uses recorded responses, no backend needed
 });
 ```
 

docs/explanation/tea/risk-based-testing.md

@@ -577,7 +577,7 @@ flowchart TD
 
 ## Reference
 
-- [TEA Command Reference](/docs/reference/tea/commands.md) - *test-design, *nfr-assess, *trace
+- [TEA Command Reference](/docs/reference/tea/commands.md) - `*test-design`, `*nfr-assess`, `*trace`
 - [Knowledge Base Index](/docs/reference/tea/knowledge-base.md) - Risk governance fragments
 - [Glossary](/docs/reference/glossary/index.md#test-architect-tea-concepts) - Risk-based testing term
 

docs/explanation/tea/test-quality-standards.md

@@ -53,9 +53,9 @@ test('user can do stuff', async ({ page }) => {
 
 **Result:** PR review comments: "This test is flaky, please fix" → never merged → test deleted → coverage lost
 
-### The Slop Factory
+### AI-Generated Tests Without Standards
 
-AI-generated tests without quality standards:
+AI-generated tests without quality guardrails:
 
 ```typescript
 // AI generates 50 tests like this:
@@ -74,7 +74,7 @@ test('test2', async ({ page }) => {
 // ... 48 more similar tests
 ```
 
-**Result:** 50 tests, 80% redundant, 90% flaky, 0% trusted by team.
+**Result:** 50 tests, 80% redundant, 90% flaky, 0% trusted by team - low-quality outputs that create maintenance burden.
 
 ## The Solution: TEA's Quality Standards
 
@@ -524,13 +524,13 @@ flowchart LR
 
 ### Score Interpretation
 
-| Score | Interpretation | Action |
+| Score      | Interpretation | Action                                 |
-|-------|----------------|--------|
+| ---------- | -------------- | -------------------------------------- |
-| **90-100** | Excellent | Production-ready, minimal changes |
+| **90-100** | Excellent      | Production-ready, minimal changes      |
-| **80-89** | Good | Minor improvements recommended |
+| **80-89**  | Good           | Minor improvements recommended         |
-| **70-79** | Acceptable | Address recommendations before release |
+| **70-79**  | Acceptable     | Address recommendations before release |
-| **60-69** | Needs Work | Fix critical issues |
+| **60-69**  | Needs Work     | Fix critical issues                    |
-| **< 60** | Critical | Significant refactoring needed |
+| **< 60**   | Critical       | Significant refactoring needed         |
 
 ## Comparison: Good vs Bad Tests
 
@@ -633,7 +633,7 @@ test('should create user with valid data', async ({ apiRequest }) => {
   const { status, body } = await apiRequest({
     method: 'POST',
     path: '/api/users',
-    data: { email: testEmail, name: 'Test User' }
+    body: { email: testEmail, name: 'Test User' }
   });
 
   // Explicit assertions
@@ -652,7 +652,7 @@ test('should create user with valid data', async ({ apiRequest }) => {
 
 ## How TEA Enforces Standards
 
-### During Test Generation (*atdd, *automate)
+### During Test Generation (`*atdd`, `*automate`)
 
 TEA generates tests following standards by default:
 

docs/how-to/customization/integrate-playwright-utils.md

@@ -20,7 +20,7 @@ A production-ready utility library that provides:
 - Burn-in testing utilities
 - Network error monitoring
 
-**Repository:** https://github.com/seontechnologies/playwright-utils
+**Repository:** [https://github.com/seontechnologies/playwright-utils](https://github.com/seontechnologies/playwright-utils)
 
 **npm Package:** `@seontechnologies/playwright-utils`
 
@@ -133,7 +133,7 @@ test('api test', async ({ apiRequest, log }) => {
 });
 ```
 
-### *atdd and *automate Workflows
+### `*atdd` and `*automate` Workflows
 
 **Without Playwright Utils:**
 ```typescript

docs/how-to/workflows/run-atdd.md

@@ -90,7 +90,9 @@ TEA will ask what test levels to generate:
 - E2E tests (browser-based, full user journey)
 - API tests (backend only, faster)
 - Component tests (UI components in isolation)
-- Mix of levels (recommended)
+- Mix of levels
+
+**Recommended approach:** Generate API tests first, then E2E tests (see [API Tests First, E2E Later](#api-tests-first-e2e-later) tip below).
 
 ### Component Testing by Framework
 
@@ -398,16 +400,18 @@ Run `*test-design` before `*atdd` for better results:
 *atdd          # Generate tests based on design
 ```
 
-### Use Recording Mode (Optional)
+### Recording Mode Note
 
-If MCP enhancements are enabled (`tea_use_mcp_enhancements: true` in config):
+**Recording mode is NOT typically used with ATDD** because ATDD generates tests for features that don't exist yet (no UI to record against).
 
-When prompted during `*atdd`, select "recording mode" to:
+If you have a skeleton UI or are refining existing tests, use `*automate` with recording mode instead. See [How to Run Automate](/docs/how-to/workflows/run-automate.md).
-- Verify selectors against actual UI with live browser
-- Capture network requests in real-time
-- Generate accurate locators from actual DOM
 
-See [Enable MCP Enhancements](/docs/how-to/customization/enable-tea-mcp-enhancements.md)
+**Recording mode is only applicable for ATDD in the rare case where:**
+- You have skeleton/mockup UI already implemented
+- You want to verify selector patterns before full implementation
+- You're doing "UI-first" development (unusual for TDD)
+
+For most ATDD workflows, **skip recording mode** - TEA will infer selectors from best practices.
 
 ### Focus on P0/P1 Scenarios
 

docs/how-to/workflows/run-nfr-assess.md

@@ -285,7 +285,7 @@ scenarios: (100.00%) 1 scenario, 500 max VUs, 10m30s max duration
 
 **APM Data:**
 - Tool: Datadog
-- Dashboard: https://app.datadoghq.com/dashboard/abc123
+- Dashboard: <https://app.datadoghq.com/dashboard/abc123>
 
 **Conclusion:** Performance issues identified with mitigation plan. Re-assess after optimization.
 

docs/reference/glossary/index.md

@@ -9,7 +9,7 @@ Terminology reference for the BMad Method.
 | Term                      | Definition                                                                                                                                                                        |
 | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Agent**                 | Specialized AI persona with specific expertise (PM, Architect, SM, DEV, TEA) that guides users through workflows and creates deliverables.                                        |
-| **BMad**                  | Breakthrough Method of Agile AI Driven Development — AI-driven agile framework with specialized agents, guided workflows, and scale-adaptive intelligence.                        |
+| **BMad**                  | Breakthrough Method of Agile AI-Driven Development — AI-driven agile framework with specialized agents, guided workflows, and scale-adaptive intelligence.                        |
 | **BMad Method**           | Complete methodology for AI-assisted software development, encompassing planning, architecture, implementation, and quality assurance workflows that adapt to project complexity. |
 | **BMM**                   | BMad Method Module — core orchestration system providing comprehensive lifecycle management through specialized agents and workflows.                                             |
 | **Scale-Adaptive System** | Intelligent workflow orchestration that adjusts planning depth and documentation requirements based on project needs through three planning tracks.                               |

docs/reference/tea/commands.md

@@ -591,16 +591,18 @@ test('should display profile page', async ({ page }) => {
 });
 ```
 
-### Optional: Recording Mode
+### Recording Mode Note
 
-If MCP enhancements enabled (`tea_use_mcp_enhancements: true` in config):
+**Recording mode is NOT typically used with ATDD** because ATDD generates tests for features that don't exist yet.
 
-When prompted, select "recording mode" to:
+Use `*automate` with recording mode for existing features instead. See [`*automate`](#automate).
-- Verify selectors against actual UI with live browser
-- Capture network requests in real-time
-- Generate accurate locators from actual DOM
 
-Note: Recording mode assumes feature partially exists (use for refinement).
+**Only use recording mode with ATDD if:**
+- You have skeleton/mockup UI implemented
+- You want to verify selectors before full implementation
+- You're doing UI-first development (rare for TDD)
+
+For typical ATDD (feature doesn't exist), skip recording mode.
 
 ### TDD Workflow
 

docs/reference/tea/knowledge-base.md

@@ -60,7 +60,7 @@ Core patterns for test infrastructure and fixture composition.
 | [playwright-config](../../../src/modules/bmm/testarch/knowledge/playwright-config.md) | Environment switching, timeout standards, artifact outputs | Configuration, environments, CI |
 | [fixtures-composition](../../../src/modules/bmm/testarch/knowledge/fixtures-composition.md) | mergeTests composition patterns for combining utilities | Fixture merging, utility composition |
 
-**Used in:** *framework, *test-design, *atdd, *automate, *test-review
+**Used in:** `*framework`, `*test-design`, `*atdd`, `*automate`, `*test-review`
 
 ---
 
@@ -74,7 +74,7 @@ Patterns for test data generation, authentication, and setup.
 | [email-auth](../../../src/modules/bmm/testarch/knowledge/email-auth.md) | Magic link extraction, state preservation, negative flows | Authentication, email testing |
 | [auth-session](../../../src/modules/bmm/testarch/knowledge/auth-session.md) | Token persistence, multi-user, API/browser authentication | Auth patterns, session management |
 
-**Used in:** *framework, *atdd, *automate, *test-review
+**Used in:** `*framework`, `*atdd`, `*automate`, `*test-review`
 
 ---
 
@@ -89,7 +89,7 @@ Network interception, error handling, and reliability patterns.
 | [error-handling](../../../src/modules/bmm/testarch/knowledge/error-handling.md) | Scoped exception handling, retry validation, telemetry logging | Error patterns, resilience |
 | [network-error-monitor](../../../src/modules/bmm/testarch/knowledge/network-error-monitor.md) | HTTP 4xx/5xx detection for UI tests | Error detection, monitoring |
 
-**Used in:** *atdd, *automate, *test-review
+**Used in:** `*atdd`, `*automate`, `*test-review`
 
 ---
 
@@ -103,7 +103,7 @@ CI/CD patterns, burn-in testing, and selective test execution.
 | [burn-in](../../../src/modules/bmm/testarch/knowledge/burn-in.md) | Smart test selection, git diff for CI optimization | Test selection, performance |
 | [selective-testing](../../../src/modules/bmm/testarch/knowledge/selective-testing.md) | Tag/grep usage, spec filters, diff-based runs | Test filtering, optimization |
 
-**Used in:** *ci, *test-review
+**Used in:** `*ci`, `*test-review`
 
 ---
 
@@ -119,7 +119,7 @@ Test quality standards, test level selection, and TDD patterns.
 | [test-healing-patterns](../../../src/modules/bmm/testarch/knowledge/test-healing-patterns.md) | Common failure patterns and automated fixes | Debugging, healing, fixes |
 | [component-tdd](../../../src/modules/bmm/testarch/knowledge/component-tdd.md) | Red→green→refactor workflow, provider isolation | TDD, component testing |
 
-**Used in:** *test-design, *atdd, *automate, *test-review, *trace
+**Used in:** `*test-design`, `*atdd`, `*automate`, `*test-review`, `*trace`
 
 ---
 
@@ -133,7 +133,7 @@ Risk assessment, governance, and gate decision frameworks.
 | [probability-impact](../../../src/modules/bmm/testarch/knowledge/probability-impact.md) | Probability × impact scale for scoring matrix | Risk scoring, impact analysis |
 | [nfr-criteria](../../../src/modules/bmm/testarch/knowledge/nfr-criteria.md) | Security, performance, reliability, maintainability status | NFRs, compliance, enterprise |
 
-**Used in:** *test-design, *nfr-assess, *trace
+**Used in:** `*test-design`, `*nfr-assess`, `*trace`
 
 ---
 
@@ -147,7 +147,7 @@ Selector resilience, race condition debugging, and visual debugging.
 | [timing-debugging](../../../src/modules/bmm/testarch/knowledge/timing-debugging.md) | Race condition identification and deterministic fixes | Race conditions, timing issues |
 | [visual-debugging](../../../src/modules/bmm/testarch/knowledge/visual-debugging.md) | Trace viewer usage, artifact expectations | Debugging, trace viewer, artifacts |
 
-**Used in:** *atdd, *automate, *test-review
+**Used in:** `*atdd`, `*automate`, `*test-review`
 
 ---
 
@@ -161,7 +161,7 @@ Feature flag testing, contract testing, and API testing patterns.
 | [contract-testing](../../../src/modules/bmm/testarch/knowledge/contract-testing.md) | Pact publishing, provider verification, resilience | Contract testing, Pact |
 | [api-testing-patterns](../../../src/modules/bmm/testarch/knowledge/api-testing-patterns.md) | Pure API patterns without browser | API testing, backend testing |
 
-**Used in:** *test-design, *atdd, *automate
+**Used in:** `*test-design`, `*atdd`, `*automate`
 
 ---
 
@@ -185,9 +185,9 @@ Patterns for using `@seontechnologies/playwright-utils` package (11 utilities).
 
 **Note:** All 11 playwright-utils fragments are in the same `knowledge/` directory as other fragments.
 
-**Used in:** *framework (if `tea_use_playwright_utils: true`), *atdd, *automate, *test-review, *ci
+**Used in:** `*framework` (if `tea_use_playwright_utils: true`), `*atdd`, `*automate`, `*test-review`, `*ci`
 
-**Official Docs:** https://seontechnologies.github.io/playwright-utils/
+**Official Docs:** <https://seontechnologies.github.io/playwright-utils/>
 
 ---
 

docs/tutorials/getting-started/tea-lite-quickstart.md

@@ -18,7 +18,7 @@ By the end of this 30-minute tutorial, you'll have:
 
 - Node.js installed (v18 or later)
 - 30 minutes of focused time
-- We'll use TodoMVC (https://todomvc.com/examples/react/) as our demo app
+- We'll use TodoMVC (<https://todomvc.com/examples/react/>) as our demo app
 
 ## TEA Approaches Explained
 
@@ -36,7 +36,7 @@ This tutorial focuses on **TEA Lite** - the fastest way to see TEA in action.
 
 We'll test TodoMVC, a standard demo app used across testing documentation.
 
-**Demo App:** https://todomvc.com/examples/react/
+**Demo App:** <https://todomvc.com/examples/react/>
 
 No installation needed - TodoMVC runs in your browser. Open the link above and:
 1. Add a few todos (type and press Enter)
@@ -173,7 +173,7 @@ In your chat with TEA, run:
 ```
 
 **Q: What are you testing?**
-A: "TodoMVC React app at https://todomvc.com/examples/react/ - focus on the test design we just created"
+A: "TodoMVC React app at <https://todomvc.com/examples/react/> - focus on the test design we just created"
 
 **Q: Reference existing docs?**
 A: "Yes, use test-design-epic-1.md"
@@ -452,8 +452,8 @@ use: {
 
 ### Need Help?
 
-- **Documentation:** https://docs.bmad-method.org
+- **Documentation:** <https://docs.bmad-method.org>
-- **GitHub Issues:** https://github.com/bmad-code-org/bmad-method/issues
+- **GitHub Issues:** <https://github.com/bmad-code-org/bmad-method/issues>
 - **Discord:** Join the BMAD community
 
 ---

package-lock.json

@@ -244,7 +244,6 @@
       "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.27.1",
         "@babel/generator": "^7.28.5",
@@ -3643,7 +3642,6 @@
       "integrity": "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~7.16.0"
       }
@@ -3983,7 +3981,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -4290,7 +4287,6 @@
       "integrity": "sha512-6mF/YrvwwRxLTu+aMEa5pwzKUNl5ZetWbTyZCs9Um0F12HUmxUiF5UHiZPy4rifzU3gtpM3xP2DfdmkNX9eZRg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@astrojs/compiler": "^2.13.0",
         "@astrojs/internal-helpers": "0.7.5",
@@ -5358,7 +5354,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -6689,7 +6684,6 @@
       "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -10304,7 +10298,6 @@
       "integrity": "sha512-p3JTemJJbkiMjXEMiFwgm0v6ym5g8K+b2oDny+6xdl300tUKySxvilJQLSea48C6OaYNmO30kH9KxpiAg5bWJw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "globby": "15.0.0",
         "js-yaml": "4.1.1",
@@ -12378,7 +12371,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -12444,7 +12436,6 @@
       "integrity": "sha512-v6UNi1+3hSlVvv8fSaoUbggEM5VErKmmpGA7Pl3HF8V6uKY7rvClBOJlH6yNwQtfTueNkGVpOv/mtWL9L4bgRA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -13273,7 +13264,6 @@
       "integrity": "sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/estree": "1.0.8"
       },
@@ -14837,7 +14827,6 @@
       "integrity": "sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.25.0",
         "fdir": "^6.4.4",
@@ -15111,7 +15100,6 @@
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
       "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
       "license": "ISC",
-      "peer": true,
       "bin": {
         "yaml": "bin.mjs"
       },
@@ -15303,7 +15291,6 @@
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package.json

@@ -34,6 +34,7 @@
     "flatten": "node tools/flattener/main.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "format:fix:staged": "prettier --write",
     "install:bmad": "node tools/cli/bmad-cli.js install",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
@@ -53,14 +54,14 @@
   "lint-staged": {
     "*.{js,cjs,mjs}": [
       "npm run lint:fix",
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.yaml": [
       "eslint --fix",
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.json": [
-      "npm run format:fix"
+      "npm run format:fix:staged"
     ],
     "*.md": [
       "markdownlint-cli2"