ado-sync 0.1.24 → 0.1.26

package/README.md

@@ -2,7 +2,7 @@
 
 Bidirectional sync between local test specs and Azure DevOps Test Cases.
 
-Supports **Cucumber / Gherkin** `.feature` files, **prose Markdown** `.md` spec files (including Playwright test-plan markdown generated by the Playwright MCP agent), and **Azure DevOps tabular exports** in **CSV** and **Excel** (`.xlsx`) format.
+Supports **Cucumber / Gherkin** `.feature` files, **prose Markdown** `.md` spec files (including Playwright test-plan markdown), and **Azure DevOps tabular exports** in **CSV** and **Excel** (`.xlsx`) format.
 Inspired by [SpecSync](https://docs.specsolutions.eu/specsync/).
 
 ---
@@ -20,7 +20,7 @@ Local files                   ado-sync              Azure DevOps
                               @tc:12345 / col A (csv/xlsx)
 ```
 
-On the **first push** of a scenario, a new Test Case is created in Azure DevOps and its ID is written back into the local file as a tag or comment. Every subsequent push uses that ID to update the existing Test Case. Pulling fetches the latest title and steps from Azure and overwrites the local file.
+On the **first push** of a scenario, a new Test Case is created in Azure DevOps and its ID is written back into the local file as a tag. Every subsequent push uses that ID to update the existing Test Case. Pulling fetches the latest title and steps from Azure and overwrites the local file.
 
 ---
 
@@ -28,7 +28,7 @@ On the **first push** of a scenario, a new Test Case is created in Azure DevOps
 
 ```bash
 npm install -g ado-sync
-# or use locally without installing
+# or run without installing
 npx ado-sync --help
 ```
 
@@ -36,51 +36,33 @@ npx ado-sync --help
 
 ## Quick start
 
-### 1. Generate a config file
-
 ```bash
+# 1. Generate a config file
 ado-sync init              # creates ado-sync.json
-ado-sync init ado-sync.yml # creates ado-sync.yml (YAML format)
+ado-sync init ado-sync.yml # YAML format
+
+# 2. Edit the config with your org, project, plan ID, and token
+export AZURE_DEVOPS_TOKEN=your_personal_access_token
+
+# 3. Preview what will be created
+ado-sync push --dry-run
+
+# 4. Push to Azure DevOps
+ado-sync push
 ```
 
-### 2. Edit the config
+Minimal config:
 
 ```json
 {
   "orgUrl": "https://dev.azure.com/my-org",
   "project": "MyProject",
-  "auth": {
-    "type": "pat",
-    "token": "$AZURE_DEVOPS_TOKEN"
-  },
-  "testPlan": {
-    "id": 1234,
-    "suiteId": 5678
-  },
-  "local": {
-    "type": "gherkin",
-    "include": "specs/**/*.feature"
-  },
-  "sync": {
-    "tagPrefix": "tc"
-  }
+  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
+  "testPlan": { "id": 1234 },
+  "local": { "type": "gherkin", "include": "specs/**/*.feature" }
 }
 ```
 
-### 3. Set your token
-
-```bash
-export AZURE_DEVOPS_TOKEN=your_personal_access_token
-```
-
-### 4. Push
-
-```bash
-ado-sync push
-```
-
-New scenarios are created in Azure DevOps. Their IDs are written back into your local files automatically.
-
 ---
 
 ## CLI reference
@@ -94,49 +76,36 @@ Options:
   -h, --help            Show help
 
 Commands:
-  init [output]         Generate a starter config file
-  push [options]        Push local specs to Azure DevOps
-  pull [options]        Pull updates from Azure DevOps into local files
-  status [options]      Show what would change without making any modifications
-  help [command]        Help for a specific command
+  init [output]                Generate a starter config file
+  push [options]               Push local specs to Azure DevOps
+  pull [options]               Pull updates from Azure DevOps into local files
+  status [options]             Show diff without making changes
+  publish-test-results [opts]  Publish TRX / JUnit / Cucumber JSON results to Azure DevOps
+  help [command]               Help for a specific command
 ```
 
 ### `init`
 
 ```bash
 ado-sync init                    # creates ado-sync.json
-ado-sync init ado-sync.yml       # creates ado-sync.yml
-ado-sync init path/to/config.json
+ado-sync init ado-sync.yml       # YAML format
 ```
 
-Creates a starter config file in JSON or YAML format depending on the file extension. Safe — will not overwrite an existing file.
-
----
-
 ### `push`
 
 ```bash
 ado-sync push
 ado-sync push --dry-run
-ado-sync push --tags "@smoke"
 ado-sync push --tags "@smoke and not @wip"
 ado-sync push --config-override testPlan.id=9999
-ado-sync -c other-config.json push
 ```
 
-For every scenario / heading in your local spec files:
-
 | Scenario state | Action |
 |----------------|--------|
-| No ID tag yet | Creates a new Test Case, writes ID back to file |
-| Has ID tag, no changes | Skipped (uses local cache for speed) |
-| Has ID tag, title or steps changed | Updates the existing Test Case |
+| 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 suite | Tagged `ado-sync:removed` in Azure |
-| Has ID tag but Test Case deleted in Azure | Reported as error |
-
-`--dry-run` prints what would happen without modifying anything.
-
----
 
 ### `pull`
 
@@ -144,637 +113,37 @@ For every scenario / heading in your local spec files:
 ado-sync pull
 ado-sync pull --dry-run
 ado-sync pull --tags "@smoke"
-ado-sync pull --config-override sync.conflictAction=skip
 ```
 
-For every locally-linked scenario (has an ID tag):
-
-| Remote state | Action |
-|--------------|--------|
-| Title, steps, or description changed in Azure | Updates the local file |
-| No changes | Skipped |
-| Test Case not found | Reported as error |
-
-`--dry-run` prints what would change without modifying local files.
-
----
-
 ### `status`
 
 ```bash
 ado-sync status
 ado-sync status --tags "@smoke"
-ado-sync status --config-override testPlan.id=9999
 ```
 
 Compares local specs against Azure DevOps and prints a diff — no changes made.
 
----
-
-### `--config-override`
-
-All commands accept one or more `--config-override path=value` options to set config values from the command line without editing the file. Useful in CI pipelines.
+### `publish-test-results`
 
 ```bash
-# Override test plan ID
-ado-sync push --config-override testPlan.id=9999
-
-# Override tag prefix
-ado-sync push --config-override sync.tagPrefix=azure
-
-# Multiple overrides (repeat the flag)
-ado-sync push \
-  --config-override testPlan.id=9999 \
-  --config-override sync.disableLocalChanges=true
+ado-sync publish-test-results --testResult results/test.trx
+ado-sync publish-test-results --testResult results/test.xml --testResultFormat junit --dry-run
 ```
 
-Dot-path notation is used for nested fields. Numbers and booleans are coerced automatically.
-
----
-
-## Config file reference
-
-Config files can be JSON (`.json`) or YAML (`.yml` / `.yaml`). Run `ado-sync init` to generate a template.
-
-### Full example (JSON)
-
-```json
-{
-  "orgUrl": "https://dev.azure.com/YOUR_ORG",
-  "project": "YOUR_PROJECT",
-
-  "auth": {
-    "type": "pat",
-    "token": "$AZURE_DEVOPS_TOKEN"
-  },
-
-  "testPlan": {
-    "id": 1234,
-    "suiteId": 5678,
-    "suiteMapping": "flat"
-  },
-
-  "local": {
-    "type": "gherkin",
-    "include": "specs/**/*.feature",
-    "exclude": []
-  },
-
-  "sync": {
-    "tagPrefix": "tc",
-    "titleField": "System.Title",
-    "areaPath": "MyProject\\Team A",
-    "iterationPath": "MyProject\\Sprint 1",
-    "disableLocalChanges": false,
-    "conflictAction": "overwrite",
-    "links": [
-      { "prefix": "story", "relationship": "System.LinkTypes.Related" },
-      { "prefix": "bug",   "relationship": "System.LinkTypes.Related" }
-    ]
-  }
-}
-```
-
----
-
-### `orgUrl`
-
-Azure DevOps organisation URL. Format: `https://dev.azure.com/YOUR_ORG`.
-
----
-
-### `project`
-
-Azure DevOps project name.
-
----
-
-### `auth`
-
-| Field | Description |
-|-------|-------------|
-| `type` | `"pat"` · `"accessToken"` · `"managedIdentity"` |
-| `token` | PAT or access token value. Prefix with `$` to read from an environment variable (e.g. `"$AZURE_DEVOPS_TOKEN"`). |
-| `applicationIdURI` | Required only when `type` is `"managedIdentity"`. |
-
-**PAT permissions required:** Test Management (Read & Write), Work Items (Read & Write).
-
----
-
-### `testPlan`
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `id` | *(required)* | ID of the Azure DevOps Test Plan. |
-| `suiteId` | plan root | ID of the Test Suite within the plan. Defaults to the plan's root suite. |
-| `suiteMapping` | `"flat"` | `"flat"` — all Test Cases go into one suite. `"byFolder"` — folder structure is mirrored as nested child suites (e.g. `specs/login/` → suite named `login`). |
-
----
-
-### `testPlans` (multi-plan)
-
-To sync the same repository against multiple Test Plans, use the `testPlans` array instead of (or in addition to) `testPlan`. Each entry overrides `testPlan` and can specify its own file globs.
-
-```json
-{
-  "testPlans": [
-    {
-      "id": 1001,
-      "suiteId": 2001,
-      "include": "specs/smoke/**/*.feature"
-    },
-    {
-      "id": 1002,
-      "suiteId": 2002,
-      "include": "specs/regression/**/*.feature",
-      "suiteMapping": "byFolder"
-    }
-  ]
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `id` | Test Plan ID |
-| `suiteId` | *(Optional)* Target suite ID |
-| `suiteMapping` | *(Optional)* `"flat"` or `"byFolder"` |
-| `include` | *(Optional)* Override `local.include` for this plan |
-| `exclude` | *(Optional)* Override `local.exclude` for this plan |
-
----
-
-### `local`
-
-| Field | Description |
-|-------|-------------|
-| `type` | `"gherkin"` · `"markdown"` · `"csv"` · `"excel"` — see [Spec file formats](#spec-file-formats) |
-| `include` | Glob pattern(s) relative to the config file. String or array. |
-| `exclude` | *(Optional)* Glob pattern(s) to exclude. String or array. |
-
----
-
-### `sync`
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `tagPrefix` | `"tc"` | Prefix used in ID tags. See [ID tags](#id-tags). |
-| `titleField` | `"System.Title"` | Azure DevOps field used as the test case title. |
-| `areaPath` | *(none)* | Area path for newly created Test Cases. |
-| `iterationPath` | *(none)* | Iteration path for newly created Test Cases. |
-| `disableLocalChanges` | `false` | When `true`, no local files are modified — no ID writeback, no pull apply. Use in CI pipelines that should not commit file changes. |
-| `conflictAction` | `"overwrite"` | How to handle conflicts (remote changed since last sync AND local also differs). `"overwrite"` — push local version. `"skip"` — emit a conflict result, leave both sides unchanged. `"fail"` — throw an error listing all conflicts. |
-| `links` | `[]` | Work item link configurations. See [Work item linking](#work-item-linking). |
-
----
-
-## ID tags
-
-After a scenario is pushed for the first time, ado-sync writes the Azure Test Case ID back into the local file. The format depends on the spec type.
-
-| Format | Writeback location |
-|--------|--------------------|
-| Gherkin | `@tc:12345` tag above the `Scenario:` line |
-| Markdown | `@tc:12345` tag after the `### heading` |
-| CSV | Numeric ID in column A of the matching title row |
-| Excel | Numeric ID in cell A of the matching title row |
-
-### Gherkin
-
-The ID tag is inserted on its own line immediately above the `Scenario:` or `Scenario Outline:` keyword:
-
-```gherkin
-Feature: Login
-
-  @tc:1042
-  Scenario: Successful login with valid credentials
-    Given I am on the login page
-    When I enter username "standard_user" and password "secret_sauce"
-    Then I am redirected to the inventory page
-```
-
-For `Scenario Outline`, a **single** parametrized Test Case is created in Azure with a data table — one `@tc:ID` tag for the whole outline, not one per example row.
-
-```gherkin
-  @tc:1043
-  Scenario Outline: Login with different roles
-    Given I am logged in as "<role>"
-    Then I can see "<dashboard>"
-
-    Examples:
-      | role    | dashboard  |
-      | admin   | Admin view |
-      | tester  | Test view  |
-```
-
-### Markdown
-
-The ID tag is inserted on the line immediately after the `### heading`:
-
-```markdown
-### 1. Login (happy path)
-@tc:1042
-
-Assumption: Fresh browser session.
-
-Steps:
-1. Enter username `standard_user` in the Username field.
-2. Enter password `secret_sauce` in the Password field.
-3. Click `Login`.
-
-Expected results:
-- User is redirected to `/inventory.html`.
-- Product list is visible.
-
----
-```
-
-### Custom prefix
-
-Change the `sync.tagPrefix` in your config to use a different prefix:
-
-```json
-{ "sync": { "tagPrefix": "azure" } }
-```
-
-Result:
-- Gherkin: `@azure:1042`
-- Markdown: `@azure:1042`
-
-> **Warning:** Changing the prefix on an existing project means all existing ID tags will no longer be recognised. Do a project-wide find-and-replace on the old prefix before changing it.
-
----
-
-## Tag filtering
-
-All commands accept a `--tags` option to limit which scenarios are synced. The syntax is the standard Cucumber tag expression language.
-
-```bash
-# Only sync scenarios tagged @smoke
-ado-sync push --tags "@smoke"
-
-# Sync everything except @wip
-ado-sync push --tags "not @wip"
-
-# Combine tags with and / or
-ado-sync push --tags "@smoke and not @slow"
-ado-sync pull --tags "@regression or @critical"
-```
-
-Tags are evaluated against all tags on a scenario, including:
-
-- Tags inherited from the Feature block (Gherkin)
-- Tags on the Scenario / Scenario Outline block
-- Tags on individual Examples tables
-- Inline `<!-- tags: -->` comments in Markdown (see below)
-- **Path-based auto-tags** — directory segments prefixed with `@` are automatically applied as tags to all scenarios in that directory:
-
-  ```
-  specs/
-    @smoke/
-      login.feature       ← all scenarios get tag 'smoke'
-    @regression/
-      @slow/
-        checkout.feature  ← all scenarios get tags 'regression' and 'slow'
-  ```
-
-  ```bash
-  ado-sync push --tags "@smoke"   # only push specs/@smoke/** scenarios
-  ```
-
-### Tags in Markdown
-
-Add a `<!-- tags: -->` HTML comment anywhere inside a scenario block to assign tags:
-
-```markdown
-### Login with valid credentials
-@tc:1042
-<!-- tags: @smoke, @regression -->
-
-Steps:
-1. Navigate to the login page
-2. Enter valid credentials
-3. Click Login
-
-Expected results:
-- Dashboard is shown
-
----
-```
-
-Path-based auto-tagging also works for Markdown files — placing them inside an `@smoke/` folder automatically adds the `smoke` tag.
-
----
-
-## Spec file formats
-
-### Gherkin `.feature`
-
-Standard Gherkin syntax is supported, including:
-- `Feature` / `Scenario` / `Scenario Outline`
-- `Given` / `When` / `Then` / `And` / `But`
-- Feature-level and scenario-level tags
-- `Scenario Outline` with `Examples` tables — creates a **single** parametrized Test Case in Azure (data table included), not one TC per row
-
-```gherkin
-Feature: Checkout
-
-  @smoke
-  Scenario: Add item and complete checkout
-    Given I am logged in as "standard_user"
-    When I add "Sauce Labs Backpack" to the cart
-    And I proceed through checkout with name "Test User" and zip "12345"
-    Then I see the order confirmation page
-
-  Scenario Outline: Checkout with different users
-    Given I am logged in as "<user>"
-    When I complete a checkout
-    Then the result is "<result>"
-
-    Examples:
-      | user                    | result  |
-      | standard_user           | success |
-      | performance_glitch_user | success |
-```
-
-### Markdown `.md`
-
-Each `### heading` is treated as one test case. The file can contain any number of scenarios separated by `---`.
-
-```markdown
-# My Feature Test Plan
-
-## Test scenarios
-
-### Login with valid credentials
-<!-- tags: @smoke -->
+See [docs/publish-test-results.md](docs/publish-test-results.md) for full reference.
 
-Assumption: Fresh browser session.
-
-Steps:
-1. Navigate to https://example.com/login
-2. Enter username "admin" and password "secret"
-3. Click the Login button
-
-Expected results:
-- The dashboard page is shown
-- The username appears in the top navigation
-
----
-
-### Login with invalid credentials
-
-Steps:
-1. Navigate to https://example.com/login
-2. Enter username "wrong" and password "wrong"
-3. Click the Login button
-
-Expected results:
-- An error message "Invalid credentials" is displayed
-- The user remains on the login page
-
----
-```
-
-Sections recognised: `Steps:`, `Expected results:` (case-insensitive). All other prose is captured as the test case description. Heading number prefixes (`### 1. Title` or `### Title`) are both supported.
-
-#### Playwright test-plan markdown
-
-Markdown `.md` files generated by the [Playwright MCP agent](https://playwright.dev/docs/test-agents) are fully supported as a local spec source. Set `local.type: "markdown"` and point `local.include` at the generated files to sync them into Azure DevOps as Test Cases.
-
----
-
-### CSV `.csv`
-
-Set `local.type: "csv"` to parse Azure DevOps / SpecSync tabular CSV exports.
-
-**Expected column layout (9 columns):**
-
-| Col | Field | Description |
-|-----|-------|-------------|
-| A (0) | ID | Azure Test Case ID — empty for new cases, filled in after first push |
-| B (1) | Work Item Type | Always `Test Case` (ignored) |
-| C (2) | Title | `Scenario: My test` or just `My test` — non-empty on the header row, empty on step rows |
-| D (3) | Test Step | Step number (1, 2, …) — empty on the header row |
-| E (4) | Step Action | Step text, optionally prefixed with a Gherkin keyword (`Given`, `When`, `Then`, …) |
-| F (5) | Step Expected | Expected result text (optional) |
-| G–I (6–8) | Area Path, Assigned To, State | Preserved but not used during parse |
-
-**Example CSV:**
-
-```csv
-ID,Work Item Type,Title,Test Step,Step Action,Step Expected,Area Path,Assigned To,State
-"","Test Case","Scenario: Login happy path",,,,...
-,,,,,"1","Given I open the app","",,...
-,,,,,"2","When I enter valid credentials","Then I see the dashboard",...
-"","Test Case","Scenario: Login with bad password",,,,...
-,,,,,"1","Given I enter wrong credentials","Then I see an error",...
-```
-
-The first row (column headers) is always skipped automatically.
-
-**ID writeback:** After the first push, the numeric TC ID is written into **column A** of the matching title row.
-
-> **Note:** Pull (`ado-sync pull`) is **not supported** for CSV files — these files are typically generated by external tools (e.g. the Playwright planner agent) and are not hand-authored. Only push is supported.
-
-**Config example:**
-
-```json
-{
-  "local": {
-    "type": "csv",
-    "include": "specs/**/*.csv"
-  }
-}
-```
-
----
-
-### Excel `.xlsx`
-
-Set `local.type: "excel"` to parse Azure DevOps / SpecSync tabular Excel exports.
-
-The xlsx format uses the same 9-column layout as CSV above. ado-sync reads the raw worksheet XML directly (no heavyweight xlsx library required) and handles both plain-string (`t="str"`) and rich-text inline-string (`t="inlineStr"`) cells produced by Azure DevOps exports.
-
-**ID writeback:** After the first push, the numeric TC ID is written into **cell A** of the matching title row and the file is repacked in place.
-
-> **Note:** Pull (`ado-sync pull`) is **not supported** for Excel files for the same reason as CSV — these are externally generated files. Only push is supported.
-
-**Config example:**
-
-```json
-{
-  "local": {
-    "type": "excel",
-    "include": "specs/**/*.xlsx"
-  }
-}
-```
-
----
-
-## Work item linking
-
-Tags matching a configured `links` prefix are turned into Azure DevOps work item relations on the Test Case.
-
-### Config
-
-```json
-{
-  "sync": {
-    "links": [
-      { "prefix": "story",  "relationship": "System.LinkTypes.Related" },
-      { "prefix": "bug",    "relationship": "System.LinkTypes.Related" },
-      { "prefix": "req",    "relationship": "Microsoft.VSTS.Common.TestedBy-Reverse" }
-    ]
-  }
-}
-```
-
-### Usage in Gherkin
-
-```gherkin
-  @tc:1042 @story:555 @bug:789
-  Scenario: User can add items to cart
-    ...
-```
-
-### Usage in Markdown
-
-```markdown
-### User can add items to cart
-@tc:1042
-<!-- tags: @story:555, @bug:789 -->
-```
-
-On each `push`, relations are synced: new links are added and stale links (whose tag was removed) are deleted. The `relationship` value is the ADO relation type; `"System.LinkTypes.Related"` is the default if omitted.
-
----
-
-## Suite hierarchy
-
-By default, all Test Cases are created in a single flat suite (`suiteMapping: "flat"`). Setting `suiteMapping: "byFolder"` mirrors the folder structure of your spec files as nested child suites in Azure.
-
-```json
-{
-  "testPlan": {
-    "id": 1234,
-    "suiteId": 5678,
-    "suiteMapping": "byFolder"
-  }
-}
-```
-
-```
-specs/
-  login/
-    basic.feature    → suite "login" → TC "Successful login"
-  checkout/
-    happy.feature    → suite "checkout" → TC "Add item and checkout"
-```
-
-Child suites are created automatically if they do not exist. The suite hierarchy is re-used across runs.
-
----
-
-## Conflict detection
-
-ado-sync uses a local state cache (`.ado-sync-state.json`) to detect conflicts — cases where **both** the local file and the Azure Test Case were changed since the last sync.
-
-The `sync.conflictAction` setting controls what happens:
-
-| Value | Behaviour |
-|-------|-----------|
-| `"overwrite"` *(default)* | Push the local version to Azure, overwriting the remote change. |
-| `"skip"` | Emit a `!` conflict result for the scenario and leave both sides unchanged. |
-| `"fail"` | Throw an error listing all conflicting scenarios and abort the sync. |
-
-```json
-{ "sync": { "conflictAction": "skip" } }
-```
-
----
-
-## Local state cache
-
-ado-sync writes a `.ado-sync-state.json` file in the same directory as your config file. This cache stores SHA-256 hashes of the last-synced title, steps, and description for each Test Case, plus the Azure `changedDate` timestamp.
-
-**Commit this file to version control** so all team members and CI share the same last-synced state, enabling accurate conflict detection across machines.
-
-The cache also speeds up `push` — if neither the local file nor the Azure `changedDate` has changed since the last sync, the Azure API call is skipped entirely and the scenario is marked `skipped`.
-
----
-
-## Build server / CI mode
-
-Set `sync.disableLocalChanges: true` to prevent ado-sync from writing back to local files. In this mode:
-
-- `push` — creates and updates Test Cases in Azure, but does **not** write ID tags back to local files.
-- `pull` — computes what would change but does **not** modify local files (behaves like `--dry-run`).
-
-```json
-{ "sync": { "disableLocalChanges": true } }
-```
+### `--config-override`
 
-Or use `--config-override` per run:
+All commands accept `--config-override path=value` to set config values without editing the file:
 
 ```bash
+ado-sync push --config-override testPlan.id=9999
 ado-sync push --config-override sync.disableLocalChanges=true
 ```
 
 ---
 
-## Removed scenario detection
-
-When a scenario is deleted from a local spec file but its Test Case still exists in the Azure suite, ado-sync detects this on the next `push` and appends the tag `ado-sync:removed` to the Azure Test Case (without deleting it). A `−` removed line is printed in the output.
-
-To completely remove the Test Case from Azure, delete it manually in Test Plans after reviewing.
-
----
-
-## YAML config example
-
-```yaml
-orgUrl: https://dev.azure.com/my-org
-project: MyProject
-
-auth:
-  type: pat
-  token: $AZURE_DEVOPS_TOKEN
-
-testPlan:
-  id: 1234
-  suiteId: 5678
-  suiteMapping: byFolder
-
-local:
-  type: gherkin
-  include: specs/**/*.feature
-  exclude:
-    - specs/archive/**
-
-sync:
-  tagPrefix: tc
-  areaPath: "MyProject\\QA Team"
-  conflictAction: skip
-  disableLocalChanges: false
-  links:
-    - prefix: story
-      relationship: System.LinkTypes.Related
-```
-
----
-
-## Environment variables
-
-| Variable | Description |
-|----------|-------------|
-| `AZURE_DEVOPS_TOKEN` | PAT or access token. Reference it in config with `"$AZURE_DEVOPS_TOKEN"`. |
-| Any name | Any env var can be used — set `auth.token` to `"$MY_VAR_NAME"`. |
-
-You can also use a `.env` file in the working directory. It is loaded automatically.
-
----
-
 ## Output symbols
 
 ```
@@ -789,68 +158,67 @@ You can also use a `.env` file in the working directory. It is loaded automatica
 
 ---
 
-## Workflow examples
+## Documentation
 
-### First-time setup
-
-```bash
-# Generate config
-ado-sync init
+| Topic | Link |
+|-------|------|
+| Full configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Spec file formats (Gherkin, Markdown, CSV, Excel) | [docs/spec-formats.md](docs/spec-formats.md) |
+| Advanced features (format, state, fieldUpdates, customizations, attachments, CI mode) | [docs/advanced.md](docs/advanced.md) |
+| Publishing test results | [docs/publish-test-results.md](docs/publish-test-results.md) |
 
-# Edit ado-sync.json with your org, project, plan ID, and token
-export AZURE_DEVOPS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-
-# Preview what will be created
-ado-sync push --dry-run
+---
 
-# Create test cases in Azure DevOps
-ado-sync push
-```
+## Workflow examples
 
 ### Day-to-day: local changes first
 
 ```bash
-# Edit your .feature or .md files locally
-# Then push changes to Azure DevOps
+# Edit your .feature or .md files, then push
 ado-sync push
 ```
 
 ### Day-to-day: Azure changes first
 
 ```bash
-# Someone edited a test case in Azure DevOps Test Plans UI
-# Pull the changes into your local files
+# Someone edited a Test Case in the Azure DevOps UI
 ado-sync pull
 ```
 
-### Check for drift before a PR
-
-```bash
-ado-sync status
-```
-
-### CI pipeline (no file writeback)
+### CI pipeline
 
 ```yaml
-# GitHub Actions example
+# GitHub Actions
 - name: Sync test cases to Azure DevOps
   run: ado-sync push --config-override sync.disableLocalChanges=true
   env:
     AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
+
+- name: Publish test results
+  run: ado-sync publish-test-results --testResult results/test.trx
+  env:
+    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
 ```
 
-### Override plan per environment
+### Check for drift before a PR
 
 ```bash
-# Push to staging plan
-ado-sync push --config-override testPlan.id=2001
-
-# Push to production plan
-ado-sync push --config-override testPlan.id=3001
+ado-sync status
 ```
 
 ---
 
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `AZURE_DEVOPS_TOKEN` | PAT or access token. Reference in config with `"$AZURE_DEVOPS_TOKEN"`. |
+| Any name | Any env var — set `auth.token` to `"$MY_VAR_NAME"`. |
+
+A `.env` file in the working directory is loaded automatically.
+
+---
+
 ## Troubleshooting
 
 **`No config file found`**
@@ -860,28 +228,25 @@ Run `ado-sync init` or pass `-c path/to/config.json`.
 Your config references `$X` in `auth.token` but the variable is not exported. Run `export X=...` or add it to a `.env` file.
 
 **Test Case created but ID not written back**
-Check that the local file is writable, or set `sync.disableLocalChanges: false`. On the next `push` it will try again.
+Check that the file is writable, or that `sync.disableLocalChanges` is not `true`.
 
 **`Test case #N not found in Azure DevOps`**
 The test case was deleted in Azure. Remove the ID tag from the local file to recreate it, or restore the test case in Azure.
 
 **`Failed to parse <file>`**
-Gherkin syntax error in a `.feature` file. Run `npx cucumber-js --dry-run` to identify the problem line.
+Gherkin syntax error. Run `npx cucumber-js --dry-run` to identify the problem line.
 
 **Changes not detected on push**
-The comparison uses title + steps + description. If only `areaPath` or `iterationPath` changed, touch any step to trigger an update, or use `--config-override` to set those fields and rely on the next sync.
+The comparison uses title + steps + description. Touch any step to force an update, or reset the cache by deleting `.ado-sync-state.json`.
 
 **Conflict detected unexpectedly**
-Delete `.ado-sync-state.json` to reset the cache. The next push will re-populate it by fetching current state from Azure.
-
-**`init` generated JSON instead of YAML**
-Pass the filename as a positional argument: `ado-sync init ado-sync.yml` (not `--output`).
+Delete `.ado-sync-state.json` to reset the cache. The next push re-populates it from Azure.
 
 **CSV/Excel IDs not written back**
-Ensure the file is not open in Excel or another application (which would lock it). Also check that `sync.disableLocalChanges` is not `true`.
+Ensure the file is not open in another application. Check that `sync.disableLocalChanges` is not `true`.
 
 **Excel file not parsed / `No worksheet found`**
-ado-sync looks for `xl/worksheets/sheet.xml` or `xl/worksheets/sheet1.xml` inside the xlsx ZIP. Files exported directly from Azure DevOps or saved by the Playwright planner agent match this structure. Workbooks re-saved by Excel may use a different sheet name — export again from Azure DevOps to regenerate a compatible file.
+ado-sync looks for `xl/worksheets/sheet.xml` or `xl/worksheets/sheet1.xml` inside the xlsx ZIP. Re-export from Azure DevOps to get a compatible file.
 
 **Pull has no effect on CSV/Excel files**
-Pull is not supported for CSV and Excel formats — these files are managed by external tools. Use `push` to sync local changes to Azure DevOps.
+Pull is not supported for CSV and Excel — only push. These formats are managed by external tools.