testeiya 0.2.1 → 0.3.10

package/{src/prompt → prompt}/testomatio.ts

@@ -1,16 +1,16 @@
 import dedent from "dedent";
-import type { TestomatioProjectInfo } from "../project-info.js";
+import type { TestomatioProjectInfo } from "./project-info.js";
 
 const MAX_PROMPT_LABELS = 20;
 const MAX_PROMPT_TAGS = 30;
 const MAX_PROMPT_ENVS = 15;
 
-export const testomatioTms = dedent`
+const tmsViaDirectTools = dedent`
   # Testomat.io-first operating rules (highest priority)
 
-  This agent runs **inside the Testomat.io product**. You have TWO sources of truth and they answer different kinds of questions:
+  This agent works on Testomat.io projects. You have TWO sources of truth and they answer different kinds of questions:
 
-  1. **The pulled markdown workspace (\`cwd\`)** — for **tests** and **suites**. Each project's tests and suite structure are already pulled as markdown files into the working directory (one directory per project slug). This is the canonical source for test content, suite hierarchy, test bodies, tags, gherkin scenarios, file layout. Use \`read\`, \`find\`, \`grep\`, \`ls\` (and the \`render_tree\` tool for suite hierarchy) — they're instant and don't hit the network.
+  1. **The pulled markdown workspace (\`cwd\`)** — for **tests** and **suites**. Each project's tests and suite structure are already pulled as markdown files into the working directory (one directory per project slug). This is the canonical source for test content, suite hierarchy, test bodies, tags, gherkin scenarios, file layout. Use \`read\`, \`find\`, \`grep\`, \`ls\` — they're instant and don't hit the network.
   2. **MCP tools under \`testomatio-<slug>\`** — for **dynamic Testomat.io data**: runs, testruns, plans, labels, linked issues, ims config, ci config, analytics. These things don't live as files and MUST come from MCP.
 
   **Prefer the filesystem for test/suite queries.** Only fall back to \`testomatio-*_tests_list\` / \`testomatio-*_suites_list\` if the user's question genuinely needs cross-tree metadata (e.g. priority, labels, status) that isn't in the markdown, or if the workspace looks stale. Reading test files is faster, cheaper, and gives you the actual code/gherkin.
@@ -30,21 +30,103 @@ export const testomatioTms = dedent`
   | Question is about… | First action |
   |---|---|
   | Test content (code, steps, gherkin, description, file path, tags) | \`read\` / \`find\` / \`grep\` in \`cwd\` |
-  | Suite hierarchy / structure / which files exist | \`ls\` / \`find\` + \`render_tree\` |
+  | Suite hierarchy / structure / which files exist | \`ls\` / \`find\` |
   | Individual test metadata (priority, status flag, labels) | try filesystem; if missing, \`testomatio-*_tests_get\` |
   | Runs, testruns, plans, labels, issues, analytics | MCP \`testomatio-*\` tools |
   | Creating/updating tests or suites | edit the markdown file, then \`npx check-tests push\` |
   | Creating/updating runs, linking issues | MCP create/update tools |
-  | Launching automated or mixed Run remotely on CI | Use npx @testomatio/reporter run --remote <profile>, raise error if no CI profiles configured
+  | Launching automated or mixed Run remotely on CI | Use npx -y @testomatio/reporter@latest run --remote <profile>, raise error if no CI profiles configured
   | Running automated Run | Use local test runner with testomatio reporter attached to report to current project
 
   ---
 `;
 
+const tmsViaProxy = dedent`
+  # Testomat.io-first operating rules (highest priority)
+
+  This agent works on a Testomat.io project. You have TWO sources of truth and they answer different kinds of questions:
+
+  1. **The pulled markdown workspace (\`cwd\`)** — for **tests** and **suites**. Test content, suite hierarchy, bodies, tags and gherkin scenarios are files. Use \`read\`, \`find\`, \`grep\`, \`ls\` — they are instant and hit no network.
+  2. **The \`mcp\` tool** — for **dynamic Testomat.io data**: runs, testruns, plans, labels, linked issues, ims config, ci config, analytics. These do not live as files and MUST come from there.
+
+  Testomat.io is reached through **one \`mcp\` tool**, not a tool per operation. Call \`mcp({ search: "<what you need>" })\` to find the right operation, then \`mcp({ tool: "<name>", ... })\` to run it. The handful of reads used most often are also registered as their own tools — use those directly when they fit.
+
+  **Prefer the filesystem for test/suite queries.** Reach for a listing only when the question needs cross-tree metadata (priority, labels, status) the markdown does not carry, or when the workspace looks stale.
+
+  **Never** ask the user for the **Testomat.io** API token — it's configured. (This does NOT cover secrets the *app under test* needs to run — its own env vars/tokens. If a test run is blocked by one of those, report it.)
+
+  **Statuses and counts are live** — runs change them at any time. Fresh query results supersede numbers from earlier in the conversation; when they differ, the data changed — report the new snapshot.
+
+  ## Banned moves
+
+  - Do NOT search for an operation as your first action for a test/suite question — **read the filesystem first** (\`find\`, \`ls\`, \`grep\`, \`read\`). Fall back to a listing only if the metadata you need isn't in the markdown.
+  - Do NOT ask the user for the **Testomat.io** API token — it's already configured. (Secrets the app under test needs to run are a different thing — report those if a run is blocked.)
+  - Do NOT call \`bash\` / \`find\` / \`grep\` to answer questions about **runs, testruns, plans, labels, linked issues, analytics** — those don't exist as files.
+
+  ## Filesystem vs. Testomat.io cheat sheet
+
+  | Question is about… | First action |
+  |---|---|
+  | Test content (code, steps, gherkin, description, file path, tags) | \`read\` / \`find\` / \`grep\` in \`cwd\` |
+  | Suite hierarchy / structure / which files exist | \`ls\` / \`find\` |
+  | Individual test metadata (priority, status flag, labels) | try filesystem; if missing, \`mcp({ search: "get test" })\` |
+  | Runs, testruns, plans, labels, issues, analytics | \`mcp({ search: … })\`, then \`mcp({ tool: … })\` |
+  | Creating/updating tests or suites | edit the markdown file, then \`npx check-tests push\` |
+  | Creating/updating runs, linking issues | the matching \`mcp\` create/update operation |
+  | Launching automated or mixed Run remotely on CI | Use npx -y @testomatio/reporter@latest run --remote <profile>, raise error if no CI profiles configured |
+  | Running automated Run | Use local test runner with testomatio reporter attached to report to current project |
+
+  ---
+`;
+
+const tmsViaCli = dedent`
+  # Testomat.io-first operating rules (highest priority)
+
+  This agent works on a Testomat.io project through the **shell only** — there are no Testomat.io tools in this session.
+
+  1. **The pulled markdown workspace (\`cwd\`)** — the canonical source for **tests** and **suites**: content, hierarchy, bodies, tags, gherkin scenarios. Use \`read\`, \`find\`, \`grep\`, \`ls\`.
+  2. **\`npx check-tests\`** — moves test cases between the markdown and Testomat.io (\`pull\`, \`push\`). It reads its credentials from the environment.
+  3. **The REST API through \`bash\`** — for dynamic data (runs, testruns, plans, labels, linked issues, analytics): \`curl -H "Authorization: $TESTOMATIO" "$TESTOMATIO_URL/api/v2/..."\`.
+
+  **Never** ask the user for the **Testomat.io** API token — it's configured as \`TESTOMATIO\`. (This does NOT cover secrets the *app under test* needs to run — its own env vars/tokens. If a test run is blocked by one of those, report it.)
+
+  **Statuses and counts are live** — runs change them at any time. Fresh query results supersede numbers from earlier in the conversation.
+
+  ## Banned moves
+
+  - Do NOT shell out for test content that is already a file in \`cwd\` — read the file.
+  - Do NOT invent REST paths or parameters. Read the workspace first; when a call is genuinely needed, keep to documented \`/api/v2\` endpoints.
+  - Do NOT ask the user for the **Testomat.io** API token.
+
+  ## Filesystem vs. shell cheat sheet
+
+  | Question is about… | First action |
+  |---|---|
+  | Test content (code, steps, gherkin, description, file path, tags) | \`read\` / \`find\` / \`grep\` in \`cwd\` |
+  | Suite hierarchy / structure / which files exist | \`ls\` / \`find\` |
+  | Runs, testruns, plans, labels, issues, analytics | \`curl\` against \`/api/v2\` |
+  | Creating/updating tests or suites | edit the markdown file, then \`npx check-tests push\` |
+  | Launching automated or mixed Run remotely on CI | Use npx -y @testomatio/reporter@latest run --remote <profile>, raise error if no CI profiles configured |
+  | Running automated Run | Use local test runner with testomatio reporter attached to report to current project |
+
+  ---
+`;
+
+/**
+ * How the agent reaches Testomat.io in this session. The rules are the same;
+ * the way to act on them is not, so the harness picks the matching wording.
+ */
+export function testomatioTms(access: TmsAccess): string {
+  if (access === "mcp-proxy") return tmsViaProxy;
+  if (access === "cli-only") return tmsViaCli;
+  return tmsViaDirectTools;
+}
+
 export function testomatioConnection(
   tokenSlugs: string[],
   backendUrl?: string,
-  connection?: { projectId?: string; title?: string }
+  connection?: { projectId?: string; title?: string },
+  access: TmsAccess = "mcp-direct"
 ): string {
   let urlSuffix = "";
   if (backendUrl) urlSuffix = ` (\`${backendUrl}\`)`;
@@ -60,7 +142,7 @@ export function testomatioConnection(
 
       The project API key is **already set** as \`TESTOMATIO\` in the environment of every \`bash\` command you run, along with \`TESTOMATIO_URL\`${urlSuffix}. **Never ask the user for a Testomat.io token or API key** — it is already in scope.
 
-      Push or pull manual test cases with \`npx check-tests\` (or other \`npx @testomatio/*\` commands) — they pick the credentials up from the environment. If \`testomatio-*\` MCP tools are available, prefer them for structured actions (list/create/update tests, runs, labels, suites, etc.).
+      Push or pull manual test cases with \`npx check-tests\` (or other \`npx @testomatio/*\` commands) — they pick the credentials up from the environment. ${envTokenActions(access)}
 
     `;
   }
@@ -89,7 +171,7 @@ export function testomatioConnection(
     Projects pulled into this working directory (one dir per project):
     ${projects}
 
-    The **Testomat.io MCP server** is also auto-connected, one instance per project (tool prefix: \`testomatio-<slug>\`). Prefer MCP tools for structured actions (list/create/update tests, runs, labels, suites, etc.) — they are typed, safer, and faster than shell calls. Fall back to \`bash\` + \`check-tests\` only for things the MCP does not cover (e.g. pulling full markdown files).
+    ${perProjectActions(access)}
 
     When you need to push changes back, run \`npx check-tests push\` (or similar \`npx @testomatio/*\` commands) directly — credentials are already in scope.
 
@@ -161,6 +243,28 @@ export function projectSettings(info: TestomatioProjectInfo): string {
   `;
 }
 
+// How to act on a connection whose token comes from the environment.
+function envTokenActions(access: TmsAccess): string {
+  if (access === "mcp-proxy") {
+    return "For structured actions (list/create/update tests, runs, labels, suites, etc.) prefer the `mcp` tool: `mcp({ search })` to find an operation, `mcp({ tool })` to run it.";
+  }
+  if (access === "cli-only") {
+    return "For runs, plans, labels and analytics use `curl` against `/api/v2` — there are no Testomat.io tools in this session.";
+  }
+  return "If `testomatio-*` MCP tools are available, prefer them for structured actions (list/create/update tests, runs, labels, suites, etc.).";
+}
+
+// The same, where the harness runs one MCP server per pulled project.
+function perProjectActions(access: TmsAccess): string {
+  if (access === "mcp-proxy") {
+    return "The **Testomat.io MCP server** is also connected, reached through the `mcp` tool (`mcp({ search })` to find an operation, `mcp({ tool })` to run it). Prefer it for structured actions (list/create/update tests, runs, labels, suites, etc.) — those are typed, safer, and faster than shell calls. Fall back to `bash` + `check-tests` only for things it does not cover (e.g. pulling full markdown files).";
+  }
+  if (access === "cli-only") {
+    return "There are no Testomat.io tools in this session: use `npx check-tests` for test cases and `curl` against `/api/v2` for runs, plans and labels.";
+  }
+  return "The **Testomat.io MCP server** is also auto-connected, one instance per project (tool prefix: `testomatio-<slug>`). Prefer MCP tools for structured actions (list/create/update tests, runs, labels, suites, etc.) — they are typed, safer, and faster than shell calls. Fall back to `bash` + `check-tests` only for things the MCP does not cover (e.g. pulling full markdown files).";
+}
+
 function capped(shown: string[], total: number): string {
   let suffix = "";
   if (total > shown.length) {
@@ -168,3 +272,10 @@ function capped(shown: string[], total: number): string {
   }
   return shown.join(", ") + suffix;
 }
+
+/**
+ * `mcp-direct` — every Testomat.io operation is its own tool, prefixed
+ * `testomatio-<slug>`. `mcp-proxy` — one `mcp` tool with search and call.
+ * `cli-only` — no tools at all: `check-tests` and REST through the shell.
+ */
+export type TmsAccess = "mcp-direct" | "mcp-proxy" | "cli-only";

package/prompt/tools.ts

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+
+import dedent from 'dedent';
+
+/**
+ * The tools every harness gives the agent. Anything a particular harness adds —
+ * a question tool, a browser it can drive for a watching user — arrives as an
+ * extra bullet from that harness, since the agent must not be told about a tool
+ * it does not have.
+ */
+export function tools(options?: { extra?: string[] }): string {
+  const extra = (options?.extra ?? []).join('');
+  let routing = '    - GitHub: issues and projects through MCP.';
+  if (onPath('gh')) {
+    routing +=
+      '\n    - Pull requests and repositories: `gh` in `bash`. When a PR question needs issue detail, query the issue through MCP — never infer it from a PR title.';
+  }
+  if (onPath('acli')) {
+    routing +=
+      '\n    - Jira in bulk (many issues at once), boards, sprints and filters: `acli` in `bash`, per the `atlassian` skill. Confluence and attachments have no `acli` command and stay on MCP.';
+  }
+  if (onPath('glab')) {
+    routing +=
+      '\n    - GitLab releases, labels, milestones, snippets, CI artifacts, and any endpoint with no MCP tool: `glab` in `bash`. Issues, merge requests, pipelines and code search stay on MCP, which covers them well.';
+  }
+  return dedent`
+<available-tools>
+  You have these tools available:
+  * **Read operations (use freely):** \`read\`, \`grep\`, \`ls\`.
+    - Use these aggressively to understand the system under test before proposing changes.
+  * **Write operations (restricted):** \`write\`, \`edit\`, \`bash\`.
+    - Requires explicit user confirmation for destructive or shared-state actions.
+${extra}  * **Internal Skills:** For QA-related tasks, check available skills first and prefer using them when applicable.
+  * **External Integrations:** Use MCP tools when they provide superior data or specialized integrations.
+    - Primary MCP (Testomat.io): Use Testomat.io MCP tools to extend functionality.
+    - Secondary MCP (Jira, GitHub, etc.): Invoke only when user explicitly asks or when remote context exploration is required.
+${routing}
+
+  <tool-governance>
+    * **Prioritize Specificity:** Use \`read\` instead of \`cat\`, and \`edit\` instead of \`sed\`. Dedicated tools provide better error tracking and safety.
+    * **Parallel Execution:** Call independent tools in parallel to minimize latency. Sequential calls are reserved for operations with data dependencies.
+    * **Atomic Updates:** Mark tasks as complete in your internal state immediately upon execution. Do not batch status updates.
+    * **Analysis-First:** Use your own reasoning to guide tool selection. Do not wait for step-by-step instructions if discovery tools can provide the answer.
+  </tool-governance>
+</available-tools>
+`;
+}
+
+/** Is this CLI on PATH? Never tell the agent to use a binary this machine lacks. */
+function onPath(bin: string): boolean {
+  for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    if (existsSync(join(dir, bin)) || existsSync(join(dir, `${bin}.exe`))) return true;
+  }
+  return false;
+}

package/prompt/vocab.ts

@@ -0,0 +1,7 @@
+/**
+ * The per-project config directory name, as the agent knows it. Part of the
+ * vocabulary the system prompt teaches — every path the prompt names below it
+ * (`.testeiya/manual-tests`, `.testeiya/project-info.json`, …) is built from
+ * this constant, so the prompt and the harness can never disagree about it.
+ */
+export const TESTEIYA_DIR_NAME = ".testeiya";

package/skills/codeceptjs/ci-fix-tests/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ci-fix-tests
-description: "Use on CI in non-interactive mode when a CodeceptJS run failed — automatically attempt safe fixes (locator drift, missing waits), rerun only the failing scenarios, compare against the baseline, roll back any edit that didn't help, and always write a markdown report at `output/ci-fix.md` for the CI step to consume. Conservative by design: no refactors, no config edits, no auth fixes, no flake-masking retries. Trigger on \"ci fix tests\", \"auto-fix failing tests\", \"attempt repair on CI\", or as a CI step after a failed run."
+description: "Use on CI in non-interactive mode after a failed CodeceptJS run — attempts safe fixes only (locator drift, missing waits), reruns failing scenarios, rolls back edits that didn't help, reports at `output/ci-fix.md`. No refactors, no config edits, no flake-masking. Trigger on \"ci fix tests\", \"auto-fix failing tests\", \"attempt repair on CI\", or as a CI step after a failed run."
 ---
 
 # Auto-fix CodeceptJS Tests on CI
@@ -25,7 +25,7 @@ Save this as the **baseline** — `count`, `failing_set`, `clusters`.
 ### 2. Pick safe fix candidates
 Only attempt fixes from this allowed list:
 
-- **Locator drift** — the failed locator no longer matches anything but a similar element exists. Use the **codeceptjs-exploration** skill (headless) to find candidates; pick one with high semantic stability (ARIA `{ role, name }` → visible text → `data-testid` → composed CSS). Replace the locator at the failing step only.
+- **Locator drift** — the failed locator no longer matches anything but a similar element exists. Use the **codeceptjs-exploration** skill (headless) to find candidates; pick a short locator scoped to a stable region — `I.click('Save', '.toolbar')` — in this order: visible text / accessible name → ARIA `{ role, name }` → `$name` (`customLocator`) → composed CSS. Replace the locator at the failing step only.
 - **Missing wait for a spinner / loader / modal** — the failed step's ARIA snapshot shows a spinner or skeleton present, or the target element appears later. Add a single matching `I.waitFor*` immediately before the failing step.
 - **`I.wait(N)` replacement** — when a hardcoded sleep is the only thing between a failing assertion and a passing one and the gating element is identifiable, replace the sleep with a specific `waitFor*`.
 
@@ -81,7 +81,7 @@ Failing scenarios: N
 - ...
 
 ## Attempted fixes
-- `tests/foo_test.js:42` — locator drift: `'Save'` → `{ role: 'button', name: 'Save' }`
+- `tests/foo_test.js:42` — locator drift: `I.click('Save')` → `I.click('Save', '.toolbar')`
 - `tests/bar_test.js:15` — added `I.waitForInvisible('.spinner')` before checkout click
 - `tests/baz_test.js:7` — replaced `I.wait(3)` with `I.waitForVisible('.confirmation-dialog', 10)`
 
@@ -112,9 +112,8 @@ The first line of `Status:` is the machine-parseable signal. The rest is for the
 - Writing a partial or missing `output/ci-fix.md`. CI depends on it; the absence of a report is itself a failure mode.
 - Running the **whole** suite for the verification step — only the originally-failing scenarios, to keep CI time bounded.
 
-## Pointers
+## Related skills
 
-- `codeceptjs-run-analysis` — read trace artifacts, cluster failures, build the baseline set.
-- `codeceptjs-exploration` — find replacement locators when one has drifted.
-- `codeceptjs-fundamentals` — confirm helper, config, which env the CI run used.
-- `node_modules/codeceptjs/docs/aitrace.md` — trace format.
+- `codeceptjs-run-analysis` — baseline, clustering, post-fix comparison
+- `codeceptjs-exploration` — replacement locators for drift
+- `codeceptjs-fundamentals` — config, helper, CI environment

package/skills/codeceptjs/codeceptjs-auth/SKILL.md

@@ -1,51 +1,45 @@
 ---
 name: codeceptjs-auth
-description: Use when a CodeceptJS test needs login, when different user roles are involved, or when the writing-codeceptjs-tests skill identifies authorization is required. Configures the `auth` plugin for session reuse, derives the login flow from the actual login page HTML (not guesses), keeps the real flow inside `steps_file.js` so `I.login*()` is callable directly and the conf stays small, loads credentials from a `.env` file via the modern Node `process.loadEnvFile()` API (no `dotenv` dependency), and supports multiple roles. Trigger on mentions of login, sign-in, sign-up, authentication, sessions, "logged in", admin/editor/user roles, or auth-related test failures.
+description: >
+  Use when a CodeceptJS test needs login, user roles, or session reuse — or
+  when another CodeceptJS skill identifies authorization is required. Also on
+  auth-related test failures. Trigger on login, sign-in, sign-up,
+  authentication, sessions, "logged in", admin/editor/user roles.
 ---
 
 # CodeceptJS Auth Plugin
 
-The `auth` plugin logs each user in once, captures cookies (or local-storage / token via overrides), and restores the session for subsequent tests. Stale sessions trigger a fresh login automatically.
+The `auth` plugin logs each user in once, captures cookies (or localStorage/token via overrides), and restores the session for subsequent tests. Stale sessions trigger a fresh login automatically.
 
-Source of truth: `node_modules/codeceptjs/lib/plugin/auth.js` — JSDoc lists every recipe. Reference doc: `node_modules/codeceptjs/docs/auth.md`.
-
-## When to add it
-
-Suggested if tests have repeatable authentication and session is needed to be persisted accross tests. Also optimizes start time of tests by saving previous sessision cookies in files. 
-
-Suggested as performance optimization, refactoring measure.
-
-If `auth` plugin already exists in the project (check fundamentals' output), reuse the existing `inject` name and user keys.
+If the project already has `auth` configured (fundamentals' discovery output), **reuse** its existing inject name and user keys — don't reconfigure.
 
 ## Decide first — ask the user
 
-Four answers shape the plugin. Don't guess any. If the project or test plan doesn't make them obvious, ASK.
+Four answers shape the plugin. Don't guess any.
 
-1. **Is a session needed at all?** Public flows (landing, signup) don't need one — skip the plugin.
-2. **One user or many?** Default to one. Add more only when more than one is actually exercised.
-3. **If many — what splits them?** Don't assume "admin / editor / viewer". Real systems split users by role, workspace / tenant, plan tier, sign-in provider (Google vs SSO vs password — same person), or per-test fixture. ASK the user; use the answer to name the `users.<key>` entries.
-4. **What's the auth type?** Form login is the default; others need a different `login()` body:
-   - **Form** — `fillField` → `click Sign in`. Canonical shape below.
-   - **OAuth / SSO** — click provider button, drive the IdP page (often a separate origin).
-   - **Magic link / passwordless** — UI flow is rarely worth automating. Prefer a backdoor — API mint, or read the link from a test mailbox.
-   - **API token** — skip the form; `I.executeScript` to write the token into `localStorage`, or `I.setCookie(...)`.
-   - **2FA / OTP** — `async login`; fetch the code from a test mailbox / backdoor before submitting.
+1. **Is a session needed at all?** Public flows (landing, signup) → skip the plugin.
+2. **One user or many?** Default one; add more only when actually exercised.
+3. **If many — what splits them?** Role, workspace/tenant, plan tier, sign-in provider, per-test fixture — real systems vary. Ask; use the answer to name `users.<key>` entries.
+4. **What's the auth type?**
+   - **Form** — default; canonical shape below
+   - **OAuth / SSO** — click provider button, drive the IdP page (often separate origin)
+   - **Magic link / passwordless** — UI flow rarely worth automating; prefer an API mint or reading the link from a test mailbox
+   - **API token** — skip the form; write the token into `localStorage` via `executeScript`, or `I.setCookie(...)`
+   - **2FA / OTP** — async `login`; fetch the code from a test mailbox / backdoor before submitting
 
 ## Rules
 
-1. **Login flow must not be written in the conf.** Better to place it nto steps_file.js (if it is includded) or page object. The conf better to reference it like: `login: (I) => I.login()`.
-2. **Credentials should not be stored in configs. Use `.env` via `process.loadEnvFile()`** (modern Node, no `dotenv` package). Passwords wrapped with `secret(...)`. No literal credentials anywhere — conf, steps file, test, or git history.
-3. **`.env` is gitignored; `.env.example` is committed** with the var names and no values. `output/*_session.json` is gitignored too.
+1. **Login flow never lives in the conf.** Put it in `steps_file.js` (if included) or a page object; conf only references it: `login: (I) => I.login()`.
+2. **Credentials from env only** — `.env` loaded via `process.loadEnvFile()` (no dotenv dependency). Passwords wrapped with `secret(...)`. No literals anywhere — conf, steps file, test, git history.
+3. **`.env` is gitignored; `.env.example` is committed** with names, no values. Gitignore `output/*_session.json` too.
 
 ## Canonical shape
 
 ```js
 // codecept.conf.js — first line of the file
-process.loadEnvFile() // or dotenv.load() if this package availble 
-// ...
+process.loadEnvFile()
 
 export const config = {
-  // ...
   include: { I: './steps_file.js' },
   plugins: {
     auth: {
@@ -79,56 +73,46 @@ export default function () {
 }
 ```
 
-```
-# .env (gitignored)              # .env.example (committed)
-USER_EMAIL=USER@example.com     USER_EMAIL=
-USER_PASSWORD=<secret>          USER_PASSWORD=
+```sh
+# .env (gitignored)        # .env.example (committed)
+USER_EMAIL=...             USER_EMAIL=
+USER_PASSWORD=<secret>     USER_PASSWORD=
 ```
 
 ## Pre-flight (before writing config)
 
-1. **Read the real login page HTML.** Don't guess locators. MCP: `run_code` to login page and inspect the ARIA snapshot. Field labels / `name` / `id` / submit control — from the actual page. It's ok to ask user about authorization if it is not clear how to makeit.
-2. **Pick a role-specific post-login marker.** Something the page renders only for *this* user (navbar username, `data-user-role`).
-3. **Confirm session storage.** Cookies (default) for server-rendered apps; `localStorage`/`sessionStorage` for SPAs — verify with `I.executeScript(() => Object.keys(localStorage))` after a manual login. Default cookie `fetch`/`restore` silently no-op for token storage.
+1. **Read the real login page** — MCP `run_code` to `/login`, inspect the ARIA snapshot (`codeceptjs-exploration`). Field labels / `name` / `id` / submit control from the actual page, not guesses. Unclear authorization mechanism → ask the user.
+2. **Pick a role-specific post-login marker** — something rendered only for *this* user (navbar username, `data-user-role`).
+3. **Confirm session storage** — cookies (default) for server-rendered apps; localStorage/sessionStorage for SPAs. Verify after a manual login with `I.executeScript(() => Object.keys(localStorage))`. Cookie fetch/restore silently no-op against token storage.
 
 ## Verify
 
-Or MCP `run_test` against a one-Scenario file that calls `login(<role>)` then asserts on the post-login marker.
-
-Enable `saveToFile: true` only after the verification round-trip succeeds — a bad saved session masks a broken `login`.
-
-## Refactor
-
-Add to before hooks (if applied to all tests in suite) or to exact tests in syute
-
-`Before(({ login }) => login())`
-
-`login` was declared in auth plugin configuration
-
-Run real, not dry:
+Run a one-Scenario file that calls `login(<role>)` then asserts on the post-login marker:
 
 ```bash
-npx codeceptjs run --grep '<scenario>' --debug
+npx codeceptjs run --grep '<scenario>' --debug    # real run, not dry — dry-run doesn't init plugins
 ```
 
+Enable `saveToFile: true` only after this round-trip succeeds — a bad saved session masks a broken `login`.
+
+Then wire into hooks/tests: `Before(({ login }) => login())` for suite-wide, or per-test as needed.
 
-## Multi-session shape
+## Multi-role shape
 
-Only after question 3 is answered. Name `users.<key>` after whatever splits them in *this* system; one matching login method per key in `steps_file.js`.
+Only after question 3 is answered. Keys named after whatever splits users *in this system*; one matching actor method per key:
 
 ```js
-// keys named after the dimension (role / workspace / provider / …)
 users: {
   admin:      { login: (I) => I.loginAsAdmin() },
   workspaceB: { login: (I) => I.loginToWorkspaceB() },
 }
 ```
 
-Don't parameterise into a single `login(key)` — the plugin keys sessions by name and explicit methods read better. Switching between sessions in one Scenario: `session('<key>')` opens a separate browser context (see `node_modules/codeceptjs/docs/sessions.md`).
+Don't parameterise into a single `login(key)` — the plugin keys sessions by name, explicit methods read better. Switch mid-Scenario: `session('<key>')` opens a parallel browser context (fundamentals § Writing tests).
 
-## Token / local-storage auth
+## Token / localStorage auth
 
-When sessions live outside cookies, override `fetch` and `restore`:
+Override `fetch` / `restore` when sessions live outside cookies:
 
 ```js
 admin: {
@@ -142,17 +126,16 @@ admin: {
 }
 ```
 
-`check(I, session)` receives whatever `fetch` returned — throw inside `check` to force a fresh login (e.g., when a `/me` endpoint shows the wrong user).
-
-## Common pitfalls
+`check(I, session)` receives whatever `fetch` returned — throw inside `check` to force fresh login (e.g. `/me` endpoint shows wrong user).
 
-- **Credentials inlined in conf or test.** Always env-driven. A code review showing a literal email or password = skill failed.
-- **Forgetting to gitignore `.env` and `output/*_session.json`.** Both leak credentials.
+## Pitfalls
 
+- Credentials inlined in conf/test — always env-driven + `secret()`.
+- Forgetting to gitignore `.env` and `output/*_session.json` — both leak credentials.
 
-## Pointers
+## Related skills
 
-- `node_modules/codeceptjs/lib/plugin/auth.js` — JSDoc recipes (cookie / multi-user / local-storage / async / session-validation)
-- `node_modules/codeceptjs/docs/auth.md` — full reference
-- `node_modules/codeceptjs/docs/sessions.md` — `session()` for multi-user Scenarios
-- `node_modules/codeceptjs/docs/secrets.md` — the `secret()` wrapper
+- `codeceptjs-fundamentals` — secrets rule, sessions, config mutation trap
+- `codeceptjs-exploration` — reading the live login page
+- `writing-codeceptjs-tests` / `refactoring-codeceptjs-tests` — invoke this skill when auth is identified
+- `debugging-codeceptjs-tests` — auth-related failure patterns