ado-sync 0.1.46 → 0.1.48

package/docs/cli.md

@@ -0,0 +1,241 @@
+# CLI Reference
+
+```
+ado-sync [options] [command]
+
+Options:
+  -c, --config <path>     Path to config file (default: ado-sync.json)
+  --output <format>       Output format: text (default) or json
+  -V, --version           Print version
+  -h, --help              Show help
+
+Commands:
+  init                    Generate a starter config file (interactive wizard)
+  validate                Check config and Azure DevOps connectivity
+  push                    Push local specs to Azure DevOps
+  pull                    Pull updates from Azure DevOps into local files
+  status                  Show diff without making changes
+  diff                    Show field-level diff between local and Azure
+  generate                Generate local spec files from ADO User Stories
+  publish-test-results    Publish TRX / JUnit / Cucumber JSON results
+  help [command]          Help for a specific command
+```
+
+---
+
+## `init`
+
+Generate a starter config file. Runs an **interactive wizard** when stdin is a TTY.
+
+```bash
+ado-sync init                    # creates ado-sync.json (wizard)
+ado-sync init ado-sync.yml       # YAML format
+ado-sync init --no-interactive   # dump template without prompting
+```
+
+The wizard asks for org URL, project, auth type, token env var, test plan ID, local spec type, and include glob — then writes a minimal valid config.
+
+---
+
+## `validate`
+
+Check that the config is valid and Azure DevOps is reachable. Run this before your first `push`.
+
+```bash
+ado-sync validate
+ado-sync validate -c path/to/ado-sync.json
+```
+
+Output:
+```
+  ✓ Config loaded — /project/ado-sync.json
+  ✓ Azure connection — https://dev.azure.com/myorg
+  ✓ Project "MyProject" found
+  ✓ Test Plan #42 "Regression Suite" found
+
+All checks passed.
+```
+
+---
+
+## `push`
+
+Push local spec files to Azure DevOps — creates new Test Cases or updates existing ones.
+
+```bash
+ado-sync push
+ado-sync push --dry-run
+ado-sync push --tags "@smoke and not @wip"
+ado-sync push --config-override testPlan.id=9999
+
+# AI-generated test steps for code files
+ado-sync push --ai-provider heuristic           # fast regex, no model needed
+ado-sync push --ai-provider local --ai-model ~/.cache/models/qwen2.5-coder-1.5b-instruct-q4_k_m.gguf
+ado-sync push --ai-provider ollama --ai-model qwen2.5-coder:7b
+ado-sync push --ai-provider openai  --ai-key $OPENAI_API_KEY
+ado-sync push --ai-provider anthropic --ai-key $ANTHROPIC_API_KEY
+ado-sync push --ai-provider none                # disable AI entirely
+ado-sync push --ai-context ./docs/ai-context.md # inject domain context
+```
+
+| Scenario | Action |
+|----------|--------|
+| No ID tag | Creates a new Test Case, writes ID back |
+| ID tag, no changes | Skipped |
+| ID tag, content changed | Updates the existing Test Case |
+| Deleted locally, still in Azure | Tagged `ado-sync:removed` in Azure |
+
+### AI auto-summary
+
+For code-based types (`java`, `csharp`, `python`, `javascript`, `playwright`, `cypress`, `testcafe`, `detox`, `espresso`, `xcuitest`, `flutter`), ado-sync reads test function bodies and generates a TC **title**, **description**, and **steps** automatically.
+
+> No setup required — `push` always works, falling back to fast heuristic analysis.
+
+| Provider | Quality | Setup |
+|---|---|---|
+| `local` *(default)* | Good–Excellent | Download a GGUF model (see below) |
+| `heuristic` | Basic | None — offline, zero dependencies |
+| `ollama` | Good–Excellent | `ollama pull qwen2.5-coder:7b` |
+| `openai` | Excellent | `--ai-key $OPENAI_API_KEY` |
+| `anthropic` | Excellent | `--ai-key $ANTHROPIC_API_KEY` |
+| `openai` + `--ai-url` | Excellent | Any OpenAI-compatible proxy (LiteLLM, Azure OpenAI, vLLM) |
+
+#### Local LLM — model download
+
+```bash
+# macOS / Linux
+mkdir -p ~/.cache/ado-sync/models
+curl -L -o ~/.cache/ado-sync/models/qwen2.5-coder-1.5b-instruct-q4_k_m.gguf \
+  "https://huggingface.co/Qwen/Qwen2.5-Coder-1.5B-Instruct-GGUF/resolve/main/qwen2.5-coder-1.5b-instruct-q4_k_m.gguf"
+
+ado-sync push --ai-model ~/.cache/ado-sync/models/qwen2.5-coder-1.5b-instruct-q4_k_m.gguf
+```
+
+| Model | RAM | Quality |
+|-------|-----|---------|
+| 1.5B Q4_K_M | ~1.1 GB | Good |
+| 7B Q4_K_M | ~4.5 GB | Better |
+| 14B Q4_K_M | ~8.5 GB | Excellent |
+
+#### Inject domain context
+
+```bash
+ado-sync push --ai-context ./docs/ai-context.md
+```
+
+Or in config:
+```json
+{ "sync": { "ai": { "provider": "anthropic", "contextFile": "./docs/ai-context.md" } } }
+```
+
+#### Freeze steps in source files
+
+Enable `writebackDocComment: true` to write AI-generated steps as JSDoc comments above each `test()` call. On subsequent pushes the parser reads the JSDoc, so AI is not re-invoked.
+
+```json
+{ "sync": { "ai": { "writebackDocComment": true } } }
+```
+
+---
+
+## `pull`
+
+Pull Azure DevOps Test Case changes into local spec files.
+
+```bash
+ado-sync pull
+ado-sync pull --dry-run
+ado-sync pull --tags "@smoke"
+```
+
+---
+
+## `status`
+
+Show what would change on the next push without making any modifications.
+
+```bash
+ado-sync status
+ado-sync status --tags "@smoke"
+ado-sync status --output json    # machine-readable
+```
+
+---
+
+## `diff`
+
+Show a field-level diff between local specs and Azure DevOps — richer than `status`.
+
+```bash
+ado-sync diff
+ado-sync diff --tags "@smoke"
+```
+
+Output example:
+```
+~ specs/login.feature:12 · Login with valid credentials [#1234]
+    changed fields: title, steps
+```
+
+---
+
+## `generate`
+
+Generate local spec files (`.feature` or `.md`) from Azure DevOps User Stories, pulling title, description, and acceptance criteria to scaffold each file.
+
+```bash
+# By explicit work item IDs
+ado-sync generate --story-ids 1234,5678
+
+# By area path (fetches all User Stories under it)
+ado-sync generate --area-path "MyProject\\\\Teams\\\\QA"
+
+# By WIQL query
+ado-sync generate --query "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType]='User Story' AND [System.State]='Active'"
+
+# Options
+ado-sync generate --story-ids 1234 --format gherkin      # output .feature files
+ado-sync generate --story-ids 1234 --format markdown     # output .md files (default)
+ado-sync generate --story-ids 1234 --output-folder specs/generated
+ado-sync generate --story-ids 1234 --force               # overwrite existing files
+ado-sync generate --story-ids 1234 --dry-run             # preview without writing
+```
+
+---
+
+## `publish-test-results`
+
+Publish test results from TRX, JUnit XML, NUnit XML, Cucumber JSON, or Playwright JSON files to Azure DevOps Test Runs.
+
+```bash
+ado-sync publish-test-results --testResult results/test.trx
+ado-sync publish-test-results --testResult results/test.xml --testResultFormat junit --dry-run
+ado-sync publish-test-results --testResult results/playwright.json --attachmentsFolder test-results/
+```
+
+See [publish-test-results.md](publish-test-results.md) for full reference.
+
+---
+
+## `--config-override`
+
+All commands accept `--config-override path=value` (repeatable) to set config values at runtime:
+
+```bash
+ado-sync push --config-override testPlan.id=9999
+ado-sync push --config-override sync.disableLocalChanges=true
+ado-sync push --config-override sync.tagPrefix=test --config-override testPlan.id=42
+```
+
+---
+
+## `--output json`
+
+All sync commands support `--output json` for machine-readable output:
+
+```bash
+ado-sync status --output json | jq '.[] | select(.action=="updated")'
+ado-sync push   --output json > results.json
+```
+
+Each result object: `{ action, filePath, title, azureId?, detail?, changedFields? }`

package/docs/mcp-server.md

@@ -0,0 +1,275 @@
+# MCP Server
+
+`ado-sync` ships a built-in MCP (Model Context Protocol) server that exposes its sync operations as **structured tools** for AI agents — Claude Code, GitHub Copilot, Cursor, and any other MCP-compatible host.
+
+Using the MCP server instead of spawning the CLI gives agents:
+- Typed JSON responses (no output parsing)
+- Structured error objects with status codes
+- Fine-grained tool calls (get one test case, push a subset, etc.)
+
+---
+
+## Installation
+
+No separate install needed. `ado-sync-mcp` ships inside the `ado-sync` npm package.
+
+**Option A — Global install (recommended, fastest startup)**
+```bash
+npm install -g ado-sync
+```
+
+**Option B — npx (no install, always latest)**
+
+Use `npx --yes --package=ado-sync ado-sync-mcp` as the command in all configs below.
+npx downloads and runs the package automatically on first use.
+
+---
+
+## Claude Code — one-liner registration
+
+```bash
+# With global install
+claude mcp add ado-sync \
+  --env AZURE_DEVOPS_TOKEN="$AZURE_DEVOPS_TOKEN" \
+  --env ADO_SYNC_CONFIG="$(pwd)/ado-sync.json" \
+  -- ado-sync-mcp
+
+# With npx (no global install required)
+claude mcp add ado-sync \
+  --env AZURE_DEVOPS_TOKEN="$AZURE_DEVOPS_TOKEN" \
+  --env ADO_SYNC_CONFIG="$(pwd)/ado-sync.json" \
+  -- npx --yes --package=ado-sync ado-sync-mcp
+```
+
+Verify it registered: run `/mcp` in Claude Code — `ado-sync` should appear in the list.
+
+**Manual config** — `~/.claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "ado-sync": {
+      "command": "npx",
+      "args": ["--yes", "--package=ado-sync", "ado-sync-mcp"],
+      "env": {
+        "AZURE_DEVOPS_TOKEN": "<your-pat>",
+        "ADO_SYNC_CONFIG": "/absolute/path/to/ado-sync.json"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Claude Desktop
+
+Config file location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ado-sync": {
+      "command": "npx",
+      "args": ["--yes", "--package=ado-sync", "ado-sync-mcp"],
+      "env": {
+        "AZURE_DEVOPS_TOKEN": "<your-pat>",
+        "ADO_SYNC_CONFIG": "/absolute/path/to/ado-sync.json"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+---
+
+## VS Code (GitHub Copilot agent mode)
+
+Create `.vscode/mcp.json` in your workspace root:
+
+```json
+{
+  "servers": {
+    "ado-sync": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "--package=ado-sync", "ado-sync-mcp"],
+      "env": {
+        "AZURE_DEVOPS_TOKEN": "${env:AZURE_DEVOPS_TOKEN}",
+        "ADO_SYNC_CONFIG": "${workspaceFolder}/ado-sync.json"
+      }
+    }
+  }
+}
+```
+
+`${env:AZURE_DEVOPS_TOKEN}` reads the variable from your shell environment — no hardcoded secrets.
+
+---
+
+## Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ado-sync": {
+      "command": "npx",
+      "args": ["--yes", "--package=ado-sync", "ado-sync-mcp"],
+      "env": {
+        "AZURE_DEVOPS_TOKEN": "<your-pat>",
+        "ADO_SYNC_CONFIG": "/absolute/path/to/ado-sync.json"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Verify it works
+
+After registration, ask your AI assistant:
+
+```
+"Call ado-sync validate_config and tell me what it returns"
+```
+
+Expected response includes config validity, Azure connection status, and test plan confirmation.
+
+---
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `validate_config` | Check config validity and Azure DevOps connectivity |
+| `get_test_cases` | List all Test Cases in a suite |
+| `get_test_case` | Get a single Test Case by ID |
+| `push_specs` | Push local spec files to Azure DevOps |
+| `pull_specs` | Pull Azure DevOps changes into local files |
+| `status` | Show diff between local and Azure without making changes |
+| `diff` | Show field-level diff (richer than status) |
+| `generate_specs` | Generate local spec files from ADO User Stories |
+| `get_work_items` | Fetch ADO User Stories / work items |
+| `publish_test_results` | Publish TRX / JUnit / Playwright JSON / CTRF results; optionally file issues for failures |
+| `create_issue` | File a single GitHub Issue or ADO Bug for a test failure (for healer agents) |
+| `get_story_context` | Planner-agent feed: AC items, suggested tags, actors, linked TC IDs |
+| `generate_manifest` | Write `.ai-workflow-manifest-{id}.json` for the full Planner→CI cycle |
+
+---
+
+## Tool parameters
+
+All tools accept these optional base parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `configPath` | string | Absolute path to `ado-sync.json` (overrides `ADO_SYNC_CONFIG`) |
+| `configOverrides` | string[] | Runtime overrides in `key=value` format (same as `--config-override`) |
+
+### `push_specs`
+
+```json
+{
+  "dryRun": false,
+  "tags": "@smoke and not @wip",
+  "aiProvider": "heuristic"
+}
+```
+
+### `generate_specs`
+
+```json
+{
+  "storyIds": [1234, 5678],
+  "format": "gherkin",
+  "outputFolder": "specs/generated",
+  "dryRun": false,
+  "force": false
+}
+```
+
+### `publish_test_results`
+
+```json
+{
+  "testResult": "results/playwright.json",
+  "attachmentsFolder": "test-results/",
+  "createIssuesOnFailure": true,
+  "issueProvider": "github",
+  "githubRepo": "myorg/myrepo",
+  "githubToken": "$GITHUB_TOKEN",
+  "bugThreshold": 20,
+  "maxIssues": 50
+}
+```
+
+### `create_issue`
+
+```json
+{
+  "title": "[FAILED] Login with valid credentials",
+  "body": "Error: Expected 200 but got 401\n\nStack: ...",
+  "provider": "github",
+  "githubRepo": "myorg/myrepo",
+  "githubToken": "$GITHUB_TOKEN",
+  "testCaseId": 1234
+}
+```
+
+### `get_story_context`
+
+```json
+{ "storyId": 1234 }
+```
+
+Returns: AC items as a bullet list, inferred tags (`@smoke`, `@auth`, …), extracted actors, and IDs of any Test Cases already linked via TestedBy relation.
+
+### `generate_manifest`
+
+```json
+{
+  "storyIds": [1234, 5678],
+  "outputFolder": "e2e/bdd",
+  "format": "gherkin",
+  "dryRun": false
+}
+```
+
+Writes `.ai-workflow-manifest-1234.json` in `outputFolder`. The manifest contains the ordered 8-step workflow, AC items, required documents checklist, and validation steps.
+
+---
+
+## Example agent workflow
+
+Once registered, an AI agent can orchestrate the full test lifecycle without any human CLI invocation:
+
+```
+Agent: "Set up ado-sync for this repo"
+→ calls validate_config to check connectivity
+→ calls push_specs({ dryRun: true }) to preview
+→ calls push_specs({}) to create Test Cases
+
+Agent: "Generate spec files for User Story 1234"
+→ calls generate_specs({ storyIds: [1234], format: "gherkin" })
+
+Agent: "Publish the latest test results and file issues for failures"
+→ calls publish_test_results({ testResult: "results/playwright.json", createIssuesOnFailure: true, githubRepo: "myorg/myrepo", githubToken: "$GITHUB_TOKEN" })
+→ returns issue URLs for any failures → healer agent opens fix PRs
+```
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `ADO_SYNC_CONFIG` | Absolute path to config file (default: `ado-sync.json` in cwd) |
+| `AZURE_DEVOPS_TOKEN` | PAT or access token (referenced by `auth.token` in config) |
+
+> **Important:** `ADO_SYNC_CONFIG` must be an **absolute path**. The MCP server process does not inherit the shell's working directory the same way as a CLI call.

package/docs/publish-test-results.md

@@ -1,6 +1,6 @@
 # publish-test-results
 
-Parses test result files (TRX, NUnit XML, JUnit, Cucumber JSON, Playwright JSON) and publishes them to an Azure DevOps Test Run, linking results back to Test Cases either directly by TC ID (when available in the result file) or by `AutomatedTestName` matching.
+Parses test result files (TRX, NUnit XML, JUnit, Cucumber JSON, Playwright JSON, CTRF JSON) and publishes them to an Azure DevOps Test Run, linking results back to Test Cases either directly by TC ID (when available in the result file) or by `AutomatedTestName` matching.
 
 ---
 
@@ -31,11 +31,17 @@ ado-sync publish-test-results \
 | Option | Description |
 |--------|-------------|
 | `--testResult <path>` | Path to a result file. Repeatable. |
-| `--testResultFormat <format>` | `trx` · `nunitXml` · `junit` · `cucumberJson` · `playwrightJson`. Auto-detected when omitted. |
+| `--testResultFormat <format>` | `trx` · `nunitXml` · `junit` · `cucumberJson` · `playwrightJson` · `ctrfJson`. Auto-detected when omitted. |
 | `--attachmentsFolder <path>` | Folder to scan for screenshots/videos/logs to attach to test results. |
 | `--runName <name>` | Name for the Test Run in Azure DevOps. Defaults to `ado-sync <ISO timestamp>`. |
 | `--buildId <id>` | Build ID to associate with the Test Run. |
 | `--dry-run` | Parse results and print summary without creating a run in Azure. |
+| `--create-issues-on-failure` | File GitHub Issues or ADO Bugs for each failed test after publishing. |
+| `--issue-provider <github\|ado>` | Issue provider. Default: `github`. |
+| `--github-repo <owner/repo>` | GitHub repository to file issues in. |
+| `--github-token <token>` | GitHub token. Supports `$ENV_VAR` references. |
+| `--bug-threshold <percent>` | If more than this % of tests fail, one environment-failure issue is filed instead of per-test issues. Default: `20`. |
+| `--max-issues <n>` | Hard cap on issues filed per run. Default: `50`. |
 | `--config-override` | Override config values (repeatable, same as other commands). |
 
 ---
@@ -50,6 +56,7 @@ ado-sync publish-test-results \
 | Cucumber JSON | `.json` | Yes (JSON array, Cucumber format) | Yes — via `@tc:ID` tag on scenario | `step.embeddings[]` (base64 screenshots/video) |
 | Playwright JSON | `.json` | Yes (JSON object with `suites` key) | Yes — via `test.annotations[{ type: 'tc', description: 'ID' }]` (preferred) or `@tc:ID` in test title | `test.results[].attachments[]` (screenshots, videos, traces) |
 | Robot Framework XML | `output.xml` | Yes (`<robot>` root element) | Yes — via `<tags><tag>tc:ID</tag></tags>` | — |
+| CTRF JSON | `.json` | Yes (`results.tests` array) | Yes — via `tags: ["@tc:ID"]` or `@tc:ID` in test name | `attachments[].path` files, `stdout`/`stderr` arrays |
 
 > **NUnit via TRX**: when NUnit tests are run through the VSTest adapter (`--logger trx`), `[Property]` values are **not** included in the TRX output. Use `--logger "nunit3;LogFileName=results.xml"` to get the native NUnit XML format, which does include property values.
 
@@ -441,6 +448,38 @@ Recommended config:
 
 ---
 
+### CTRF (Common Test Report Format)
+
+[CTRF](https://ctrf.io) is a framework-agnostic JSON report format supported by reporters for Playwright, Cypress, Jest, k6, and many others. ado-sync auto-detects CTRF from the `results.tests` array structure.
+
+```bash
+# Example: Playwright with CTRF reporter
+npm install --save-dev playwright-ctrf-json-reporter
+
+# playwright.config.ts:
+# reporter: [['playwright-ctrf-json-reporter', { outputFile: 'results/ctrf.json' }]]
+
+npx playwright test
+ado-sync publish-test-results --testResult results/ctrf.json
+```
+
+```bash
+# Example: Jest with CTRF reporter
+npm install --save-dev jest-ctrf-json-reporter
+
+# jest.config.ts:
+# reporters: [['jest-ctrf-json-reporter', { outputFile: 'results/ctrf.json' }]]
+
+npx jest
+ado-sync publish-test-results --testResult results/ctrf.json
+```
+
+TC IDs are extracted from the `tags` array (e.g. `["@tc:1234", "@smoke"]`) or, as a fallback, from `@tc:ID` in the test name. `stdout`/`stderr` arrays and `attachments[].path` files are uploaded automatically.
+
+> **Status mapping**: CTRF `passed` → `Passed`, `failed` → `Failed`, `skipped`/`pending`/`other` → `NotExecuted`.
+
+---
+
 ### Flutter
 
 Flutter can produce JUnit XML via the `flutter_test_junit` package or by piping `--reporter junit`:
@@ -483,6 +522,7 @@ TC linking uses `AutomatedTestName` matching — set `sync.markAutomated: true`
 | Espresso | JUnit XML | ❌ AutomatedTestName matching only | `<system-out>`, `<system-err>` | |
 | Flutter | JUnit XML | ❌ AutomatedTestName matching only | `<system-out>`, `<system-err>` | |
 | Robot Framework | Robot XML (`output.xml`) | ✅ `tc:N` in `<tags>` | — | |
+| CTRF (any framework) | CTRF JSON | ✅ `tags: ["@tc:ID"]` or `@tc:ID` in name | `attachments[].path` files + `stdout`/`stderr` | |
 
 ---
 
@@ -499,6 +539,7 @@ ado-sync uploads screenshots, videos, and logs from test results to the correspo
 | JUnit XML | `<system-out>` → log; `<system-err>` → log; `[[ATTACHMENT\|path]]` → Playwright files |
 | Cucumber JSON | `step.embeddings[]` → base64-encoded screenshots/video |
 | Playwright JSON | `results[].attachments[].path` → files on disk (screenshots, videos, traces) |
+| CTRF JSON | `tests[].attachments[].path` → files on disk; `tests[].stdout[]` / `tests[].stderr[]` → console logs |
 
 > **Note**: All file paths are resolved relative to the result file's directory, not the process working directory. This matches how test runners (Playwright, MSTest, NUnit) write relative paths in their output.
 
@@ -670,6 +711,99 @@ Results can also be configured in the config file under `publishTestResults`:
 
 ---
 
+## Creating issues on failure
+
+`--create-issues-on-failure` automatically files a GitHub Issue or ADO Bug for each failed test
+after the run is published. Multiple guards prevent flooding your tracker when the environment is
+the problem rather than individual tests.
+
+### Guard logic (applied in order)
+
+```
+failures > threshold% of total?
+  └─ YES → 1 environment-failure issue, stop
+  └─ NO
+       └─ cluster by error signature
+            └─ cluster size > 1?
+                 └─ YES → 1 issue per cluster (lists affected test names)
+                 └─ NO  → 1 issue per TC (up to maxIssues cap)
+                               └─ cap hit? → 1 overflow summary issue
+```
+
+| Guard | Default | Description |
+|---|---|---|
+| Failure-rate threshold | 20% | Above this, one env-failure issue is filed instead of per-test |
+| Error clustering | enabled | Tests with the same error message are grouped into one issue |
+| Hard cap | 50 | No more than this many issues per run; one overflow summary when exceeded |
+| Dedup | enabled | Skip if an open issue already exists for the same TC (GitHub: by `tc:ID` label; ADO: by title) |
+
+### GitHub Issues (recommended)
+
+```bash
+ado-sync publish-test-results \
+  --testResult results/ctrf.json \
+  --create-issues-on-failure \
+  --github-repo myorg/myrepo \
+  --github-token $GITHUB_TOKEN
+```
+
+Each issue is labelled `test-failure` and `tc:{ID}` (when a TC ID is available). The issue body
+contains the error message, stack trace, ADO TC link, and run URL — everything a healer agent
+needs to propose a fix PR.
+
+### ADO Bugs
+
+```bash
+ado-sync publish-test-results \
+  --testResult results/junit.xml \
+  --create-issues-on-failure \
+  --issue-provider ado
+```
+
+ADO Bugs are created as Bug work items in the same project. The `Repro Steps` field is populated
+with the error details. When a TC ID is known, a `TestedBy` relation is added linking the Bug to
+the Test Case.
+
+### Config-based setup
+
+```json
+{
+  "publishTestResults": {
+    "createIssuesOnFailure": {
+      "provider": "github",
+      "repo": "myorg/myrepo",
+      "token": "$GITHUB_TOKEN",
+      "labels": ["test-failure", "automated"],
+      "threshold": 20,
+      "maxIssues": 50,
+      "clusterByError": true,
+      "dedupByTestCase": true
+    }
+  }
+}
+```
+
+CLI flags override the config values when both are present.
+
+### MCP tool: `create_issue`
+
+The `create_issue` MCP tool lets healer agents file a single issue directly:
+
+```
+create_issue({
+  title:       "[FAILED] Login with valid credentials",
+  body:        "Error: Expected 200 but got 401\n\nStack: ...",
+  provider:    "github",
+  githubRepo:  "myorg/myrepo",
+  githubToken: "$GITHUB_TOKEN",
+  testCaseId:  1234
+})
+```
+
+Returns the issue URL immediately, which the agent can embed in its fix PR.
+
+---
+
 ## Output
 
 ```