froid-plane-test-architecture-enterprise 1.23.4

package/docs/reference/troubleshooting.md

@@ -0,0 +1,362 @@
+---
+title: Troubleshooting Guide
+description: Diagnose and resolve common issues when using TEA
+---
+
+# Troubleshooting Guide
+
+## Installation Issues
+
+### TEA Module Not Found After Installation
+
+**Symptom**: after `npx froid-plane install`, the TEA agent is not available.
+
+**Cause**: TEA was not selected at the module prompt, or the install failed silently and `_froid/tea/` was never created.
+
+```bash
+ls -la _froid/tea/                 # should show agents/, workflows/, config.yaml
+npx froid-plane install           # select "Test Architect (TEA)" at the module prompt
+npx froid-plane install --debug   # if it fails again, this surfaces the installer error
+```
+
+### Module Installation Hangs
+
+**Symptom**: the installer hangs or times out.
+
+**Cause**: network connectivity, an npm registry timeout, or no disk space.
+
+```bash
+ping registry.npmjs.org
+df -h                                              # installs need room for the module tree
+npm cache clean --force && npx froid-plane install # retry on a clean cache
+npm config set registry https://registry.npmjs.org/ # if a proxy rewrote the registry
+```
+
+### Installer Cannot Reach GitHub
+
+The installer starts but cannot fetch the Test Architect module. See [Install TEA Behind a Corporate Firewall](/how-to/install-behind-firewall/).
+
+## Agent Loading Issues
+
+### "Agent Not Found" Error
+
+**Symptom**: `Error: Agent '_froid/tea' not found` or `Agent 'tea' could not be loaded`.
+
+**Cause**: TEA is not installed, or the install is incomplete.
+
+```bash
+ls -la _froid/tea/agents/froid-tea/SKILL.md   # the agent entrypoint
+```
+
+If the file is missing or the tree looks partial, [reset TEA to a fresh state](#reset-tea-to-a-fresh-state).
+
+### TEA Loads But Commands Don't Work
+
+**Symptom**: the TEA agent loads, but workflow codes (TF, TD, AT, and the rest) do not execute.
+
+**Cause**: workflow directories are missing from the install.
+
+```bash
+ls _froid/tea/workflows/testarch/   # all nine must be present
+# froid-teach-me-testing   froid-testarch-framework   froid-testarch-test-design
+# froid-testarch-atdd      froid-testarch-nfr         froid-testarch-test-review
+# froid-testarch-automate  froid-testarch-ci          froid-testarch-trace
+```
+
+Then invoke the workflow by its skill name instead of the two-letter code:
+
+```text
+/froid-testarch-test-design    # Claude Code, Cursor, Windsurf
+$froid-testarch-test-design    # Codex
+```
+
+If a directory is missing, [reset TEA to a fresh state](#reset-tea-to-a-fresh-state).
+
+### Custom TEA Workflow Does Not Appear
+
+**Symptom**: a custom workflow that used to appear in the `froid-tea` menu is gone after an update.
+
+**Cause**: TEA is a standalone module. Custom workflows are not merged into TEA core automatically.
+
+**Fix**: package the workflow as custom content or a custom module, attach it to `froid-tea` through the generated customization file under `_froid/_config/agents/`, then re-run `npx froid-plane install` so the customization and workflow registration are refreshed. See [Extend TEA with Custom Workflows](../how-to/customization/extend-tea-with-custom-workflows.md).
+
+## Workflow Execution Issues
+
+### GitHub Copilot Slash Command Fails with "No such file or directory"
+
+**Symptom**: a workflow launched through GitHub Copilot in VS Code fails with an error such as `can't open file 'C:\path\to\workspace\scripts\resolve_customization.py': [Errno 2] No such file or directory`.
+
+**Cause**: GitHub Copilot runs skill commands from the workspace root rather than from the installed skill folder under `.github/skills/`, so a path written relative to the skill does not resolve.
+
+**Fix**: shipped TEA workflows already anchor every path with `{skill-root}` or `{project-root}`. If you hit this in a workflow you wrote, apply the same anchoring; see [Extend TEA with Custom Workflows](../how-to/customization/extend-tea-with-custom-workflows.md).
+
+### Workflow Starts But Produces No Output
+
+**Symptom**: the workflow runs but generates no test designs, reports, or tests.
+
+**Cause**: the output directory is missing or not writable, `test_artifacts` is misconfigured, or the run stopped before its output step.
+
+```bash
+grep test_artifacts _froid/tea/config.yaml   # default: _froid-output/test-artifacts
+mkdir -p _froid-output/test-artifacts
+chmod -R u+w _froid-output/test-artifacts
+```
+
+If the directory is correct and writable, read the agent's final message for a completion line such as `✓ Test design complete`. When a run stops early, the last step it names is where to look.
+
+### Subagent Fails to Execute
+
+**Symptom**: the workflow reports a subagent failure, for example "API test generation subagent failed".
+
+**Cause**: a subagent step file is missing, `/tmp` is not writable, the subagent returned an unparseable payload, or the runtime cannot launch parallel workers.
+
+```bash
+# 1. The subagent step files must exist
+ls _froid/tea/workflows/testarch/froid-testarch-automate/steps-c/step-03*.md
+# step-03-generate-tests.md plus step-03a-*, step-03b-*, step-03c-aggregate.md
+
+# 2. Workers hand off through one JSON file per suite in /tmp
+ls /tmp | grep '^tea-'
+# e.g. tea-automate-api-tests-1763049600.json, tea-automate-e2e-tests-1763049600.json
+
+# 3. Check which orchestration mode was selected
+grep -E "tea_execution_mode|tea_capability_probe" _froid/tea/config.yaml
+```
+
+If the runtime cannot launch parallel workers, force the deterministic path in `_froid/tea/config.yaml`:
+
+```yaml
+tea_execution_mode: 'sequential'
+tea_capability_probe: true
+```
+
+### Knowledge Fragments Not Loading
+
+**Symptom**: the workflow runs but never references knowledge base patterns such as `test-quality` or `network-first`.
+
+**Cause**: `tea-index.csv` is missing or truncated, or fragment files are missing.
+
+```bash
+wc -l < _froid/tea/agents/froid-tea/resources/tea-index.csv   # 60 (header + 59 fragments)
+ls _froid/tea/agents/froid-tea/resources/knowledge/*.md | wc -l   # 59
+head -1 _froid/tea/agents/froid-tea/resources/tea-index.csv
+# id,name,description,tags,tier,fragment_file
+
+# Workflows load knowledge through a `knowledgeIndex` key in step-file frontmatter,
+# so workflow.yaml never mentions fragments
+grep -r knowledgeIndex _froid/tea/workflows/testarch/froid-testarch-test-design/steps-c/
+# knowledgeIndex: './resources/tea-index.csv'
+```
+
+## Configuration Issues
+
+### Variables Not Prompting During Installation
+
+**Symptom**: installation completes without asking for TEA configuration (`test_artifacts`, Playwright Utils, and the rest).
+
+**Cause**: the installer ran with `-y`/`--yes`, which accepts defaults and skips prompts.
+
+```bash
+npx froid-plane install                    # prompting is the default; omit --yes
+npx froid-plane install --list-options tea # every key and its allowed values
+npx froid-plane install --set tea.test_artifacts=_froid-output/test-artifacts
+vi _froid/tea/config.yaml                   # or edit the installed values directly
+```
+
+### Config Values Ignored
+
+**Symptom**: TEA uses defaults instead of the values in `config.yaml`, or keeps using old values after you edited the file.
+
+**Cause**: the file is in the wrong place, the YAML does not parse, a key is misspelled, or the chat started before the edit. TEA reads config once at workflow start and does not reload mid-chat.
+
+```bash
+ls -la _froid/tea/config.yaml              # must be at the project root, under _froid/tea/
+npx --yes js-yaml _froid/tea/config.yaml   # prints the parsed object, or the syntax error
+```
+
+If it parses and the key name matches [Configuration](/reference/configuration/), save the file, start a fresh chat, and re-run the workflow.
+
+### Playwright Utils Integration Not Working
+
+**Symptom**: workflows produce no Playwright Utils references even though `tea_use_playwright_utils` is enabled.
+
+```bash
+grep tea_use_playwright_utils _froid/tea/config.yaml   # should show: true
+grep -ic playwright-utils _froid/tea/agents/froid-tea/resources/tea-index.csv   # 21
+npm ls @seontechnologies/playwright-utils              # the package must actually be installed
+```
+
+Confirm the workflow integrates Playwright Utils at all. Framework (TF), Test Design (TD), ATDD (AT), Automate (TA), Test Review (RV), and CI all do. Trace and NFR Evidence Audit do not.
+
+The same three checks apply to Pact.js Utils, which is also on by default: `grep tea_use_pactjs_utils _froid/tea/config.yaml`, `npm ls @seontechnologies/pactjs-utils`, and `ls _froid/tea/agents/froid-tea/resources/knowledge/pactjs-utils-mandate.md`.
+
+**If a flag is `true` and its package is missing**, that is the usual cause, and it applies to both integrations independently: `tea_use_playwright_utils` needs `@seontechnologies/playwright-utils`, `tea_use_pactjs_utils` needs `@seontechnologies/pactjs-utils`. Either one can be active while the other is not. Generation will not scaffold imports against a package the project does not have, and Test Review closes the `M9` gate rather than deducting. Run the Framework (TF) workflow, or install it directly:
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**If the package is installed and output is still vanilla**, the mandate fragment did not load. Check that `playwright-utils-mandate.md` is present next to the other fragments and indexed in `tea-index.csv`:
+
+```bash
+ls _froid/tea/agents/froid-tea/resources/knowledge/playwright-utils-mandate.md
+grep playwright-utils-mandate _froid/tea/agents/froid-tea/resources/tea-index.csv
+```
+
+Then start a fresh chat: fragment selection happens at step 01, so a run that already loaded the vanilla profile keeps it for the rest of the run.
+
+## Output and File Issues
+
+### Test Files Generated in Wrong Location
+
+**Symptom**: test files are created in an unexpected directory.
+
+**Cause**: `test_artifacts` resolves against the project root, so a misconfigured value or a shell sitting in a subdirectory moves the target.
+
+```bash
+grep test_artifacts _froid/tea/config.yaml   # default: _froid-output/test-artifacts
+                                            # edit config.yaml to change it
+pwd                                         # must be the project root
+```
+
+### Generated Tests Have Syntax Errors
+
+**Symptom**: TEA generates tests with JavaScript or TypeScript syntax errors.
+
+**Cause**: a framework mismatch, usually Playwright syntax emitted for a Cypress project or the reverse.
+
+**Fix**: name the framework and language explicitly in the prompt, for example "Generate Playwright tests using TypeScript", then lint what came back:
+
+```bash
+npx eslint tests/**/*.spec.ts
+```
+
+### File Permission Errors
+
+**Symptom**: `EACCES: permission denied` when writing files.
+
+**Cause**: the target directory is not writable, is owned by another user, or the disk is full.
+
+```bash
+ls -la _froid-output/test-artifacts
+chmod -R u+w _froid-output/test-artifacts
+df -h
+```
+
+## Integration Issues
+
+### Playwright Utils Not Found
+
+**Symptom**: tests reference Playwright Utils but the imports fail.
+
+```bash
+npm install @seontechnologies/playwright-utils
+npm ls @seontechnologies/playwright-utils   # confirms the resolved version
+```
+
+Generated tests import each fixture from its own module subpath, and `expect` from Playwright:
+
+```typescript
+import { expect } from '@playwright/test';
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+```
+
+### Pact MCP Reports the Broker as Unreachable
+
+**Symptom**: a workflow says the broker was unreachable and fell back to provider source or an OpenAPI spec.
+
+**Cause**: `tea_pact_mcp` defaults to `"mcp"`, so TEA probes for the SmartBear MCP tools on any contract-testing step. Without a broker, that probe fails and the workflow degrades on purpose.
+
+**This is not an error.** The run completed; it just used a lower-authority source for provider states. To silence the probe entirely:
+
+```yaml
+tea_pact_mcp: 'none'
+```
+
+To make the probe succeed instead, configure the server and its credentials:
+
+```bash
+npm install -g @smartbear/mcp    # Node.js 20+ required
+```
+
+Installing the server is not enough: the MCP client has to be told about it, since the probe checks the session's tool list. For Claude Code:
+
+```bash
+claude mcp add-json -s user smartbear '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-api-token>"}}'
+```
+
+Other clients take the same server in their own MCP settings file. Restart the session afterwards; the tool list is read at startup.
+
+TEA never blocks on the broker and never presents inferred provider states as broker data, so a failed probe cannot silently corrupt a contract.
+
+### Browser Automation Not Working
+
+**Symptom**: `tea_browser_automation` is set to `auto`, `cli`, or `mcp`, but outputs contain no browser features.
+
+**Cause**: for `cli` or `auto`, the CLI is not installed globally. For `mcp` or `auto`, the MCP server is not configured in the IDE.
+
+```bash
+playwright-cli --version                          # cli mode; install: npm i -g @playwright/cli@latest
+npx playwright install                            # both modes need the browser binaries
+npx @playwright/mcp@latest --version              # mcp mode; confirms the server is reachable
+grep tea_browser_automation _froid/tea/config.yaml # confirm the mode you think you set
+```
+
+For MCP mode, add the server to your tool's MCP config, then restart the IDE:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+See [Configure Browser Automation: MCP Setup](/docs/how-to/customization/configure-browser-automation.md#for-mcp-mcp-or-auto-mode) for the exact config file path for your tool (Claude Code, Codex, Gemini CLI, Cursor, Windsurf).
+
+## Performance Issues
+
+### Workflows Taking Too Long
+
+**Symptom**: a workflow runs for several minutes without completing.
+
+**Cause**: a large codebase to explore, many test files to review, or subagent overhead.
+
+**Fix**: scope the run to a directory instead of the whole suite, for example "Review tests in tests/e2e/checkout/" rather than "review all tests". Use `automate` for targeted generation and `test-review` on specific files. Check `top` for CPU and memory pressure.
+
+The first workflow run in a session loads knowledge fragments from disk and is slower than later runs. That is expected.
+
+## Getting Help
+
+### Reset TEA to a Fresh State
+
+This clears a partial or corrupted install and is the fallback for every "missing file" symptom above.
+
+```bash
+cp _froid/tea/config.yaml /tmp/tea-config-backup.yaml   # back up your answers first
+rm -rf _froid/tea/
+npx froid-plane install                                # select "Test Architect (TEA)"
+cp /tmp/tea-config-backup.yaml _froid/tea/config.yaml   # only if the prompts lost a value
+```
+
+### Collecting Diagnostic Information
+
+Include all of this when reporting an issue, plus the full error message and the exact commands that trigger it:
+
+```bash
+npx froid-plane status                                # FROID and module versions
+grep -A6 'test-architecture' _froid/_config/manifest.yaml   # TEA channel and sha
+node --version
+uname -a
+tree -L 2 _froid/tea/
+```
+
+### Support Channels
+
+- **Documentation**: [TEA documentation](https://cordya-ai.github.io/froid-plane-test-architecture-enterprise/)
+- **Bug reports**: [Open an issue](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/issues/new?template=issue.md)
+- **Questions**: [search existing issues](https://github.com/cordya-ai/froid-plane-test-architecture-enterprise/issues) before filing a new one

package/docs/tutorials/learn-testing-tea-academy.md

@@ -0,0 +1,67 @@
+---
+title: 'Learn Testing with TEA Academy'
+description: Walk through your first TEA Academy session, from invocation to session notes
+---
+
+# Learn Testing with TEA Academy
+
+TEA Academy teaches testing through 7 progressive sessions with quizzes and saved progress. This tutorial walks you through starting it and completing Session 1. Budget 45 minutes.
+
+**Who it is for:** QA engineers, developers, leads, and managers learning testing.
+
+## Prerequisites
+
+- Froid installed with the TEA module (`npx froid-plane install`)
+
+## Step 1: Start the Workflow
+
+- **Claude Code / Cursor / Windsurf:** `/froid-teach-me-testing`
+- **Codex:** `$froid-teach-me-testing`
+- **Inside a `/froid-tea` chat:** `TMT`
+
+Full invocation rules: [Invoking a TEA Workflow](/docs/reference/commands.md#invoking-a-tea-workflow).
+
+## Step 2: Answer the Assessment
+
+On a first run, the workflow asks four questions before showing you anything:
+
+1. **Your role:** QA, Dev, Lead, or VP. This picks the examples used throughout.
+2. **Experience level:** beginner, intermediate, or experienced. This picks your recommended path.
+3. **Learning goals:** what you want out of the course.
+4. **Pain points** (optional): what is going wrong on your current project.
+
+Answer as your real role. A "Lead" answer produces architecture and code-review examples; a "Dev" answer produces TDD and API-testing examples for the same concepts.
+
+The session menu appears next, showing all 7 sessions with completion state and a recommended next session.
+
+## Step 3: Complete Session 1
+
+Pick **Session 1: Quick Start** (30 minutes). It runs in four beats:
+
+1. **Teaching.** What TEA is, the TEA Lite 30-minute path, the 9 workflows, and the 5 engagement models, with examples matched to the role you gave.
+2. **Quiz.** Three questions. 70% or higher passes. If you score lower, choose `[R]` to review the content again or `[C]` to continue with the score recorded.
+3. **Session notes.** The workflow writes `session-01-notes.md` with the key takeaways.
+4. **Back to the menu.** Pick the next session or exit. You can jump to any session; they are independent.
+
+## Step 4: Confirm Your Progress Saved
+
+Progress is written after the assessment, after each quiz, after each set of session notes, and on exit. Look under your configured `test_artifacts` folder (default `docs/test-artifacts`):
+
+```text
+docs/test-artifacts/
+├── teaching-progress/
+│   └── alex-tea-progress.yaml
+└── tea-academy/
+    └── alex/
+        └── session-01-notes.md
+```
+
+Run the workflow again at any time. It detects the progress file, shows your dashboard, and offers to resume.
+
+## Next Steps
+
+You have completed one session of seven. The rest cover core concepts, architecture patterns, test design, ATDD and automate, quality and trace, and a menu-driven tour of the 59 knowledge fragments.
+
+- [How to Learn Testing with TEA Academy](/docs/how-to/workflows/teach-me-testing.md) for the full session list, learning paths by experience, role customization, and troubleshooting
+- [Getting Started with Test Architect](/docs/tutorials/tea-lite-quickstart.md) to generate and run real tests in 30 minutes
+- [Knowledge Base](/docs/reference/knowledge-base.md) for the 59 fragments