testeiya 0.2.0

package/skills/testomatio/test-management/qa-write-test-cases/references/testomat-tms-guide.md

@@ -0,0 +1,72 @@
+---
+title: Testomat.io TMS Integration Guide
+description: Essential reference for generating Testomat.io-compatible test cases. Covers structure, MCP tools, conventions, and best practices.
+---
+
+# Testomat.io TMS Integration Guide
+
+Quick reference for generating test cases compatible with Testomat.io Test Management System.
+
+Follow this guide along with [Test Case Format](./test-case-format.md).
+
+## Structure
+
+```
+Folder (top-level)
+└── Suite {title} (@S{id})
+    └── Test {title} (@T{id}) → has tags (e.g. @smoke), labels, priority (e.g. high)
+```
+
+Priority values: `critical`, `high`, `normal`, `low`.
+
+## Key MCP Tools
+
+| Purpose         | Entities / tools                                                                           |
+| --------------- | ------------------------------------------------------------------------------------------ |
+| **Structure**   | `suites_list`, `suites_search`, `tests_list`, `tests_search`, `steps_list`, `steps_search` |
+| **Conventions** | `tags_list`, `labels_list`                                                                 |
+
+**Key actions:**
+
+- `tests_search` - **Always use before creating new cases** to avoid duplicates
+- `steps_search` - Find reusable shared steps before writing new ones
+
+## Use tags and labels
+
+Add them based on context, user prompt, existing tags and labels.
+
+Split tests by module, testing type, scope and other criteria which helps to organize and filter tests.
+
+### When to use Tags vs Labels
+
+| Aspect          | Tags                                   | Labels                                |
+| --------------- | -------------------------------------- | ------------------------------------- |
+| **Best for**    | Broad categorization                   | Specific metadata                     |
+| **Use for**     | Test type (@smoke, @regression, @e2e)  | Priority, severity, status, ownership |
+| **Flexibility** | Constant, embedded in code             | Flexible, easy to change via UI       |
+| **Values**      | Single tag per category                | Multiple values per label allowed     |
+| **Examples**    | `@smoke`, `@api`, `@auth`, `@checkout` |                                       |
+
+**Rule of thumb:** Use tags for test categorization and automation; use labels for test metadata, workflow tracking, and manual test management.
+
+## Deduplication Workflow
+
+```
+1. tests_search() → Find existing tests
+2. Compare → Exact match? → Notify user, let user decide to skip or not
+3. Partial overlap? → Ask user
+4. No match? → Create new test cases
+```
+
+## Quality Checklist
+
+- [ ] Followed template format
+- [ ] Priority set
+- [ ] Tags/labels added
+- [ ] Clear steps
+- [ ] No duplicates
+
+## References
+
+- [Testomat.io Docs](https://testomat.io/docs)
+- [Test Case Format](./test-case-format.md) - Full Markdown format reference

package/skills/testomatio/test-management/qa-write-test-cases/references/writing-rule.md

@@ -0,0 +1,159 @@
+# Test Writing Rules
+
+If the user provided example test cases, follow their style first; then apply these rules.
+
+## Test Suites
+
+- Formulas, business rules, edge-case reasoning, and feature context live in the suite/test description.
+- Prerequisites common to all test cases go as bullet points in the suite description.
+- Formulas and diagrams relevant to all test cases can be included as code blocks in the suite description.
+
+## Test Cases
+
+- A test case consists of a description and steps.
+- Golden rule: "why" in the description, "what" in the steps.
+- Add the intent to the description if the title is not enough to explain it.
+- Keep the description clear and concise.
+- Put preparations into preconditions/description, not into steps.
+- Focus on black-box testing: every action and observable result goes through public APIs or UI (unless the user specifies otherwise).
+- Prefer UI over public APIs when possible.
+- Add system checks only when it is not clear how to test via public APIs or UI. This is not a unit test; usually no direct server or code access is allowed.
+- Understand UI pages, components, or API endpoints from source code, design, or requirements.
+- If this is a web app, ask the user to help discover it:
+  - by looking at its frontend source code
+  - by accessing it on a non-production environment via browser (URLs and credentials)
+  - by looking at screenshots of related pages
+
+## Title
+
+Title states the behavior under test from the user's perspective.
+
+Title structure: `<role> <action> <object> <qualifier>`
+
+Examples:
+
+- Editor can change description of a blogpost in admin panel
+- User can report a bug using widget on a web page
+- Blocked user must not be able to log in to app workspace
+- Admin can invite up to 10 users to a project via Settings Page
+- User can not edit a comment it doesn't own
+- User can retry operation when NetworkError occurs
+- User can not retry operation when network connection is disabled
+
+Avoid:
+
+- Filler prefixes: `Verify that ...`, `Test that ...`, `Check ...`, `Should ...`
+- Multi-intent titles joined by `and` / `then`
+- Restating the suite name in every title
+- Embedding IDs or numbers: `TC-001: Login`
+- Vague outcomes: `Successful login`, `Login works`
+
+Good vs bad:
+
+- `Verify successful login` → `User can log in with valid email and password`
+- `Wrong password test` → `User cannot log in with invalid password`
+- `Login and update profile` → split into two tests
+- `Email validation` → `User sees error when email format is invalid`
+
+## Preconditions
+
+- Add preconditions for setup that is required for the test to run but is not part of the test actions.
+- Define the preconditions and initial state of the system as bullet points.
+- If relevant, include the user role.
+- Skip preconditions that are not needed or repeat the suite description.
+- Do not include preconditions like "service is running" unless the user explicitly mentioned them or the test is about them.
+
+## Steps
+
+A step consists of an action (with optional test data) and an expected result.
+
+Test steps use the `## Steps` header section with a nested markdown list format:
+
+```markdown
+## Steps
+
+- (Step Action)
+  *Expected*: ... (Observable behavior)
+- ...
+  *Expected*: ...
+```
+
+e.g.
+
+```markdown
+## Steps
+
+- Navigate to the login page
+  *Expected*: Login form is displayed with username and password fields
+- Enter a valid username and password
+  *Expected*: Credentials are entered without errors
+- Click the "Login" button
+  *Expected*: User is redirected to the dashboard
+```
+
+Step format rules:
+
+- Steps must be under a `## Steps` heading.
+- Use nested markdown lists (bulleted `-`/`*` or numbered `1.`).
+- Top-level items describe the action to perform.
+- Nested items with `*Expected*` (or `*Expected*:`, `*Expected result*`) describe the observable behavior.
+- Expected results should be specific and verifiable.
+
+Step content rules:
+
+- Each step is a simple sentence. Avoid commas and sub-sentences.
+- Steps are mechanical: click, send, read, assert.
+- Each step includes exact instructions with concrete, realistic values a tester can act on directly.
+- Do NOT parametrize by default — first-pass test cases should read as executable manual steps, not templates.
+- Use a placeholder variable like `${domain}` only when the value is genuinely reused across steps or is data-driven (see the Examples section in the format reference). A plain UI/API acceptance step needs concrete values, not placeholders.
+- Do not turn data unrelated to the test into placeholders.
+- Do not add preconditions as placeholders.
+- Prefer URL paths over full URLs, e.g. `/auth/login`.
+- Use specific values when they are important for the scenario (boundary values, format validation, locale-specific input).
+- Avoid vague qualifiers like "small", "known", "around", "e.g.", "like", "(…)"; replace them with concrete, literal values.
+- Avoid general statements in steps. Move them to the description.
+- Do not chain multiple distinct actions or use unnecessary And / Or combinations in a single step.
+- All step actions must be clear to perform via public API or UI.
+- All checks/verifications/assertions belong in the expected result, not in the step action.
+- A code block may follow a step when needed: API request, SQL, shell command, pseudocode, etc.
+
+If an expected result has multiple conditions, split them into separate lines.
+
+Instead of:
+
+`*Expected*: Comment appears in the Run's comment list with the current user as author`
+
+Use:
+
+`*Expected*: Comment appears in the Run's comment list`
+`*Expected*: Current user is the author`
+
+### Bold and italic in steps
+
+Use sparingly. Each style serves one purpose; otherwise write plain text.
+
+- **bold** — UI elements the user interacts with: buttons, links, fields, tabs, checkboxes, modals (e.g. `Click **Save**`, `Open **Settings** tab`).
+- *italic* — names of pages/screens/documents referenced as context (e.g. `Open the *Privacy Policy* page`).
+
+Avoid:
+
+- Bold/italic on full sentences or whole steps.
+- Combining bold and italic (`***...***`).
+- Emphasis for visual weight; rephrase or split the step instead.
+- Bold/italic in place of a placeholder (`[url]`) or a code block.
+
+## AI Writing Patterns to Avoid
+
+Be specific, not grandiose. Say what it actually does. Avoid marketing language and emojis (unless explicitly intended).
+
+Avoid:
+
+- Puffery: pivotal, crucial, vital, testament, enduring legacy, indelible mark, deeply rooted, profound heritage, steadfast dedication, key turning point
+- Promotional adjectives: groundbreaking (figurative), seamless/seamlessly, robust, cutting-edge, vibrant, nuanced, multifaceted, intricate/intricacies, stunning natural beauty
+- Overused AI vocabulary: delve/delves, leverage/leveraging, foster/fostering, realm, tapestry, landscape, interplay, streamline, shed light on, garnered, notably, key (as adjective)
+- Empty "-ing" phrases: ensuring, showcasing, highlighting, emphasizing, reflecting, underscoring, aligning with, contributing to, enhancing, underpinning
+- Filler frames: stands/serves as, is a testament/reminder, plays a vital/significant/crucial/pivotal role, underscores/highlights its importance, reflects broader, symbolizing its ongoing/enduring/lasting impact, continues to captivate, nestled in the heart of, boasts a
+- Hedges and closers: it's important/critical/crucial to note/remember/consider, may vary, In summary, In conclusion, Overall
+- "Challenges/Legacy" framing: Despite its... faces several challenges, Despite these challenges, Challenges and Legacy, Future Outlook
+- Parallel "not/but/however" constructions: "Not only ... but ...", "It is not just about ..., it's ..." — common in LLM writing but unsuitable for a neutral tone
+- Formatting overuse: excessive bullets, emoji decorations, bold on every other word

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`                        |