testeiya 0.3.9 → 0.3.14

package/skills/testomatio/test-management/scan-automation-project/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: scan-automation-project
+description: Scan project source code to inventory languages, frameworks, and existing tests (manual `*.test.md` and automated test files). Use this skill whenever analyzing a codebase for test planning, detecting test frameworks, or preparing for test automation. Specifically, when the user mentions "scan project", "what tests exist", "analyze codebase", "detect frameworks", "test matrix", or needs a codebase inventory before a QA workflow.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Scan Automation Project
+
+Scan project source code and return a QA-focused inventory: languages, frameworks, and existing tests.
+
+**Shallow scan only.** No full import resolution, no line-by-line parsing, no reading full test implementations. High-level structure only.
+
+## Step 1: Locate Source Code
+
+- If the project root has non-empty source folders or files, go to Step 2.
+- If **no source** files are found, stop and ask the user:
+
+```
+❓ No application source code detected (folder may be empty or missing).
+Where is the source code?
+1. Use local project from another folder (I will create a symlink)
+2. Clone from Git repo
+3. I don't know yet (stop here)
+```
+
+- Wait for the user's reply.
+- If the user gives a Git repo or another folder, clone or symlink it into `.testeiya/code/`. No-op if it is already there.
+
+### Rule for pulled data
+
+**When you need to pull external data** (manual test cases, app code, e2e tests from another repo) into this project:
+
+| This project has | Store pulled data in | Gitignored? |
+| ------------------ | ---------------------- | ----------- |
+| **Source code** (`src/` folder) or **big project** | `.testeiya/…` | **Yes** |
+| **Only test infrastructure** (e2e dirs like `tests/`, `playwright/`, `cypress/` but no `src/`) | `manual-tests/` or `e2e-tests/` | No |
+| **Empty / manual-only** | `manual-tests/` | No |
+
+Detection logic:
+1. Has `src/` folder or is a monorepo? → Use `.testeiya/`
+2. Has e2e test dirs (`tests/`, `playwright/`, `cypress/`, `e2e/`)? → Use tracked folder (`manual-tests/`, `e2e-tests/`)
+3. Otherwise → Default to `manual-tests/`
+
+- Any skill that creates `.testeiya/...` must also add `.testeiya/` to the project's `.gitignore` — but only if it is not there yet. Never add it twice.
+- The rule covers *pulled* data only. Output a skill *produces* and the user wants — a `coverage.*.yml`, new `*.test.md` files — goes in the repo as normal.
+- On a source repo with no manual tests, this skill changes no tracked file: it only creates the gitignored `.testeiya/` directory and, if needed, adds one line to `.gitignore`.
+- **Only touch `.testeiya/` and tracked folders — never pollute the repo with cache in a wrong location.**
+
+## Step 2: Project Analysis
+
+Collect source file paths only. **Do NOT read file contents.**
+
+Include:
+- Application source files.
+- View/template files: `.html`/`.htm`, `.vue`, `.svelte`, `.hbs`/`.handlebars`, `.ejs`, `.pug`/`.jade`, `.mustache`, `.liquid`, `.erb`, `.haml`, `.slim`, `.blade.php`, `.twig`, `.j2`/`.jinja`/`.jinja2`, `.cshtml`/`.razor`, `.jsp`. They are application source — coverage skills map UI changes through them.
+
+Exclude:
+- Dependencies, build output, coverage, reports, caches, config, lock, and environment files.
+- Paths ignored by `.gitignore` — but **not** `.testeiya/code/`. In a manual-tests repo the app code lives there; scan it as source.
+- Testeiya internal files (e.g. `session-factory.ts`, `system-prompt.ts`).
+- **If in doubt**, exclude.
+
+From the file list:
+- Detect languages and frameworks. Collect one `frameworks` list with ALL application and testing frameworks.
+- Extract the project name from a project config file (`package.json`, `Cargo.toml`, `pom.xml`, ...); fall back to the root directory name.
+- Rate complexity by source file count:
+
+| File Count | Complexity   |
+|------------|--------------|
+| 1-30       | `small`      |
+| 31-150     | `moderate`   |
+| 151-500    | `large`      |
+| 500+       | `very-large` |
+
+## Step 3: Test Inventory (optional)
+
+Detect existing tests, automated and manual. Stay shallow.
+
+Automated tests:
+- Detect frameworks via config files (`jest.config.*`, `playwright.config.*`, `vitest.config.*`, `pytest.ini`, `pom.xml`, ...), project dependencies, and test file patterns (`*.test.*`, `*.spec.*`, `*_test.*`).
+- For each framework: identify its test file pattern and count matching files.
+
+Manual tests:
+- Find all `.test.md` files and parse test titles. `find .` also looks inside `.testeiya/manual-tests/`, so a re-run after a pull finds the cached cases instead of reporting "no manual tests":
+
+```bash
+find . -name "*.test.md" -exec awk '
+  /^<!-- test/   { in_block=1; kind="TEST";  next }
+  /^<!-- suite/  { in_block=1; kind="SUITE"; next }
+  in_block && /^-->/ { in_block=0; expect=1; next }
+  expect && /^#+[[:space:]]+/ {
+    title=$0; sub(/^#+[[:space:]]+/, "", title)
+    if (kind == "SUITE") printf "SUITE: %s\n", title
+    else             printf "|- %s\n",     title
+    expect=0
+  }
+' {} +
+```
+
+- If the only `.test.md` files are under `.testeiya/manual-tests/`, say so in the inventory: they came from Testomat.io, not from this repo.
+
+## Step 4: Output
+
+Return one structured markdown result directly. **Do NOT save to a file.**
+
+```markdown
+# Project Overview
+
+- **Project Name:** acme-web-app
+- **Description:** A React-based customer dashboard with an Express API.
+- **Languages:** TypeScript, SQL
+- **Frameworks:** React, Express, Jest, Playwright
+- **Complexity:** small (12 files)
+
+## Test Inventory
+
+- **Automated Tests:** 10 files
+- **Manual Tests:** 37 cases
+
+### Manual Tests (20 of 37 shown)
+
+- SUITE: Authentication
+  |- User can login
+  |- User can reset password
+- SUITE: Billing
+  |- User can view invoice
+  ...and 17 more
+
+### Automated Tests (10 of 10 shown)
+
+- home.page.spec.ts
+...
+```
+
+Field rules:
+- **Description:** 1-2 sentences based only on detected source code and folder structure (include the domain area if that makes sense).
+- **Complexity:** one of `small` | `moderate` | `large` | `very-large`, plus the file count.
+- **Manual Tests:** preserve hierarchy as plain strings — SUITE items as parent bullets, test titles (`|-`) as nested children.
+- **Automated Tests:** list of detected test files.
+- All values must come from observable files. Do NOT guess missing data or add fields not shown above.
+
+Sections:
+- If Step 3 was skipped or found no tests, omit `## Test Inventory` and note that the project contains no tests; the `# Project Overview` section is still useful for next steps.
+- If one test type is absent, note it with a blockquote, e.g. ``> No manual tests (`.test.md`) found in the project.``
+
+Test listing truncation:
+- Show at most the first 20 entries per list, in original file order.
+- Mark truncation in the heading (`(20 of 37 shown)`) and with `...and N more`.
+- Do not print full test listings beyond that.

package/skills/testomatio/test-management/sync-test-cases-with-tms/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: sync-test-cases-with-tms
+description: Synchronize test scenarios and cases between a local project and Testomat.io. Use this skill whenever the user wants to pull/export/download tests from Testomat.io; or push/import/sync new or updated test cases back to the TMS in corresponding `*.test.md` format. Supports custom directories, markdown test format and advanced import/export workflows.
+inputs:
+  testDir:
+    description: "Target directory for pulled tests"
+    required: false
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Sync Test Cases with TMS
+
+Sync Markdown test cases (`*.test.md`) between the local project and Testomat.io.
+
+Use when the user wants to:
+- Pull/export/download tests from Testomat.io to local Markdown files.
+- Push/upload/import local Markdown tests to Testomat.io.
+- Bulk edit: pull cases -> edit locally -> push back to TMS.
+
+## Setup
+
+- Check for the `TESTOMATIO` token: skill input -> `.env` in project root -> ask the user.
+- Save the token to `.env`: `TESTOMATIO=tstmt_xxxxx`.
+- If the user has no key: get it in Testomat.io under **Settings → Project → Project Reporting API key** (`https://app.testomat.io/projects/<project-id>/settings/project`).
+
+## Running the CLI
+
+- Run `check-tests` via `npx`. Do not install it as a project dependency.
+- **The first `check-tests` call in the session must be `npx check-tests@latest …`** to resolve the latest version. All later calls in the same session use plain `npx check-tests …`.
+- **Use only options documented here, in [TESTOMATIO_CLI.md](./references/TESTOMATIO_CLI.md), or listed by `npx check-tests --help`. Do not invent options** (e.g. `--pattern`, `--force`).
+
+## Pull
+
+Downloads test scenarios from Testomat.io and saves them as local Markdown files.
+
+Directory selection — if the `testDir` input is provided or the user passes `-d <path>`, use that path. Otherwise:
+- Workspace is empty or for manual tests only: pull to root.
+- End-to-end testing project: pull to the `manual-tests` directory.
+- Any other case: pull to `.testeiya/manual-tests` (ensure `.testeiya/` exists and is gitignored).
+
+Cache-folder rules:
+- Default pull target is the gitignored cache `.testeiya/manual-tests/`. Add `.testeiya/` to the project `.gitignore` if it is not there yet.
+- **Pulled cases must never land in a tracked folder** (`manual-tests/`, etc.) — that pollutes the repo.
+- Being gitignored does not block editing the files or pushing them back.
+- If the repo already keeps its `*.test.md` files in a tracked folder, don't pull — work with them in place, or pass `-d <that folder>` for an in-place refresh.
+- This matches `scan-automation-project`, which pulls the *code* into `.testeiya/code/` when it runs inside a manual-tests repo.
+
+```bash
+npx check-tests pull -d .testeiya/manual-tests
+```
+
+- To pull only specific suites (user names a suite or gives suite IDs): `npx check-tests pull --suite-ids "@S12345678,@S87654321"`.
+- More pull options: [TESTOMATIO_CLI.md](./references/TESTOMATIO_CLI.md).
+
+## Push
+
+Uploads local Markdown tests to Testomat.io.
+
+Pre-push file filtering — push only test case files, never project docs or requirements:
+- Include files matching `*.test.md`, or Markdown files with valid `<!-- test ... -->` blocks.
+- Ignore all other Markdown (`README.md`, `CHANGELOG.md`, documentation).
+- If test cases live alongside other files, copy or move the test files into `.testeiya/manual-tests/` first.
+
+Pre-push validation:
+1. At least one `*.test.md` file exists.
+2. Each file contains a valid test block:
+
+```md
+<!-- test
+priority: ...
+creator: ...
+tags: ...
+labels: ...
+-->
+# ... (test case title)
+
+... (test case description)
+```
+
+```bash
+# Specific files (preferred when known)
+npx check-tests push --files login.test.md checkout.test.md
+
+# Testeiya cache folder
+npx check-tests push -d .testeiya/manual-tests
+```
+
+- **When the files to push are known** (e.g. just produced by `qa-write-test-cases` / `improve-test-cases`), **pass them explicitly via `--files`** (alias `-f`). Without `--files` the CLI falls back to the default glob `**/*.test.md`, which may pick up unrelated files.
+- Quote glob patterns. Paths resolve relative to `--dir`.
+- Use `-d` when `.testeiya` or `manual-tests` directories exist.
+- **Push only the test cases directory** (e.g. `.testeiya/manual-tests`, not `.testeiya/`).
+- More push options and examples: [TESTOMATIO_CLI.md](./references/TESTOMATIO_CLI.md).
+
+## Summary Output
+
+After syncing, print a short log-style summary:
+
+```
+Sync Complete:
+- Action: pull/push
+- Directory: <path>
+- Tests synced: 15
+- Status: Success
+```

package/skills/testomatio/test-management/sync-test-cases-with-tms/references/TESTOMATIO_CLI.md

@@ -0,0 +1,140 @@
+# Testomat.io CLI Documentation
+
+This document provides comprehensive information about the `check-tests` CLI commands, which synchronizes test scenarios, and interacts with Testomat.io test cases from your local project with TMS.
+
+---
+
+## Prerequisites
+
+### Run check-tests via npx (always latest)
+
+Invoke `check-tests` through `npx` so users automatically pick up the newest published version:
+
+```bash
+# First invocation in the agent session — forces resolve of latest
+npx check-tests@latest <command>
+
+# Subsequent invocations in the same session could be used without @latest
+npx check-tests <command>
+```
+
+Do not install `check-tests` as a project dependency. The first call (with `@latest` version specified) refreshes the npx cache; next calls in the same session reuse it without an extra registry round-trip. A new agent session re-triggers the `@latest` check so users use the latest version over time.
+
+---
+
+## Environment Variables
+
+The tool supports loading environment variables from `.env` files using dotenv.
+
+### Testomat.io Configuration
+
+| Variable                 | Description                                            | Required                              |
+| ------------------------ | ------------------------------------------------------ | ------------------------------------- |
+| `TESTOMATIO`             | API key for Testomat.io (format: tstmt_xxxxx)          | Yes (for sync operations)             |
+| `TESTOMATIO_URL`         | Testomat.io server URL                                 | No (default: https://app.testomat.io) |
+| `TESTOMATIO_WORKDIR`     | Working directory for relative file paths              | No                                    |
+| `TESTOMATIO_PREPEND_DIR` | Directory to prepend to test paths                     | No                                    |
+| `TESTOMATIO_LABELS`      | Comma-separated labels. Supports `label:value`         | No                                    |
+
+### Configuration File
+
+Save credentials to `.env` file:
+
+```env
+TESTOMATIO=tstmt_xxxxx
+TESTOMATIO_URL=https://app.testomat.io
+...
+```
+
+---
+
+## CLI Options
+
+### Basic "check-tests" Options
+
+| Option                | Description                                 | Default                     |
+| --------------------- | ------------------------------------------- | ----------------------------|
+| `-h, --help`          | Display help information                    | -                           |
+| `-d, --dir <dir>`     | Test directory to scan                      | Current dir  (default: `.`) |
+| `--suite-ids <ids>`   | Comma-separated suite IDs to pull (e.g. `@S12345678, @S456r4342`)  | -    |
+
+### Testomat.io Integration Specific Project Options
+
+| Option                        | Description                                                   | Default |
+| ----------------------------- | ------------------------------------------------------------- | ------- |
+| `--update-ids`                | Update test and suite with Testomat.io IDs                    | false   |
+| `--keep-structure`            | Prefer structure of source code over structure in Testomat.io | false   |
+| `--no-empty`                  | Remove empty suites after import                              | false   |
+| `--clean-ids`                 | Remove Testomat.io IDs from test and suite                    | false   |
+
+---
+
+## Commands
+
+### Pull
+
+Retrieve the latest test scenarios from Testomat.io and save them as Markdown files locally.
+
+```bash
+npx check-tests pull [options]
+```
+
+**Examples:**
+
+```bash
+# Export tests to current directory
+npx check-tests pull
+
+# Export tests to manual-tests folder
+npx check-tests pull -d manual-tests
+
+# Keep source structure
+npx check-tests pull -d manual-tests --keep-structure
+
+# Pull specific suites only
+npx check-tests pull --suite-ids "@S12345678,@S87654321"
+```
+
+### Push
+
+Send local Markdown test updates to Testomat.io. (Equivalent to `check-tests manual <files> --update-ids`.)
+
+```bash
+npx check-tests push [options]
+```
+
+`--files` (alias `-f`) accepts file paths, glob patterns, or a mix; defaults to `**/*.test.md`. Paths resolve relative to `--dir`. Quote globs.
+
+**Best practice:** when the files to push are known, list them explicitly via `--files` rather than relying on the default glob.
+
+**Examples:**
+
+```bash
+# Default glob (**/*.test.md)
+npx check-tests push
+
+# Specific files
+npx check-tests push -f docs/login.test.md docs/checkout.test.md
+
+# Glob (quoted)
+npx check-tests push --files "manual-tests/**/*.test.md"
+
+# Multiple globs
+npx check-tests push -f "smoke/**/*.test.md" "regression/**/*.test.md"
+
+# With labels
+TESTOMATIO_LABELS=smoke,updated npx check-tests push
+```
+
+---
+
+## Quick Reference
+
+| Action          | Command                                                        |
+| --------------- | -------------------------------------------------------------- |
+| Pull tests      | `npx check-tests pull -d <dir>`                                |
+| Push files      | `npx check-tests push --files <file1.test.md> <file2.test.md>` |
+| Push glob       | `npx check-tests push --files "<dir>/**/*.test.md"`            |
+| Push directory  | `npx check-tests push -d <dir>` (glob: `**/*.test.md`)         |
+| With labels     | `TESTOMATIO_LABELS=smoke npx check-tests push`                 |
+| Keep structure  | `npx check-tests pull --keep-structure`                        |

package/skills/testomatio/test-management/testomatio-mcp/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: testomatio-mcp
+description: Configures and leverages the Testomat.io MCP server for test management analytics, run analysis, failure investigation, and defect triage. Use when the user needs to connect to Testomat.io via MCP, analyze test runs, cluster failures, investigate root causes.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Testomatio MCP
+
+Set up access to Testomat.io via MCP and run QA analysis workflows: run analysis, failure clustering, root-cause investigation, plan analysis, defect triage.
+
+## When to Use
+
+- Detect or set up the Testomat.io MCP server for an AI agent (Claude, Cursor, OpenCode, etc.).
+- Analyze test runs: recent results, success rates, failure trends.
+- Investigate failures: group similar failures, find patterns.
+- Find the root cause when many tests fail with the same issue.
+- Create defects from failed tests in the user's issue tracker (e.g. Jira).
+
+## MCP Tools
+
+- Test: `tests_list`, `tests_get`, `tests_search`
+- Test Plan: `plans_list`, `plans_get`, `plans_search`
+- Run: `runs_list`, `runs_get`, `runs_search`
+- Testrun (results within a run): `testruns_list`, `testruns_get`
+- Suite: `suites_list`, `suites_get`, `suites_search`
+- Label: `labels_list`, `labels_get`, `labels_create`, `labels_update`, `labels_delete`. Labels may be scoped (`key:value`). Attach or swap them on entities via the `link` parameter — [MCP Setup Reference](./references/MCP_SETUP.md).
+- Tag: `tags_list`, `tags_get`, `tags_search`
+
+**CRUD tools (create, update, delete) exist for all entities. Use them only when explicitly needed for targeted updates.**
+
+## Rules
+
+- **Prefer local tests over MCP.** If the repo contains markdown test cases (`*.test.md`) or automated test files, read them from the filesystem (or load them via the `sync-test-cases-with-tms` skill) instead of using MCP for full test discovery and analysis.
+- Use MCP for:
+  - reading and analyzing run reports
+  - analytics and reporting
+  - test plan management
+  - tests that live exclusively in Testomat.io (no local copies), or quick test case searches (`tests_list`, `tests_search`)
+  - targeted searches and point updates to remote test cases
+- Filter `runs_list`, `plans_list`, `testruns_list` with TQL (Testomat.io Query Language). Operators and examples: [MCP Setup Reference](./references/MCP_SETUP.md).
+
+## Setup
+
+### Step 1: Detect Existing Configuration
+
+Check the user's AI agent config files for a `testomatio` or `mcp.testomatio` entry:
+- `opencode.json`
+- `.cursor/mcp.json`
+- `claude_desktop_config.json`
+- other, based on the user's local agent
+
+Validate:
+- the server is enabled (when the client supports enable/disable flags)
+- `TESTOMATIO_PROJECT_TOKEN` and `TESTOMATIO_PROJECT_ID` are present
+
+Configured and enabled → go to Workflows. Missing, incomplete, or disabled → Step 2.
+
+### Step 2: Configure MCP
+
+Before configuring:
+- Prefer confirming the project contains no more than 1000 tests.
+- If project size cannot be determined, warn the user about MCP performance limits on large projects.
+- **Use only targeted or filtered operations when explicitly requested.**
+
+Credential priority for `TESTOMATIO_PROJECT_TOKEN` and `TESTOMATIO_PROJECT_ID`:
+1. Existing environment variables.
+2. Existing MCP configuration.
+3. User-provided values.
+
+Per-agent config formats (OpenCode, Cursor, Claude Desktop) and where to obtain credentials: [MCP Setup Reference](./references/MCP_SETUP.md).
+
+**Rules:**
+- **Do not overwrite unrelated MCP server configurations.** Merge changes carefully with existing config content.
+- **Do not expose project tokens, secrets, or credentials in chat responses.**
+
+After successful configuration, confirm with a summary:
+
+```text
+Testomat.io MCP configuration completed successfully.
+
+AI Agent: Cursor
+Config Updated: `.cursor/mcp.json`
+MCP Server: Enabled
+Authentication: Verified
+
+Available workflows:
+- Test run analysis
+- Failure clustering
+- Root-cause investigation
+- Plan analysis & defect triage
+```
+
+## Workflows
+
+Common patterns, not a complete list — adapt and extend to the user's needs. All assume the MCP server is enabled.
+
+### Workflow 1: Analyze Test Runs
+
+Goal: understand the health of recent test execution.
+
+1. Call `runs_list` with `tql` filters (e.g. `finished`, `failed`, `with_defect`); narrow scope by status, environment, or plan.
+2. Select a run of interest and call `runs_get` for detailed metadata.
+3. Call `testruns_list` with `run_id` and `filter_status: failed` to extract failed results.
+4. Summarize: total tests, passed, failed, skipped, environments involved.
+   - Compare success/failure ratios across runs to spot regressions.
+
+### Workflow 2: Failure Investigation & Error Clustering
+
+Goal: determine what went wrong and which areas are affected.
+
+1. Call `testruns_list` (`filter_status: failed`, `run_id`) to get failed results.
+2. For each failed testrun, call `tests_get` to map it to its suite, priority, tags, and linked issues.
+3. Cluster failures:
+   - by `suite_id` → identify the suite with the highest failure count
+   - by `message` substring → find tests failing with the same exception or assertion
+4. Present clusters ranked by count, with suite and message breakdowns and affected test titles.
+
+### Workflow 3: Plan Analysis & Root-Cause Detection
+
+Goal: when many tests fail with the same issue, explain the root cause.
+
+1. Call `plans_get` (if a plan is linked to the run) to understand the intended scope; check whether failures correlate with specific plan sections.
+2. Call `runs_list` with `tql` targeting the same plan or environment to get historical runs.
+3. Compare failures across runs:
+   - increasing failure count → new regression
+   - same failures across multiple runs → stable bug or flaky infrastructure
+   - spike in a single suite or tag → localized code change, feature regression
+   - scattered across unrelated suites → systemic issue (infrastructure, config, dependency)
+4. Call `tests_get` on affected tests to check `code`, `state`, and linked issues.
+5. Report a root-cause hypothesis.
+
+Example — user asks: "Check why 20 tests failed in the last run — one suite or a systemic issue?"
+
+```text
+1. Detecting existing Testomat.io MCP configuration:
+   - Found `.cursor/mcp.json`
+   - Found `testomatio` MCP server entry
+   - MCP server status: enabled
+
+2. Verifying MCP availability...
+   - Authentication successful
+   - Testomat.io tools available
+
+3. Analyzing latest test run...
+   - Retrieved last completed run
+   - Total failed tests: 20
+
+4. Failure clustering summary:
+   - 16/20 failures belong to suite: "Checkout / Payments"
+   - 14 failures share the same error: "Timeout waiting for payment confirmation"
+   - First failure timestamp indicates failures started simultaneously
+
+5. Probable root cause:
+   - The failures appear systemic rather than test-specific.
+   - Most failures point to instability or outage in the payment gateway service used during checkout flows.
+```
+
+### Workflow 4: Defect Creation from Failed Tests
+
+Goal: turn recurring failures into trackable defects.
+
+1. Run Workflow 2 to cluster failures by message.
+2. If a cluster contains 5+ tests with the same failure:
+   - propose creating a defect (e.g. Jira issue) to the user
+   - draft the defect summary: title, description, affected test titles, failure messages, run link, environment
+   - if a Jira MCP is available, offer to create the ticket via the Jira skill
+3. After defect creation, call `tests_issues_link` for each affected test to link it to the defect.
+
+### Workflow 5: Update Labels & Tags on Tests
+
+Goal: set, change, or remove labels and tags on tests — for example, update a status label that drives a dashboard chart.
+
+1. Call `labels_list` (or `project_info`) to read the exact label values that exist in the project, including the full `key:value` form of scoped labels. Do not guess label strings.
+2. Optionally find the tests to update with `tests_list` + TQL: `label == 'regression:yes'`.
+3. Update with `tests_update` (or `tests_create`) using the `link` array — one `{ action, type, value }` entry per change. To change a value (e.g. `regression:no` → `regression:yes`), send a `remove` and an `add` in the same call. The same shape works for `tag`, `custom_field`, `milestone`, `issue`, and `jira`.
+
+Link format and a full swap example: [MCP Setup Reference](./references/MCP_SETUP.md).
+
+## Quick Commands
+
+| Action              | MCP Tool        | Key Parameters |
+|---------------------|-----------------|----------------|
+| List failed results | `testruns_list` | `run_id`, `filter_status: failed` |
+| List runs           | `runs_list`     | `tql`, `page`, `per_page` |
+| Get run details     | `runs_get`      | `run_id` |
+| Get test details    | `tests_get`     | `test_id` |
+| Get plan details    | `plans_get`     | `plan_id` |
+| Link issue to test  | `tests_issues_link` | `test_id`, `url` or `jira_id` |
+| List labels         | `labels_list`   | `page`, `per_page` |
+| Set / swap label on test | `tests_update` | `test_id`, `link` |
+| Find tests by label | `tests_list`    | `tql: label == '...'` |
+| Check server status | `system_ping`   | none |