@testspectra/skills 1.1.0-rc.0

package/dist/registry.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+function parseSkillContent(id, content) {
+    let name = id;
+    let description = 'TestSpectra script-authoring skill';
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+    if (frontmatterMatch) {
+        const fm = frontmatterMatch[1];
+        const nameMatch = fm.match(/^name:\s*(.+)$/m);
+        const descMatch = fm.match(/^description:\s*(.+)$/m);
+        if (nameMatch)
+            name = nameMatch[1].trim();
+        if (descMatch)
+            description = descMatch[1].trim();
+    }
+    return { id, name, description, content };
+}
+function findSkillsDir() {
+    // dist/registry.js -> ../skills ; src/registry.ts (ts-node/dev) -> ../skills
+    const candidates = [
+        path.resolve(__dirname, '../skills'),
+        path.resolve(__dirname, '../../skills'),
+    ];
+    return candidates.find((dir) => fs.existsSync(dir));
+}
+export function loadAllSkills() {
+    const skillsDir = findSkillsDir();
+    if (!skillsDir)
+        return [];
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
+        if (fs.existsSync(skillMdPath)) {
+            const content = fs.readFileSync(skillMdPath, 'utf-8');
+            skills.push(parseSkillContent(entry.name, content));
+        }
+    }
+    return skills.sort((a, b) => a.id.localeCompare(b.id));
+}
+export function getSkill(id) {
+    const all = loadAllSkills();
+    return all.find((s) => s.id === id || s.name === id);
+}

package/dist/skills/fixtures-data/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: fixtures-data
+description: TestSpectra test data fixtures — JSON files under fixtures/, auto-typed globally under Fixture.* with zero imports, and how to reference/refactor them from test scripts, steps, and hooks. Use whenever a test needs static mock data (credentials, catalog items, payloads, locales).
+---
+
+# Skill: Fixture & Test Data Management
+
+Use this skill whenever a test case, shared step, or hook needs static data — user credentials,
+product catalogs, mock API payloads, localization strings.
+
+---
+
+## 1. Directory & Storage
+
+```
+workspace-root/
+└── fixtures/
+    ├── users.json             # User roles & credential sets
+    ├── products.json          # Catalog items & SKU metadata
+    ├── api-payloads.json      # Mock response payloads
+    └── locales.json           # Localization dictionaries
+```
+
+```json
+// fixtures/users.json
+{
+  "admin": {
+    "id": "usr-admin-01",
+    "name": "System Administrator",
+    "email": "admin@testspectra.dev",
+    "password": "Password123!",
+    "role": "admin"
+  },
+  "standardUser": {
+    "id": "usr-std-02",
+    "name": "Jane Doe",
+    "email": "jane.doe@testspectra.dev",
+    "password": "Password123!",
+    "role": "member"
+  }
+}
+```
+
+---
+
+## 2. Ambient Typing (Zero Import)
+
+The `TypeGenerator` watches `fixtures/` and emits `.testspectra/types/fixtures.d.ts` automatically
+whenever a fixture file is created/updated:
+
+```typescript
+declare global {
+  namespace Fixture {
+    const users: typeof import('../../fixtures/users.json');
+    const products: typeof import('../../fixtures/products.json');
+  }
+}
+```
+
+Never hand-write this file, and never `import` a fixture JSON file directly — always access it via
+the global `Fixture.<fileBaseName>` namespace, exactly like Page Objects and `Step.*`.
+
+---
+
+## 3. Usage
+
+### In test scripts
+
+```typescript
+it('should login with admin credentials from fixture', async () => {
+  await Spectra.navigate('/auth/login');
+  await LoginPage.emailInput.type(Fixture.users.admin.email, { clearFirst: true });
+  await LoginPage.passwordInput.type(Fixture.users.admin.password);
+  await LoginPage.submitButton.click();
+
+  await DashboardPage.welcomeMsg.shouldContainText(Fixture.users.admin.name);
+});
+```
+
+### In shared steps
+
+```typescript
+// support/steps/loginUser/web.step.ts
+export default async function (userType: 'admin' | 'standardUser' = 'standardUser') {
+  const user = Fixture.users[userType];
+  await Spectra.navigate('/auth/login');
+  await LoginPage.emailInput.type(user.email, { clearFirst: true });
+  await LoginPage.passwordInput.type(user.password);
+  await LoginPage.submitButton.click();
+}
+```
+
+Fixtures are freely usable inside hooks too (e.g. `global-hooks/before` seeding a DB via `fetch`
+with `Fixture.apiPayloads.seedUser`).
+
+---
+
+## 4. Renaming a Fixture
+
+Never rename a fixture file by hand. Use:
+
+```
+spectra refactor fixture users accounts
+```
+
+This renames `fixtures/users.json` → `fixtures/accounts.json`, rewrites every `Fixture.users`
+reference across `specs/**/*.test.ts`, `support/steps/**/*.step.ts`, and `hooks/**` to
+`Fixture.accounts`, and regenerates `.testspectra/types/fixtures.d.ts` immediately with 0
+TypeScript errors.

package/dist/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/dist/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/dist/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/dist/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.