testeiya 0.2.1 → 0.3.1-0.1

package/skills/codeceptjs/writing-codeceptjs-tests/SKILL.md

@@ -1,206 +1,102 @@
 ---
 name: writing-codeceptjs-tests
-description: Use when writing a new CodeceptJS 4 test, extending an existing Scenario, or porting a manual test plan to code. Builds tests live — opens the real page through the CodeceptJS MCP server, queries ARIA/HTML to learn locators, runs each step incrementally to verify it works, then commits the verified sequence to a test file. Two authoring modes — Mode A (incremental `run_code`) for known flows, Mode B (scaffold-and-pause — write `I.amOnPage(...); pause();`, run via MCP, drive the live browser, replace `pause()` with the verified sequence) for greenfield / unknown flows. Never invents locators or flows from imagination; drives the actual browser. Trigger on any request to create, write, add, draft, or scaffold a CodeceptJS test, login flow, end-to-end check, or "test from scratch".
+description: >
+  Use when creating a new CodeceptJS 4 test, extending an existing Scenario, or
+  porting a manual test plan to code. Builds tests against the live browser via
+  the CodeceptJS MCP server — never from imagined locators or flows. Trigger on
+  any request to create, write, add, draft, or scaffold a CodeceptJS test,
+  login flow, end-to-end check, or "test from scratch".
 ---
 
 # Writing CodeceptJS 4 Tests
 
-A test that was never executed during authoring is unreliable by definition. The right way to write a Scenario is to drive the real browser through the CodeceptJS MCP server, query the page to learn locators, and only commit steps that actually pass. This skill is the playbook for that loop.
+A test that was never executed during authoring is unreliable. Drive the real browser via the CodeceptJS MCP server, verify every locator against the live page, commit only steps that passed.
 
-Two authoring modes, picked by how much of the flow you already know:
+Two modes, picked by how much of the flow you already know:
 
-- **Mode A — incremental `run_code`** — send one or two `I.*` lines per `run_code`, read the response, repeat. Suited to extending an existing test or porting a manual plan with known steps.
-- **Mode B — scaffold-and-pause** (recommended for greenfield / unknown flows) — write a stub `Scenario` containing `I.amOnPage('/...'); pause();`, run via MCP `run_test`. The browser opens and yields control at `pause()` on the live container. Drive the page through `run_code` to discover the flow, then edit the test to replace `pause()` with the verified sequence and re-run.
+- **Mode A — incremental `run_code`**: send one or two `I.*` lines per call, read response, repeat. For extending existing tests, known flows, porting manual plans.
+- **Mode B — scaffold-and-pause** (recommended for greenfield / unknown flows): write a stub Scenario containing `I.amOnPage('/...'); pause();`, run via MCP `run_test`. The browser opens and yields control at `pause()` — drive the live page via `run_code`, then replace `pause()` with the verified sequence.
 
-Both modes share the discovery / locator / commit steps below; the difference is just *where the in-flight exploration happens*.
+Both share the same discovery / locator / commit steps; the difference is *where the in-flight exploration happens*.
 
 ## Workflow
 
-### 1. Read the project (fundamentals)
-Run the **codeceptjs-fundamentals** skill first. You need: active web helper, base URL, plugins (especially `aiTrace`, `auth`), AI provider, page-object names, env vars.
-
-### 2. Map what's already there
-Before adding anything, enumerate:
-- `npx codeceptjs check -c <config>` — verifies the setup loads (config, helpers, plugins, page objects, hooks, tests, defs). Each pass/fail line doubles as an inventory of what the project has wired up.
-- `npx codeceptjs list -c <config>` — every available `I.<method>` for the active helpers, including custom ones. Check before suggesting any method.
-- `npx codeceptjs dry-run -c <config>` — every Scenario the active config would load, with naming conventions and tags. Add `--steps` to also print queued `I.*` calls, `--numbers` for step indices.
-- MCP equivalents: `list_actions`, `list_tests`.
-
-This catches duplication, surfaces patterns the new test should follow, and confirms a custom step / page-object method doesn't already cover the planned flow.
-
-> ⚠ `dry-run` does **not** initialize plugins. The `auth` plugin's injected `login(...)` (and any other plugin-injected function) is undefined under `dry-run`, so `Before(({ login }) => login('admin'))` raises **"login is not a function"** even though the actual `run` works fine. Use `--steps` to inspect Scenario shape; ignore plugin-inject errors. To verify auth works, do a real `run` (or MCP `run_test`).
-
-### 3. Decide if auth is needed
-If the path under test sits behind login, invoke the **codeceptjs-auth** skill:
-- If `auth` is already configured, use the existing role: `Before(({ login }) => login())`.
-- If not, the auth skill walks through adding the plugin and env-var credentials.
-- Public path? Skip.
-
-### 4. Look for similar tests and page objects
-Before writing anything new, scan:
-- existing Scenarios that touch the same feature area
-- page objects in the directories registered under `include`
-- custom steps in the actor file
-- data factories that already create the entities the test needs (user, post, …)
-
-If a page-object method already encodes the locators for this area, drive through it (`profilePage.openSettings()`) instead of writing raw `I.click` chains.
-
-### 5. Identify the starting page
-The page where the new test does its work, **after** any auth. Get a real URL, not a guess. Look for similar tests and page objects. If you don't have that data, ask user where to start. CodeceptJS always use relative urls. The host must be set inside config (helpers.Playwright.url or helpers.WebDriver.url or helpers.Puppeteer.url)
-
-### 6. Make sure aiTrace + MCP are wired
-- **aiTrace under MCP** — auto-enabled. The MCP server forces `plugins.aiTrace = { on: 'step', enabled: true }` for every session (`bin/mcp-server.js`), so you do **not** need to add it to the project config when authoring through MCP. The user can override with `start_browser({ plugins: { aiTrace: { enabled: false } } })`.
-- **aiTrace for CLI runs** — *not* auto-enabled. Either add `plugins: { aiTrace: { enabled: true } }` to the active config, or pass `-p aiTrace` on the runner. Without it, the verification run in step 10 produces no `output/trace_*/` artifacts and `codeceptjs-run-analysis` has nothing to read.
-- **MCP** — confirm the AI client points at `node_modules/codeceptjs/bin/mcp-server.js` with `CODECEPTJS_CONFIG` and `CODECEPTJS_PROJECT_DIR` set. See `node_modules/codeceptjs/docs/mcp.md` if it isn't.
-- **Headless** — run tests headlessly by default. Either rely on `setHeadlessWhen(CI)` (export `CI=1` for the session) or set `show: false` in the helper config.
-
-### 7. Open a live session via MCP
-
-Pick a mode:
-
-**Mode A — incremental `run_code`** (existing test extension, known flow):
-Send a minimal scaffold to MCP `run_code` — `login(<role>)` if auth is needed, then `I.amOnPage(<starting URL>)`. The response includes URL, ARIA snapshot, screenshot, and console logs. This is the ground truth for everything that follows.
-
-**Mode B — scaffold-and-pause** (greenfield / unknown flow):
-Write a draft test stub directly in the test file — minimal but real. For a public page:
-
-```js
-Scenario('draft - feature exploration', ({ I }) => {
-  I.amOnPage('/')
-  pause()
-})
-```
-
-…or with auth:
-
-```js
-Before(({ login }) => login('admin'))
-
-Scenario('draft - feature exploration', ({ I }) => {
-  I.amOnPage('/dashboard')
-  pause()
-})
-```
-
-Run it via MCP `run_test`. The browser opens, navigates, and yields control at `pause()` — the response carries `{ status: 'paused', pausedAfter, page, suggestions }`. The same `I` / browser the test is using is now driven by `run_code` against the live page.
-
-### 8. Learn the page and pick locators
-Hand off to the **codeceptjs-exploration** skill: read the ARIA snapshot first, fall back to HTML when needed, and use `I.grabWebElement` / `I.grabWebElements` (with permissive XPaths when the obvious locator misses) to enumerate and disambiguate candidates. Commit a locator only after verifying it matches exactly one element via MCP `run_code`. In Mode B, this exploration happens *during the pause window* — the page is sitting there waiting for you.
-
-Translate devtools-style strict locators to readable form **before** they hit the test file — see the **Locators** section below.
-
-### 9. Build the Scenario via MCP
-
-**Mode A** — for each user goal (fill a field, click a button, see a confirmation), run one or two CodeceptJS commands through MCP `run_code`, then read the response.
-
-**Mode B** — work the live page from the pause: try one or two `I.*` lines via `run_code`, read the response, navigate the next step. Each successful command goes into a scratchpad you'll paste back into the test file in step 10. When you've reached the end of the flow you wanted, the scratchpad is your verified sequence.
-
-After every command (either mode) ask:
-- Did the URL or ARIA change the way you expected?
-- Any new errors in the console logs?
-- Does a `grab*` value match what was expected?
-
-If a step fails — try a different locator, add a `waitFor*`, or reconsider the flow. **Stop and ask the user** when something is genuinely ambiguous (two "Save" buttons; an unclear empty state; a feature flag that might not be enabled). Don't push through.
-
-### 10. Commit the verified sequence
-When every step has worked once in isolation, paste them into a test file:
-- Match existing file naming and the **one-Feature-per-file** rule.
-- Use a page-object method or custom step wherever one fits — don't duplicate selectors.
-- **Translate every locator to its readable form** (see the **Locators** section). No `{ css: 'input[placeholder*="…"]' }`, no `{ xpath: '//tr[contains(.,…)]//…' }` in committed code. Strict locators are a code-review red flag unless nothing semantic, ARIA, or `locate()`-shaped fits.
-- Wrap secrets with `secret(...)`; pull credentials from env vars only.
-- Add the tag the suite already uses (`{ tag: '@smoke' }`) when relevant.
-- **Mode B specific** — replace the `pause()` line with the verified sequence above it. Remove the `draft` Scenario name and rename to its real intent. Don't leave `pause()` in a committed test.
-- Run the file end-to-end with `aiTrace` enabled: `npx codeceptjs run --grep '<scenario name>' --steps`. Hand the result to **codeceptjs-run-analysis** — it reads `output/trace_*/` artifacts via bash tools so you can confirm the flow ran clean. Only declare done when the scenario passes there.
-
-## Locators — readable, semantic, scoped
-
-Pick the highest-level form that fits. Priority, top wins:
-
-1. **Dedicated test attributes** — when the page consistently exposes `data-testid` / `data-qa` / similar. Stable by design.
-   ```js
-   I.click('[data-testid="submit-order"]')
-   ```
-2. **Semantic + context** — plain string (label / button text / placeholder / `aria-label`).
-   ```js
-   I.click('Save', '.toolbar')
-   I.fillField('Email', 'u@t.com', '#login-form')
-   ```
-3. **ARIA role** — survives markup churn; doubles as accessibility check.
-   ```js
-   I.click({ role: 'button', name: 'Sign In' })
-   ```
-4. **`locate()` builder** — for structural conditions, repeated row/cell targeting, anything CSS can't express in one line.
-   ```js
-   I.click(locate('button').withText('Edit').inside(locate('tr').withText('Acme Corp')))
-   ```
-5. **Strict `{ id }` / `{ name }` / `{ css }`** — when nothing above fits.
-   ```js
-   I.fillField({ id: 'email' }, 'u@t.com')
-   I.seeElement({ css: '.invoice-row.paid' })
-   ```
-6. **`{ xpath }`** — last resort, for axes (`ancestor`, `following-sibling`) or text predicates the builder doesn't cover.
-   ```js
-   I.click({ xpath: '//button[@aria-pressed="true"]' })
-   ```
-
-If item 1 applies broadly across the app, enable the **`customLocator` plugin** so `$name` resolves to the configured attribute. Once it's on:
-
-```js
-// before                                      // after, with customLocator: { attribute: 'data-qa' }
-I.click({ css: '[data-qa=submit]' })           I.click('$submit')
-I.fillField({ css: '[data-qa=email]' }, ...)   I.fillField('$email', ...)
-```
-
-See `node_modules/codeceptjs/docs/plugins.md` § *customLocator*.
-
-### Context
-
-Most actions accept a **context** as the last argument — any locator type. The lookup runs only inside that region, which disambiguates duplicate labels and keeps semantic strings usable. When several actions target the same region, bind the locator once and reuse it; do not repeat the chain inline.
-
-Prefer stable structural regions — they survive UI rewrites better than the markup they wrap:
-
-- Landmark elements — `nav`, `main`, `header`, `footer`, `aside`, `{ role: 'dialog' }`, `{ role: 'navigation' }`.
-- App-shell containers — `.main-app`, `.app-content`, `.sidebar`, `.toolbar`, `.modal`, `.drawer`.
-- A row, card, or list item identified by its data, expressed via `locate(...)`.
-
-**`I.see` and `I.dontSee` require a context.** Their first argument is plain text matched across the page, so without a context the assertion can resolve against navigation, a footer, or an unrelated component and produce a false pass. Other assertions (`I.seeElement`, `I.seeNumberOfElements`, etc.) take an explicit locator, which scopes them on its own.
-
-### Picking a specific match
-
-When a locator matches several elements, CodeceptJS uses the first by default. To target another match without writing a more specific locator, pass `elementIndex` via `step.opts()` (`import step from 'codeceptjs/steps'`) — accepts a 1-based number, a negative index, or `'first'` / `'last'`. Same path for `step.opts({ exact: true })` to make a single step throw on ambiguity. See `node_modules/codeceptjs/docs/locators.md` § *Picking a specific element*.
-
-Full reference: `node_modules/codeceptjs/docs/locators.md`.
-
-## Waiting
-
-CodeceptJS auto-waits before each action, but explicit waits are still needed when:
-- a **loader / spinner / skeleton** must hide before the next step → `I.waitForInvisible('.spinner')`, `I.waitForDetached('.skeleton')`
-- a **modal / drawer / panel / section** hasn't rendered yet → `I.waitForVisible('.modal')`, `I.waitForElement({ role: 'dialog' })`
-- **data must finish loading** — list rows, cards, charts, async text → `I.waitForElement('.user-row', 10)`, `I.waitForText('Loaded', 10, '.status')`
-
-Detect what to wait for by reading the page HTML / ARIA between MCP steps. If the next element is gated by a spinner overlay or rendered after a fetch, scroll the markup until you find the gating element, pick a stable selector, and wait for the right state (visible, invisible, detached, text-present).
-
-`I.wait(N)` (raw seconds) is OK during **authoring** to confirm a timing hypothesis — if a 5-second sleep makes the step pass, the cause is timing. **Replace it with a specific `I.waitFor*` before committing.** Hardcoded sleeps are slow on fast machines, flaky on slow ones, and hide the real sync point.
+1. **Fundamentals first** — run `codeceptjs-fundamentals`. You need: active web helper, base URL, plugins (`aiTrace`, `auth`), AI provider, page objects, env vars.
+2. **Map what's already there** — `check` / `list` / `dry-run` (see fundamentals § Discover). Catches duplication and confirms no custom step or page-object method already covers the planned flow.
+   - ⚠ `dry-run` does **not** initialize plugins: `Before(({ login }) => login('admin'))` raises "login is not a function" under dry-run even though a real run works. Inspect shape with `--steps`; ignore plugin-inject errors; verify auth with a real run.
+3. **Auth** — path behind login → invoke the `codeceptjs-auth` skill. Existing role configured: `Before(({ login }) => login())`. Not configured: auth skill walks adding it. Public path: skip.
+4. **Similar tests & page objects** — scan Scenarios in the feature area, POs under `include`, actor-file custom steps, data factories. If a PO method already encodes this area's locators, drive through it instead of raw `I.click` chains.
+5. **Starting page** — a real URL *after* any auth, not a guess; ask the user if unknown. Relative URLs only — host lives in the config (`helpers.Playwright.url` etc.).
+6. **aiTrace + MCP wiring**:
+   - Under MCP: `aiTrace` is forced on by the MCP server — nothing to configure.
+   - CLI runs: *not* auto-enabled — declare in config or pass `-p aiTrace`, or step 11 produces no `output/trace_*/` artifacts for run-analysis.
+   - Run headless by default (`setHeadlessWhen(CI)` with `CI=1` exported, or `show: false`).
+   - Confirm MCP client points at `node_modules/codeceptjs/bin/mcp-server.js` with `CODECEPTJS_CONFIG` and `CODECEPTJS_PROJECT_DIR` set.
+7. **Open a live session** (pick mode):
+   - Mode A: `run_code` scaffold — `login(<role>)` if needed, then `I.amOnPage(<start URL>)`. The response (URL, ARIA snapshot, screenshot, console) is ground truth for everything after.
+   - Mode B: write a minimal-but-real draft in the test file:
+     ```js
+     Before(({ login }) => login('admin'))   // if needed
+
+     Scenario('draft - feature exploration', ({ I }) => {
+       I.amOnPage('/dashboard')
+       pause()
+     })
+     ```
+     Run via MCP `run_test` → `{ status: 'paused', pausedAfter, page, suggestions }`. The test's own `I` / browser is now driven by `run_code`.
+8. **Learn the page** — hand off to `codeceptjs-exploration`: ARIA snapshot first, HTML fallback, enumerate and disambiguate candidates, commit a locator only after verifying it matches exactly one element via `run_code`. In Mode B this happens inside the pause window.
+9. **Build the Scenario** — one or two commands at a time via `run_code` into a scratchpad. After each ask: did URL/ARIA change as expected? New console errors? Do grabbed values match expectations?
+   - Step failed → try a different locator, add a specific `waitFor*`, or reconsider the flow.
+   - Genuinely ambiguous (two Save buttons, unclear empty state, possible feature flag) → **stop and ask the user**.
+   - Optional UI elements (cookie banners) → `await tryTo(...)` instead of `if` (fundamentals § Effects) — keeps scenarios linear.
+10. **Commit the verified sequence**:
+    - Match existing naming; one `Feature` per file.
+    - Use page-object methods / custom steps where they fit — don't duplicate selectors.
+    - Translate every locator to readable form (priority below). Strict `{ css }` / `{ xpath }` in committed code are a review red flag unless nothing else fits.
+    - Credentials from env vars only, wrapped in `secret(...)`.
+    - Mode B: replace the `pause()` line with the sequence; rename `draft - ...` to the real intent.
+11. **Final verification**: `npx codeceptjs run --grep '<scenario>' --steps` with aiTrace enabled → hand output to `codeceptjs-run-analysis` to confirm the flow ran clean in `output/trace_*/`. Done only when it passes there.
+
+## Locator priority (writing time)
+
+Always pass context — see `codeceptjs-fundamentals` § Locators for rationale. Top wins:
+
+1. **Semantic string** — visible text, label, placeholder, `name`, `aria-label`: `I.click('Save', '.toolbar')`
+2. **ARIA role** — text ambiguous within context ("Delete" link *and* button), or role part of the assertion: `I.click({ role: 'button', name: 'Sign In' }, '#login-form')`
+3. **`$name` via `customLocator`** — app exposes `data-testid`/`data-qa` broadly
+4. **`locate()` builder** — structural conditions; often the structural half belongs in the context: `I.click('Edit', locate('tr').withText('Acme Corp'))`
+5. **Strict `{ id }` / `{ name }` / `{ css }`** — last resorts above exhausted
+6. **`{ xpath }`** — axes / text predicates the builder can't express
+
+Writing-time specifics beyond fundamentals:
+
+- Plain strings already match `aria-label` — never write `'aria-label=Save'` or `{ css: '[aria-label="Save"]' }`.
+- Prefer stable contexts: landmarks (`nav`, `main`, `{ role: 'dialog' }`), app-shell containers (`.sidebar`, `.modal`), rows/cards identified by their data.
+- **`I.see` / `I.dontSee` require a context** — their first arg is plain text matched across the whole page; unscoped they can false-pass on nav/footer content.
+- Several matches → `step.opts({ elementIndex: N })` (1-based, negative, `'first'`/`'last'`) or `step.opts({ exact: true })`; import `step` from `codeceptjs/steps`.
+
+## Waiting while authoring
+
+- Auto-waiting covers interactions; detect gating elements (spinner overlay, post-fetch render) from the live HTML/ARIA between MCP steps → pick the stable selector and a specific `waitFor*`.
+- `I.wait(N)` is acceptable **during authoring** to confirm a timing hypothesis — if a sleep makes the step pass, timing is the cause. Replace with the specific `waitFor*` before committing.
 
 ## Things to avoid
 
-- Writing tests from imagined locators or imagined routes.
-- Defaulting to strict `{ css }` / `{ xpath }` locators when a semantic string, ARIA role, or `locate()` chain would do. See the **Locators** section.
-- Hardcoding credentials anywhere — env vars + `secret()` only.
-- Skipping the page-object scan.
-- Adding `await` to plain action steps (see fundamentals' `await` rule).
-- Adding `waitFor*` speculatively before checking whether auto-waiting already handles it.
-- Leaving `I.wait(N)` (raw seconds) in committed tests — replace with a specific `waitFor*`.
-- Leaving the `pause()` from Mode B's stub in the committed test — it must be replaced with the verified sequence before the file is done.
-- Using Mode A when the flow is genuinely unknown — round-tripping `run_code` for every step is slower than Mode B and easier to lose track of state in.
-- Declaring the test done without running the committed file end-to-end with `aiTrace` enabled.
-
-## Pointers
-
-- `node_modules/codeceptjs/docs/basics.md` — locators, assertions, waits, hooks
-- `node_modules/codeceptjs/docs/test-structure.md` — Feature/Scenario syntax
-- `node_modules/codeceptjs/docs/locators.md`, `docs/element-selection.md`
-- `node_modules/codeceptjs/docs/pageobjects.md`, `docs/sessions.md`, `docs/within.md`
-- `node_modules/codeceptjs/docs/data.md` — REST helper, Data Objects
-- `node_modules/codeceptjs/docs/mcp.md` — MCP tool list and client config
-- `node_modules/codeceptjs/docs/secrets.md` — `secret()` wrapper
+- Writing tests from imagined locators or routes — everything from the live page.
+- Strict locators where semantic / ARIA / `locate()` fits.
+- Long unscoped locators instead of short locator + context.
+- Spelling out accessible names or repeating `[data-testid=...]` at call sites.
+- Hardcoded credentials anywhere.
+- Skipping the similar-test / page-object scan.
+- `await` on plain action steps (fundamentals await rule); speculative `waitFor*` before checking auto-waiting.
+- Leaving `I.wait(N)` or `pause()` in committed tests.
+- Using Mode A for genuinely unknown flows — slower than Mode B, easier to lose state.
+- Declaring done without the end-to-end aiTrace run.
+
+## Related skills
+
+- `codeceptjs-fundamentals` — rules, effects, discovery (run first)
+- `codeceptjs-exploration` — page inspection, WebElement API
+- `codeceptjs-auth` — login/session reuse
+- `codeceptjs-run-analysis` — trace verification
+- `debugging-codeceptjs-tests` — when the committed test misbehaves

package/skills/{playwright-best-practices-skill → playwright/playwright-best-practices}/SKILL.md

@@ -4,7 +4,7 @@ description: Use when writing Playwright tests, fixing flaky tests, debugging fa
 license: MIT
 metadata:
   author: currents.dev
-  version: "1.1"
+  version: "1.2"
 ---
 
 # Playwright Best Practices

package/{skills.lock.json → skills/skills.lock.json}

@@ -2,59 +2,66 @@
   "sources": [
     {
       "source": "testomatio/skills",
-      "ref": "feat/setup-pr-testing-skill",
-      "sha": "99a6808422ff9e3a6bd46edab04a32d37a6ed028",
+      "ref": null,
+      "sha": "84d855c359df6bf13bde7749ec3ec8d31e9fc51d",
       "folder": "testomatio",
       "skills": [
-        "testomatio-mcp",
-        "sync-test-cases-with-tms",
-        "scan-automation-project",
-        "qa-write-test-cases",
-        "qa-thinking",
-        "qa-test-code-coverage",
-        "qa-requirement-reviewer",
-        "qa-pr-requirements-analyzer",
-        "qa-e2e-tests-reporting",
-        "pull-request-diff-analyzer",
-        "improve-test-cases",
         "detect-duplicate-test-cases",
-        "setup-pr-testing",
-        "run-tests-with-testomatio-reporter",
-        "qa-automation-test-consolidation",
-        "debug-fix-failed-flaky-autotests",
+        "improve-test-cases",
+        "pull-request-diff-analyzer",
+        "qa-e2e-tests-reporting",
+        "qa-pr-requirements-analyzer",
+        "qa-requirement-reviewer",
+        "qa-split-testing-levels-pyramid",
+        "qa-sprint-report-by-testomatio",
+        "qa-test-code-coverage",
+        "qa-thinking",
+        "qa-write-test-cases",
+        "scan-automation-project",
+        "sync-test-cases-with-tms",
+        "testomatio-mcp",
         "automate-manual-test-cases",
+        "debug-fix-failed-flaky-autotests",
+        "qa-automation-test-consolidation",
+        "qa-data-seeder",
+        "run-tests-with-testomatio-reporter",
+        "setup-change-aware-pr-testing",
+        "setup-ci-automation",
         "testomat-allure-adapter",
-        "explorbot-setup",
+        "qa-explain-behavior",
+        "qa-lead-strategy-advisor",
+        "testing-workflow",
+        "explorbot-fundamentals",
         "explorbot-plan",
-        "explorbot-fundamentals"
+        "explorbot-setup"
       ]
     },
     {
       "source": "codeceptjs/skills",
       "ref": null,
-      "sha": "e19ba9d0f513cbc9c3e4a4c5c6dd02cfedde4afd",
+      "sha": "d3d6a4e0e29207b1afb051eeb6f5f36984f4752b",
       "folder": "codeceptjs",
       "skills": [
-        "writing-codeceptjs-tests",
-        "refactoring-codeceptjs-tests",
-        "migrate-testcafe-to-codeceptjs",
-        "migrate-selenium-java-to-codeceptjs",
-        "migrate-protractor-to-codeceptjs",
-        "migrate-cypress-to-codeceptjs",
-        "migrate-codeceptjs-4",
-        "debugging-codeceptjs-tests",
-        "codeceptjs-run-analysis",
-        "codeceptjs-fundamentals",
-        "codeceptjs-exploration",
+        "ci-fix-tests",
         "codeceptjs-auth",
-        "ci-fix-tests"
+        "codeceptjs-exploration",
+        "codeceptjs-fundamentals",
+        "codeceptjs-run-analysis",
+        "debugging-codeceptjs-tests",
+        "migrate-codeceptjs-4",
+        "migrate-cypress-to-codeceptjs",
+        "migrate-protractor-to-codeceptjs",
+        "migrate-selenium-java-to-codeceptjs",
+        "migrate-testcafe-to-codeceptjs",
+        "refactoring-codeceptjs-tests",
+        "writing-codeceptjs-tests"
       ]
     },
     {
       "source": "currents-dev/playwright-best-practices-skill",
       "ref": null,
-      "sha": "ef329e7e65149918e1ff0eed2cf7d2e6e6f9eb5b",
-      "folder": "playwright-best-practices-skill",
+      "sha": "283d5cbc5d11aac1abda058b16ad22c317d54dc0",
+      "folder": "playwright",
       "skills": [
         "playwright-best-practices"
       ]
@@ -62,8 +69,8 @@
     {
       "source": "microsoft/playwright-cli/tree/main/skills/playwright-cli",
       "ref": null,
-      "sha": "793cfb32572733cbcb401e6f28d05a7a914ce408",
-      "folder": "playwright-cli",
+      "sha": "2f85a94b7b885dbf4a5d34462f253a8746a690c9",
+      "folder": "playwright",
       "skills": [
         "playwright-cli"
       ]

package/skills/skills.yaml

@@ -0,0 +1,34 @@
+# External skills for Testeiya. ONE rule: every line is a GitHub repo.
+#
+#   owner/repo                        a skill repo (one skill, or many)
+#   owner/repo/tree/<ref>/<subdir>    pin a branch/tag/commit, or point at a subfolder
+#
+# Each source owns one vendor folder next to this file — the repo name, or the
+# owner when the repo is just "skills" (testomatio/skills -> testomatio/).
+# Updates replace only that folder; a folder this file does not own is treated
+# as internal and never touched. First-party skills are not kept here.
+#
+# Vendored folders are gitignored: they belong to their authors, under their own
+# licences. Send patches for them upstream, to the repo listed below.
+#
+# The folder is the category, and the repo decides it:
+#   - repo with a Claude-plugin marketplace (.claude-plugin/marketplace.json)
+#     -> one category subfolder per plugin  (testomatio/ -> test-management / test-automation / explorbot)
+#   - repo without one -> skills sit right under the vendor folder (the vendor is the category)
+#
+# Name the folder here when repos from different owners belong under one
+# category — the sources then share it, each skill in its own subfolder:
+#
+#   - source: owner/repo
+#     folder: playwright
+#
+# Edit the list, then run:  bunosh skills:update [vendor]      See the result:  bunosh skills:list
+
+- testomatio/skills
+- codeceptjs/skills
+
+# One Playwright category, two upstreams.
+- source: currents-dev/playwright-best-practices-skill
+  folder: playwright
+- source: microsoft/playwright-cli/tree/main/skills/playwright-cli
+  folder: playwright

package/skills/testomatio/explorbot/explorbot-fundamentals/SKILL.md

@@ -1,88 +1,76 @@
 ---
 name: explorbot-fundamentals
-description: Use whenever the user runs, configures, or debugs Explorbot from the command line — choosing freesail/explore/test/plan/research, asking what a flag does, asking where an artifact lives, or troubleshooting a failed run. Guide-only — you present the commands/paths and the user runs them.
+description: Use when running or debugging Explorbot from the command line — which command to run, what a flag does, where results were written, why a run failed, or how to run it with nothing installed in the project.
 license: MIT
 metadata:
   author: Testomat.io
-  version: 0.1.0
+  version: 1.2.0
 ---
 
 # Explorbot Fundamentals
 
-Explorbot is an autonomous AI web-testing CLI. It drives its own browser (CodeceptJS → Playwright) and works in cycles of **research → plan → test**.
+Explorbot is an autonomous AI web-testing CLI. It drives its own browser through cycles of research → plan → test, and an agent drives it like `git` or `npm`.
 
-**The installed CLI and the installed package's `docs/` tree are the source of truth — do not paraphrase them from memory.** Discover commands and read docs at the moment of use.
+**Answer command and flag questions from the installed CLI, never from memory.**
 
-## Where the docs actually live
+```bash
+npx explorbot --help                  # commands, and the EXPLORBOT_* variables
+npx explorbot <command> --help        # flags for one command
+```
 
-Docs ship inside the npm package. After `npm i explorbot`, they're at:
+## Running it with nothing installed
 
-```
-<project root>/node_modules/explorbot/docs/
+Explorbot needs no project install: `npx` plus a provider is enough, and nothing is written into the working directory. Reach for this when the user wants to try Explorbot, or is pointing it at an app that has no repo here.
+
+```bash
+npx explorbot init --global --provider <name>          # once per machine, key in ~/.explorbot/.env
+npx explorbot explore https://app.example.com/login --max-tests 3
 ```
 
-That's the *only* place to read them from in a typical user project. Do **not** look in the skill's own folder, do **not** look in a project-level `docs/` (that belongs to the user's app), do **not** fetch from the web. If `node_modules/explorbot/docs/` doesn't exist, Explorbot isn't installed → route the user to **`explorbot-setup`**.
+Details, including the per-command `EXPLORBOT_*` form for CI: [references/no-install.md](references/no-install.md).
 
-(For an Explorbot contributor working in the explorbot repo itself, docs are at `<repo root>/docs/`. Detect this by checking for `package.json` with `"name": "explorbot"` at the project root. Everyone else: `node_modules/explorbot/docs/`.)
+Installing into the project instead — config, knowledge, and generated tests in the repo — is [[explorbot-setup]].
 
-## Rule 1 — Discover commands via the CLI
+## Docs
 
-Always run the CLI's own help before answering a "how do I…" or "what flag…" question:
+`node_modules/explorbot/docs/` after a local install, the repo's `docs/` when working inside Explorbot itself, otherwise `https://raw.githubusercontent.com/testomatio/explorbot/main/docs/<path>`. `docs/index.json` lists every page with a description — read it to pick the page, then open that page.
 
-```bash
-npx explorbot --help                  # list every command
-npx explorbot <command> --help        # flags and options for one command
-```
+## Where results land
 
-These outputs match the installed version. Any hardcoded list (in skills, blog posts, or your own memory) can be stale.
+Explorbot writes into the project directory when the run used a project `explorbot.config.js`, and into `~/.explorbot/sites/<host>/` otherwise. Under that root:
 
-## Rule 2 — Read docs on demand, do not summarize ahead
+| Path | Contents |
+|---|---|
+| `output/reports/` | session report: coverage, defects, execution issues |
+| `output/plans/` | the plan generated or executed |
+| `output/states/` | per-state HTML, ARIA snapshots, screenshots |
+| `output/research/` | UI maps from the Researcher |
+| `output/tests/` | generated Playwright / CodeceptJS files |
+| `output/explorbot.log` | run log — start here on a failure |
+| `knowledge/`, `experience/` | what you taught it, and what it learned |
 
-Pick the file that matches the topic *when the question comes up* — do not pre-load summaries. All paths below are relative to `node_modules/explorbot/docs/` (or the repo's `docs/` for contributors).
+**Exit codes are not pass/fail.** `explore` and `test` exit `0` whenever the session completes; a failing scenario is a result, not a crash. Read the report. `navigate` is the exception — `1` means unreachable, which makes it a pre-flight check.
 
-| Topic the user is asking about | Open |
-|---|---|
-| Is this app even suitable for explorbot? | `prerequisites.md` |
-| Full list of CLI + TUI commands and flags | `commands.md` |
-| Config file shape, `dirs:`, rules wiring | `configuration.md` |
-| AI providers (OpenRouter / OpenAI / Anthropic / Groq / Cerebras / Azure) | `providers.md` |
-| Knowledge files (URL patterns, frontmatter, interpolation) | `knowledge.md` |
-| Planner, planning styles, plan markdown format | `planner.md`, `test-plans.md` |
-| Researcher (page analysis) | `researcher.md` |
-| Page interaction model (locators, ARIA, iframes) | `page-interaction.md` |
-| Re-running generated tests with healing | `rerun.md` |
-| Generated test code (Playwright / CodeceptJS) | `automated-tests.md` |
-| Hooks | `hooks.md` |
-| Reporting (HTML/MD/Testomat.io) | `reporting.md` |
-| Tracing / Langfuse / observability | `observability.md` |
-| Library / programmatic use | `scripting.md`, `npm-package.md` |
-| API testing | `api-testing.md` |
-| Doc collector | `doc-collector.md` |
-
-If the topic isn't in this table, `ls node_modules/explorbot/docs/` and pick the matching file by name.
-
-## Rule 3 — CLI only; never drive the TUI
-
-An agent can run only the non-interactive CLI (`explorbot explore`, `explorbot test`, `explorbot plan`, `explorbot research`, `explorbot navigate`, etc.). These run headless and exit.
-
-**`explorbot start` launches an interactive terminal UI (TUI). An agent cannot operate a TUI — never try to launch or drive it.** If the user wants interactive mode, tell them to run `explorbot start [path]` themselves.
-
-## Order of operations for every question
-
-1. Verify `node_modules/explorbot/` exists. If not → route to **`explorbot-setup`**.
-2. Identify whether the user is asking about a **command/flag** (→ run `npx explorbot … --help`) or a **concept/config/feature** (→ open the matching file in `node_modules/explorbot/docs/`).
-3. Read the relevant source.
-4. Answer using what you just read, and cite it (`node_modules/explorbot/docs/knowledge.md`, `npx explorbot explore --help`).
+## Naming the site
 
-## Related skills
+A target is either **absolute** — starting with `http://` or `https://` — or a **relative path** starting with `/`. Anything else is ambiguous and not a valid target.
+
+A relative path needs a site to resolve against: `web.url` from a project config, or `EXPLORBOT_URL`. Without either, pass the absolute URL. Commands that take no target at all — `test`, `learn`, `knows`, `experience`, `compact` — read the same two sources. `npx explorbot sites` lists what has been explored so far.
+
+## Cheap before expensive
 
-- [[explorbot-setup]] — install + config + verify reachability of one page (curl → navigate → credentials). Use this when `node_modules/explorbot/` is missing.
-- [[explorbot-plan]] — write a test plan markdown by hand without exploring a live page.
-- [[explorbot-debug]] — diagnose a failed session from `output/explorbot.log` + Langfuse traces.
-- [[explorbot-fix-session]] — once a session is diagnosed, propose a single minimal fix.
+- `npx explorbot context <url>` — headings, matched knowledge, interactive elements. No AI calls.
+- `npx explorbot shell <url> '<codecept command>'` — run one command and exit.
+- `npx explorbot knows <url>` — what knowledge matches a page.
+- `npx explorbot navigate <url> --session` — reachability, and it saves the session.
 
-## Anti-patterns
+## Rules
+
+- `explorbot start` is an interactive TUI — an agent cannot operate it. Ask the user to run it. Everything else runs headless and exits.
+- If `--help` does not show a command or flag, it does not exist.
+- Explorbot needs CRUD; a landing page, blog, or CMS is out of scope.
+
+## Related skills
 
-- ❌ Pasting big config snippets without opening `node_modules/explorbot/docs/configuration.md` first.
-- ❌ Inventing a command that "should exist" — if `--help` doesn't show it, it doesn't exist.
-- ❌ Telling the user to use explorbot for a landing page / blog / CMS — `node_modules/explorbot/docs/prerequisites.md` says it's for CRUD-heavy apps.
+- [[explorbot-setup]] — install into a project: config, provider, login knowledge, verified navigation.
+- [[explorbot-plan]] — hand-author a test plan and run it with `explorbot test`.