@testspectra/skills 1.1.0-rc.0

package/skills/lifecycle-hooks/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: lifecycle-hooks
+description: TestSpectra lifecycle hooks — global-hooks/ (batch-run only) vs specs/<suite>/hooks/ (before, beforeEach, afterEach, after), their execution order in single-test vs global-batch runs, and the failure-cascade rules. Use whenever adding setup/teardown logic instead of duplicating it inside individual test cases.
+---
+
+# Skill: Suite & Global Lifecycle Hooks
+
+Use this skill whenever you need setup/teardown logic (auth, DB seeding, cookie clearing, failure
+screenshots) that shouldn't be duplicated inside every `it()` body.
+
+---
+
+## 1. Two Hook Levels — Know the Difference
+
+| Hook                             | Level  | Scope              | When it runs                                                                                     |
+| :------------------------------- | :----- | :----------------- | :----------------------------------------------------------------------------------------------- |
+| `global-hooks/before`            | Global | Entire run session | **Once**, before all suites — **Global Batch Run / CI only**, never during single-test debugging |
+| `global-hooks/after`             | Global | Entire run session | **Once**, after all suites — Global Batch Run only                                               |
+| `specs/<suite>/hooks/before`     | Suite  | Test suite         | Once before the first test case in the suite                                                     |
+| `specs/<suite>/hooks/beforeEach` | Suite  | Test case          | Before every test case in the suite                                                              |
+| `specs/<suite>/hooks/afterEach`  | Suite  | Test case          | After every test case in the suite                                                               |
+| `specs/<suite>/hooks/after`      | Suite  | Test suite         | Once after the last test case in the suite                                                       |
+
+**Global hooks are skipped when running/debugging a single test case** — put anything a single
+test genuinely depends on (navigating to `/login`, clearing storage) in a **suite** hook instead,
+not a global one, or the test will fail/behave differently when run in isolation.
+
+---
+
+## 2. Directory Layout
+
+```
+workspace-root/
+├── global-hooks/
+│   ├── before/
+│   │   ├── web.hook.ts
+│   │   └── mobile.hook.ts
+│   └── after/
+│       ├── web.hook.ts
+│       └── mobile.hook.ts
+└── specs/
+    └── authentication/
+        ├── suite.md
+        ├── hooks/
+        │   ├── before/web.hook.ts
+        │   ├── beforeEach/web.hook.ts   # e.g. clear cookies, navigate to /login
+        │   ├── afterEach/web.hook.ts    # e.g. failure screenshot, clear storage
+        │   └── after/web.hook.ts
+        ├── TC-0001-valid-login/
+        └── TC-0002-invalid-password/
+```
+
+---
+
+## 3. Execution Order
+
+### Single Test Case Run (VS Code CodeLens `▶ Run on <Target>`)
+
+```
+suite/hooks/before()
+  └─► suite/hooks/beforeEach() ─► it('TC-0001') ─► suite/hooks/afterEach()
+suite/hooks/after()
+```
+
+Global hooks do **not** run here.
+
+### Global Batch Run (`▶ Global Run` / CI/CD)
+
+```
+global-hooks/before()                        (once, whole batch)
+  ├─► Suite 1: before() → [beforeEach → TC → afterEach]* → after()
+  ├─► Suite 2: before() → [beforeEach → TC → afterEach]* → after()
+global-hooks/after()                         (once, whole batch)
+```
+
+---
+
+## 4. Implementation: Anonymous Async Default Export
+
+Same convention as steps/actions — one anonymous async function, default export, zero manual
+imports:
+
+```typescript
+// specs/authentication/hooks/beforeEach/web.hook.ts
+export default async function () {
+  await Spectra.navigate('/auth/login');
+  await Spectra.browser.clearLocalStorage();
+  await Spectra.browser.clearCookies();
+}
+```
+
+```typescript
+// global-hooks/before/web.hook.ts
+export default async function () {
+  const response = await fetch(`${process.env.BASE_URL}/health`);
+  if (!response.ok) {
+    throw new Error(`Target environment is not healthy: ${response.statusText}`);
+  }
+}
+```
+
+---
+
+## 5. Failure Cascade Rules
+
+1. **`beforeEach` fails** → that test case is marked `failed` (Hook Failure), its `it()` body is
+   skipped, but `afterEach` still runs for cleanup.
+2. **Suite `before` fails** → every test case in that suite is marked `skipped`/`error`; suite
+   `after` still runs to clean up partial resources.
+3. **`global-hooks/before` fails** → the entire batch run aborts immediately; `global-hooks/after`
+   still runs to finalize cleanup.
+
+Write hook bodies defensively with this cascade in mind — teardown logic in `after`/`afterEach`
+must not assume `before`/`beforeEach` fully succeeded.

package/skills/matchers-and-assertions/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: matchers-and-assertions
+description: Full reference of the TestSpectra element action/assertion API (shouldBeVisible, click, type...), collection matchers (shouldHaveLength...), and global Spectra.* / Spectra.browser.* commands. Use whenever writing or reviewing the body of an it() test script, step, or action.
+---
+
+# Skill: Matchers, Actions & the Global `Spectra` API
+
+Use this skill as the canonical vocabulary reference whenever you write the body of a test script
+(`it()`), a shared step, or a custom action. TestSpectra never uses raw WebdriverIO/Jest matcher
+names (`toBeDisplayed`, `setValue`, `$`) in authored code — always use the TestSpectra syntax below.
+Every call is automatically traced (`trackCommand()`) and emitted as one natural-English log line
+per action/assertion in `.testspectra/reports/`.
+
+---
+
+## 1. Element Action Commands (called on a Page Object getter)
+
+| TestSpectra syntax                   | Semantic log output                     |
+| :----------------------------------- | :-------------------------------------- |
+| `await el.click()`                   | `Click on element "{el}"`               |
+| `await el.doubleClick()`             | `Double-click on {el}`                  |
+| `await el.rightClick()`              | `Right-click on {el}`                   |
+| `await el.type(text, options?)`      | `Type "{text}" into element "{el}"`     |
+| `await el.clear()`                   | `Clear text in {el}`                    |
+| `await el.select(option)`            | `Select option "{option}" in {el}`      |
+| `await el.hover()`                   | `Hover over {el}`                       |
+| `await source.dragDrop(dest)`        | `Drag {source} and drop onto {dest}`    |
+| `await el.scrollIntoView()`          | `Scroll {el} into view`                 |
+| `await el.longPress(durationMs)`     | `Long-press on {el} for {durationMs}ms` |
+| `await el.waitForElement(timeoutMs)` | `Wait for {el} to be displayed`         |
+
+`type()` accepts an options object, e.g. `{ clearFirst: true }` to clear the field before typing.
+
+---
+
+## 2. Element Assertions (called on a Page Object getter)
+
+| TestSpectra syntax                        | Semantic log output                                      |
+| :---------------------------------------- | :------------------------------------------------------- |
+| `await el.shouldBeVisible()`              | `Expect element "{el}" to be visible`                    |
+| `await el.shouldNotBeVisible()`           | `Expect element "{el}" not to be visible`                |
+| `await el.shouldExist()`                  | `Expect element "{el}" to exist in DOM`                  |
+| `await el.shouldNotExist()`               | `Expect element "{el}" not to exist in DOM`              |
+| `await el.shouldBeClickable()`            | `Expect element "{el}" to be clickable`                  |
+| `await el.shouldNotBeClickable()`         | `Expect element "{el}" not to be clickable`              |
+| `await el.shouldBeEnabled()`              | `Expect element "{el}" to be enabled`                    |
+| `await el.shouldBeDisabled()`             | `Expect element "{el}" to be disabled`                   |
+| `await el.shouldBeChecked()`              | `Expect element "{el}" to be checked`                    |
+| `await el.shouldNotBeChecked()`           | `Expect element "{el}" not to be checked`                |
+| `await el.shouldHaveText(text)`           | `Expect element "{el}" to have text "{text}"`            |
+| `await el.shouldContainText(substr)`      | `Expect element "{el}" to contain text "{substr}"`       |
+| `await el.shouldHaveValue(val)`           | `Expect element "{el}" to have value "{val}"`            |
+| `await el.shouldHaveAttribute(attr, val)` | `Expect element "{el}" attribute "{attr}" to be "{val}"` |
+| `await el.shouldBeFocused()`              | `Expect element "{el}" to be focused`                    |
+
+---
+
+## 3. Collection Matchers (on `Spectra.getAll(selector)` getters)
+
+| TestSpectra syntax                           | Semantic log output                                     |
+| :------------------------------------------- | :------------------------------------------------------ |
+| `await col.shouldHaveLength(n)`              | `Expect collection "{selector}" count to equal {n}`     |
+| `await col.shouldNotHaveLength(n)`           | `Expect collection "{selector}" count not to equal {n}` |
+| `await col.shouldHaveLengthGreaterThan(min)` | `count to be greater than {min}`                        |
+| `await col.shouldHaveLengthLessThan(max)`    | `count to be less than {max}`                           |
+| `await col.shouldBeEmpty()`                  | `Expect collection "{selector}" to be empty`            |
+| `await col.shouldNotBeEmpty()`               | `Expect collection "{selector}" not to be empty`        |
+
+---
+
+## 4. Global `Spectra.*` Commands
+
+| Category       | Syntax                                                                                                   |
+| :------------- | :------------------------------------------------------------------------------------------------------- |
+| Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                             |
+| Element query  | `Spectra.get(selector)` / `Spectra.getAll(selector)`                                                     |
+| Window         | `await Spectra.setViewport(1920, 1080)`                                                                  |
+| Timing         | `await Spectra.wait(1000)`                                                                               |
+| Keyboard       | `await Spectra.pressKey("Enter")`                                                                        |
+| Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                               |
+| Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                              |
+| Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill |
+
+## 5. `Spectra.browser.*` — Browser/Context Level
+
+| Syntax                                              | Purpose                         |
+| :-------------------------------------------------- | :------------------------------ |
+| `await Spectra.browser.clearCookies()`              | Clear all cookies               |
+| `await Spectra.browser.clearLocalStorage()`         | Clear localStorage              |
+| `await Spectra.browser.shouldHaveUrl(url)`          | Assert exact URL                |
+| `await Spectra.browser.shouldContainUrl(substr)`    | Assert URL contains substring   |
+| `await Spectra.browser.shouldHaveTitle(title)`      | Assert exact document title     |
+| `await Spectra.browser.shouldContainTitle(substr)`  | Assert title contains substring |
+| `await Spectra.browser.shouldBeLoaded()`            | Assert page fully loaded        |
+| `await Spectra.browser.shouldHaveNoConsoleErrors()` | Assert zero console errors      |
+
+---
+
+## 6. Full Example
+
+```typescript
+it('should login as administrator and assert dashboard metrics', async () => {
+  await Spectra.navigate('/auth/login');
+  await Spectra.browser.clearCookies();
+
+  await LoginPage.emailInput.type(Fixture.users.admin.email, { clearFirst: true });
+  await LoginPage.passwordInput.type(Fixture.users.admin.password);
+  await LoginPage.submitButton.click();
+
+  await DashboardPage.header.shouldBeVisible();
+  await DashboardPage.welcomeMsg.shouldHaveText('Welcome back, Admin');
+  await DashboardPage.statCards.shouldHaveLength(4);
+  await LoginPage.loadingSpinner.shouldNotBeVisible();
+
+  await Spectra.browser.shouldHaveUrl('https://app.testspectra.dev/dashboard');
+  await Spectra.browser.shouldHaveNoConsoleErrors();
+});
+```
+
+This is engine-agnostic: the exact same syntax dispatches to Chrome CDP on `web.test.ts` and to the
+native Android TCP driver on `android.test.ts` — never branch authoring code per platform inside a
+shared file; instead put platform-specific implementations in the correctly-suffixed file (see the
+`workspace-structure` skill).

package/skills/network-interception/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: network-interception
+description: The Spectra.intercept() API for deterministic network mocking in TestSpectra — InterceptRule/MockResponse/MockHandle shapes, respondOnce vs respondWith sequential polling, aborting requests, and waitForCall/callCount assertions. Use whenever a test needs to mock, stub, or assert on an API call instead of hitting the real backend.
+---
+
+# Skill: Network Interception (`Spectra.intercept`)
+
+Use this skill whenever a test needs deterministic control over a network response — mocking an
+API, simulating an error, or asserting a call happened — rather than depending on a real backend.
+
+---
+
+## 1. Rule & Handle Shapes
+
+```typescript
+interface InterceptRule {
+  url: string | RegExp; // supports glob, e.g. '**/api/v1/payments/charge'
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL';
+  response?: MockResponse | ((request: InterceptedRequest) => MockResponse | Promise<MockResponse>);
+}
+
+interface MockResponse {
+  status?: number; // default: 200
+  headers?: Record<string, string>;
+  body?: any;
+  delayMs?: number;
+}
+
+interface MockHandle {
+  respondWith(response: MockResponse): this; // default response for all subsequent matches
+  respondOnce(response: MockResponse): this; // one-time FIFO-queued response
+  abort(errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset'): this;
+  waitForCall(options?: { timeout?: number; count?: number }): Promise<InterceptedRequest>;
+  readonly callCount: number;
+  readonly calls: InterceptedRequest[];
+}
+```
+
+`Spectra.intercept(rule)` is `async` and returns a `MockHandle` — always `await` it before
+interacting with the UI that triggers the call.
+
+---
+
+## 2. Pattern: Single-Shot Static Mock
+
+```typescript
+it('should mock payment failure response gracefully', async () => {
+  const paymentMock = await Spectra.intercept({
+    url: '**/api/v1/payments/charge',
+    method: 'POST',
+    response: {
+      status: 402,
+      headers: { 'content-type': 'application/json' },
+      body: { error: 'insufficient_funds', message: 'Your card was declined due to insufficient funds.' },
+    },
+  });
+
+  await CheckoutPage.submitPaymentButton.click();
+
+  await paymentMock.waitForCall({ timeout: 5000 });
+  expect(paymentMock.callCount).toBe(1);
+
+  await CheckoutPage.errorBanner.shouldBeVisible();
+  await CheckoutPage.errorBanner.shouldContainText('insufficient funds');
+});
+```
+
+---
+
+## 3. Pattern: Multi-Response Sequential Polling
+
+Use `respondOnce` (FIFO queue, consumed one per matching request) plus a trailing `respondWith`
+default for status-polling / retry flows:
+
+```typescript
+it('should poll export job status until completed', async () => {
+  const jobMock = await Spectra.intercept({ url: '**/api/v1/export/job-99', method: 'GET' });
+
+  jobMock.respondOnce({ status: 200, body: { status: 'pending' } });
+  jobMock.respondOnce({ status: 200, body: { status: 'processing' } });
+  jobMock.respondWith({ status: 200, body: { status: 'completed', downloadUrl: '/files/report.pdf' } });
+
+  await ExportPage.startExportButton.click();
+  await ExportPage.downloadLink.shouldBeVisible();
+});
+```
+
+---
+
+## 4. Pattern: Simulating a Network Failure
+
+```typescript
+it('should handle offline mode gracefully when sync fails', async () => {
+  const syncMock = await Spectra.intercept({ url: '**/api/v1/sync' });
+  syncMock.abort('ConnectionReset');
+
+  await DashboardPage.syncButton.click();
+  await DashboardPage.offlineBanner.shouldBeVisible();
+});
+```
+
+---
+
+## 5. Conventions
+
+- Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
+  environment/base-URL changes between local, staging, and CI.
+- Only mock what the test is actually about — don't blanket-intercept every domain; the linter and
+  reviewers expect `monitoredDomains` in `spectra.config.ts` (see the `workspace-structure` skill)
+  to reflect real traffic, and over-mocking hides real integration regressions.
+- Always assert on the mock (`waitForCall` / `callCount`) when the test's purpose is to verify the
+  request was made — don't just assert on UI state and silently hope the mock fired.
+- Every real (non-mocked) network call made during a run is separately captured and written to
+  `.testspectra/reports/network-resources.json` for post-run diagnostics — you don't need to record
+  this yourself.

package/skills/page-objects-and-selectors/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: page-objects-and-selectors
+description: How to write a TestSpectra Page Object (Spectra.get / Spectra.getAll singleton pattern) and how the ~accessibility-id vs #native-id selector contract resolves identically across Web, Android, and iOS. Use whenever declaring element locators or a new Page Object.
+---
+
+# Skill: Page Objects & the Selector Contract
+
+Use this skill whenever you add a new Page Object, add a getter to an existing one, or need to
+pick a selector string.
+
+---
+
+## 1. Page Object Pattern
+
+A Page Object is a class with getter properties that return `Spectra.get(selector)` /
+`Spectra.getAll(selector)`, exported as a singleton default export, and consumed with **zero
+imports** anywhere else in the workspace (see the `workspace-structure` skill).
+
+```typescript
+// page-objects/MatchersPage/web.ts
+class MatchersPage {
+  get visibleElement() {
+    return Spectra.get('#demo-visible-el');
+  }
+  get hiddenElement() {
+    return Spectra.get('#demo-hidden-el');
+  }
+  get existingElement() {
+    return Spectra.get('#demo-existing-el');
+  }
+  get productCards() {
+    return Spectra.getAll('.demo-product-card');
+  } // collection
+
+  async open(section = '') {
+    await Spectra.navigate('/' + (section ? '#' + section : ''));
+  }
+}
+
+export default new MatchersPage();
+```
+
+Rules:
+
+- One getter per element/collection; name the getter for what the element _is_ (`submitButton`,
+  `statCards`), not for the selector string.
+- `Spectra.get(selector)` → single element; `Spectra.getAll(selector)` → collection (used with
+  collection matchers like `.shouldHaveLength(n)`).
+- Add reusable navigation/composite helpers as regular `async` methods on the same class (e.g.
+  `open()` above), not as standalone actions, when they are specific to that one page.
+- File suffix follows the platform-suffix rule: `web.ts` for CSS selectors, `mobile.ts` /
+  `android.ts` / `ios.ts` for native selectors targeting the same logical page.
+
+---
+
+## 2. Selector Contract: `~name` vs `#name`
+
+TestSpectra resolves selectors identically across every platform — a selector written once means
+the same thing everywhere. Each prefix maps to **exactly one** attribute; there is no silent
+cross-matching.
+
+| Selector           | Meaning              | Web                     | Android                          | iOS                      |
+| :----------------- | :------------------- | :---------------------- | :------------------------------- | :----------------------- |
+| `~name`            | **accessibility id** | `[aria-label="name"]`   | `content-desc`                   | accessibility identifier |
+| `#name`            | **native id**        | CSS `#name`             | `resource-id`                    | — (n/a)                  |
+| `//xpath`          | raw XPath            | delegated to the driver | delegated to the on-device agent | n/a                      |
+| `name` (no prefix) | lenient fallback     | n/a                     | native id, then accessibility id | n/a                      |
+
+### Which one to use
+
+- **Prefer `~name`** for anything a user can perceive — it's the portable, semantic, recommended
+  default across all platforms.
+- **Use `#name`** only when the element has a stable test/native id and no accessibility label
+  (React Native `testID`, Android `resource-id`, CSS `id`).
+- Set the _matching_ attribute on the app/page element so the selector actually resolves:
+
+```tsx
+// React Native — these resolve DIFFERENT selectors:
+<Pressable accessibilityLabel="submit-button" />   // → Spectra.get('~submit-button')
+<Pressable testID="submit-button" />                // → Spectra.get('#submit-button')
+```
+
+```html
+<!-- Web -->
+<button aria-label="submit-button">…</button>
+<!-- → Spectra.get('~submit-button') -->
+<button id="submit-button">…</button>
+<!-- → Spectra.get('#submit-button') -->
+```
+
+- When `testID` and `accessibilityLabel` are set to the same value, `~name` and `#name` are
+  interchangeable; they diverge the moment the two attributes differ.
+- Avoid the unprefixed lenient form (`name`) in new tests — it's Android-only leniency kept for
+  backwards compatibility, not part of the cross-platform contract. Always write an explicit `~`
+  or `#`.
+- Avoid raw `//xpath` unless there is genuinely no stable id/label to hook into — it's brittle and
+  bypasses the fast, cached full-hierarchy snapshot lookup that `~`/`#` selectors use on Android.
+
+---
+
+## 3. Never Use Raw `$` / `$$` / `browser` / `driver`
+
+TestSpectra encapsulates the entire runtime into a single global `Spectra` object. There is no raw
+WebdriverIO `$`, `$$`, `browser`, or `driver` in test-authoring code — always go through
+`Spectra.get()` / `Spectra.getAll()` for locators and `Spectra.*` / `Spectra.browser.*` for
+everything else (navigation, gestures, storage, network). See the `matchers-and-assertions` skill
+for the full command surface.

package/skills/shared-steps-and-actions/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: shared-steps-and-actions
+description: The difference between TestSpectra Shared Steps (Step.*, high-level business workflows, documented in spec.md via @step) and Spectra Actions (support/actions, low-level technical utilities) — directory layout, the mandatory anonymous async default export convention, and ambient type generation. Use whenever extracting reusable logic out of a test script.
+---
+
+# Skill: Shared Steps vs. Custom Actions
+
+Use this skill when you're about to extract repeated logic (e.g. login, checkout) out of test
+scripts, or when deciding whether new reusable logic belongs under `support/steps/` or
+`support/actions/`.
+
+---
+
+## 1. Which One Do I Need?
+
+| Attribute         | Shared Steps (`Step.*`)                        | Custom Actions (`Spectra.*` / on-element helpers)                             |
+| :---------------- | :--------------------------------------------- | :---------------------------------------------------------------------------- |
+| Abstraction level | High-level business workflow (login, checkout) | Low-level technical utility                                                   |
+| Directory         | `support/steps/<stepName>/`                    | `support/actions/<actionName>/`                                               |
+| Spec mapping      | Documented as `@step:<name>` in `spec.md`      | Just called inline, not listed in spec steps                                  |
+| Metadata file     | `step.md` (YAML frontmatter + description)     | None — implementation file only                                               |
+| Files             | `step.md` + `web.step.ts` [+ `mobile.step.ts`] | `web.action.ts` [+ `mobile.action.ts`]                                        |
+| Invocation        | `await Step.loginAsAdmin(params)`              | Called as a helper bound to an element/page, e.g. inside a Page Object method |
+
+Rule of thumb: if it's a multi-step _business_ flow a human would describe in one sentence
+("log in as admin"), it's a **Step**. If it's a small technical helper reused across Page Objects
+(a resilient click retry, filling a pair of fields), it's an **Action**.
+
+---
+
+## 2. Directory Layout
+
+```
+support/
+├── steps/
+│   └── loginAsAdmin/
+│       ├── step.md            # Metadata, docs, parameter types
+│       ├── web.step.ts
+│       └── mobile.step.ts     # optional
+└── actions/
+    └── fillCredentials/
+        ├── web.action.ts
+        └── mobile.action.ts
+```
+
+Both use **camelCase** directory/function names (`loginAsAdmin`, `fillCredentials`,
+`applyDiscount`, `verifyOtp`) — never kebab-case or snake_case.
+
+---
+
+## 3. `step.md` Metadata
+
+```markdown
+---
+id: step-login-as-admin
+name: loginAsAdmin
+description: Authenticates as an administrator and asserts landing dashboard
+platform:
+  - web
+  - mobile
+tags:
+  - auth
+  - admin
+parameters:
+  - name: email
+    type: string
+    required: false
+    description: Admin email address (defaults to Fixture.users.admin.email)
+  - name: password
+    type: string
+    required: false
+    description: Admin password (defaults to Fixture.users.admin.password)
+---
+
+# Login as Admin Step
+
+## Purpose
+
+Provides a standard, hardened administrative login sequence for web and mobile platforms.
+
+## Prerequisites
+
+- User fixture file exists at `fixtures/users.json`.
+- Browser is navigated to the base URL or login route.
+```
+
+---
+
+## 4. Implementation: Anonymous Async Default Export (Mandatory)
+
+Every `*.step.ts` and `*.action.ts` file exports **one anonymous async function as its default
+export** — no named exports, no `test()`/`it()` blocks. This is enforced by the linter
+(`testspectra/require-anonymous-default-export`).
+
+```typescript
+// support/steps/loginAsAdmin/web.step.ts
+export default async function (params?: { email?: string; password?: string }) {
+  const email = params?.email ?? Fixture.users.admin.email;
+  const password = params?.password ?? Fixture.users.admin.password;
+
+  await Spectra.navigate('/auth/login');
+  await LoginPage.emailInput.type(email, { clearFirst: true });
+  await LoginPage.passwordInput.type(password);
+  await LoginPage.submitButton.click();
+
+  await DashboardPage.header.shouldBeVisible();
+}
+```
+
+Custom Actions follow the same shape and are commonly written with a `this` receiver so they can
+be attached/bound as element/page helpers:
+
+```typescript
+// support/actions/fillCredentials/web.action.ts
+export default async function (this: any, email: string, token: string) {
+  await this.get('#demo-email-input-pg').type(email);
+  await this.get('#demo-token-input-pg').type(token);
+}
+```
+
+```typescript
+// support/actions/fillCredentials/mobile.action.ts
+export default async function (this: any, email: string, token: string) {
+  await this.get('~pg-email-input').type(email);
+  await this.get('~pg-token-input').type(token);
+}
+```
+
+Zero-import applies here too: never manually `import` a Page Object, `Fixture`, or `Spectra` — see
+the `workspace-structure` skill.
+
+---
+
+## 5. Type Generation & Invocation
+
+The `TypeGenerator` scans `support/steps/` and emits the `Step` ambient namespace automatically:
+
+```typescript
+declare global {
+  namespace Step {
+    function loginAsAdmin(params?: { email?: string; password?: string }): Promise<void>;
+  }
+}
+```
+
+### In `spec.md` (documents the step as part of the human-readable flow):
+
+```markdown
+## Test Steps
+
+1. @step:loginAsAdmin
+2. Navigate to user settings page
+3. Update profile avatar
+```
+
+### In `web.test.ts` (invokes it with zero manual imports):
+
+```typescript
+it('should update admin profile avatar', async () => {
+  await Step.loginAsAdmin();
+
+  await SettingsPage.openProfile();
+  await SettingsPage.avatarInput.type('avatar.png');
+  await SettingsPage.successToast.shouldBeVisible();
+});
+```
+
+Every `@step:<name>` in `spec.md` must have a matching `Step.<name>()` call in the paired test
+script, or `spectra lint` reports `testspectra/missing-step-call`. See the
+`spec-and-suite-authoring` skill for the full linter rule matrix.
+
+---
+
+## 6. Renaming a Step or Action
+
+Never rename a step/action folder by hand. Use:
+
+```
+spectra refactor step loginAsAdmin authenticateAdmin
+```
+
+This atomically: renames `support/steps/loginAsAdmin/` → `support/steps/authenticateAdmin/`,
+updates `name:` in `step.md`, rewrites every `@step:loginAsAdmin` in every `spec.md`, rewrites
+every `Step.loginAsAdmin()` call site, and regenerates `.testspectra/types/steps.d.ts`.