skeptic-cli 0.2.1 → 1.0.0

package/AGENTS.md

@@ -27,8 +27,8 @@ spec.
 
 The npm package installs a managed `skeptic` skill for Claude Code, Codex,
 Cursor, and OpenCode into user-level skill directories when `npm install` runs.
-Use that skill when an agent needs browser QA, spec authoring, or MCP browser
-tool guidance.
+Use that skill when an agent needs browser QA, spec authoring, or interactive
+browser-session driving.
 
 Manual install commands:
 
@@ -78,7 +78,6 @@ Rules for generated or hand-written specs:
 | `screenshot(name, opts?)` | PNG capture with optional ref annotations |
 | `settle()` | Best-effort network-idle settle |
 | `observability` | Performance, network, console, and accessibility assertions |
-| `ai` | Vision-backed assertions, defect checks, and text extraction |
 | `ctx` | Per-test execution context |
 
 ### Snapshot Helpers
@@ -185,60 +184,28 @@ Annotated screenshots add numbered labels over interactive refs and return an
 annotation map without accessible names, so structured metadata does not repeat
 potentially sensitive page text.
 
-## AI
+## Browser Session Verbs
 
-Configure a provider and key before using AI helpers.
-
-```yaml
-ai:
-  provider: openai
-  model: gpt-4o
-```
-
-```ts
-await ai.assert("the success toast is visible");
-await ai.assertNoDefects();
-const total = await ai.extract("invoice total");
-```
-
-Use:
+Skeptic is agent-native — you drive a persistent browser from the shell, no MCP
+server and no built-in AI/keys. A daemon holds the session so `@eN` refs persist
+between commands:
 
 ```bash
-skeptic generate --message "test checkout"
-skeptic generate --diff
-skeptic run --analyze
-```
-
-Generated tests are typechecked and imported before being written.
-
-## MCP Browser Tools
-
-When Skeptic is exposed through MCP, prefer its browser tools for page QA:
-
-| Tool | Use |
-|---|---|
-| `browser_open` | Navigate using project browser/auth/safety config |
-| `browser_snapshot` | Capture refs and snapshot text |
-| `browser_playwright` | Run focused Playwright code with `page`, `context`, `browser`, `ref` |
-| `browser_screenshot` | Capture PNG, annotated PNG, or snapshot-only output |
-| `browser_console_logs` | Read captured console messages |
-| `browser_network_requests` | Read requests and computed issues |
-| `browser_performance_metrics` | Capture Web Vitals, LoAF, resources, and `perf-trace.md` |
-| `browser_accessibility_audit` | Run axe-core plus IBM Equal Access when available |
-| `browser_close` | Close the session |
-
-MCP browser tools honor:
-
-```yaml
-safety:
-  allowedDomains: ["example.com", "*.example.org"]
-  actionPolicy: .skeptic/action-policy.json
-  confirmActions: ["browser_playwright"]
-  maxOutputChars: 120000
-  contentBoundaries: true
+skeptic open https://app.example.com    # opens a session
+skeptic snapshot -i                      # mints @e1.. refs + selectorHints
+skeptic click @e3
+skeptic fill @e5 "user@test.com"
+skeptic snapshot -i                      # re-snapshot after the DOM changed
+skeptic console --errors
+skeptic screenshot --full                # returns a file path
+skeptic close
 ```
 
-`confirmActions` fail closed in MCP because stdio tools cannot prompt safely.
+Verbs: `open`, `snapshot` (`-i`/`-c`), `click`, `fill`, `type`, `press`, `hover`,
+`check`, `uncheck`, `select`, `get`, `screenshot`, `console`, `wait`, `list`,
+`close`. Add `--json` to any verb; `--session <name>` for isolated sessions;
+`--headless` on `open` for CI. Re-snapshot after navigation — refs invalidate on
+DOM change and acting on a stale ref returns a clear `[ariaRef:stale]` error.
 
 ## Evidence
 
@@ -284,7 +251,7 @@ output:
 
 ```bash
 skeptic add github-action
-skeptic add github-action --ai --provider openai
+skeptic add github-action --dev-command "npm run dev" --dev-url http://localhost:3000
 skeptic comment --results ./skeptic-output/results.json
 ```
 

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 iamjr15
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Third-party components redistributed inside the published bundle are listed,
+with their own license terms and attributions, in LICENSES.md.

package/LICENSES.md

@@ -1,9 +1,98 @@
 # Third-party licenses and attributions
 
 skeptic-cli is distributed under the [MIT License](#mit-license-skeptic-cli)
-(see `package.json:license`). Portions of skeptic are derived from upstream
-projects under their own terms; those terms and the corresponding NOTICE
-attributions follow.
+(see `package.json:license`). Two kinds of third-party material are covered
+below: (1) npm dependencies that are **inlined into the published bundle**
+(`dist/skeptic.mjs`) at build time, and (2) source code **derived from upstream
+projects**. Their terms and the corresponding NOTICE attributions follow.
+
+## Bundled npm dependencies
+
+The published `skeptic-cli` bundle inlines several pure-JS dependencies at build
+time — the `noExternal` list in `tsup.config.ts` — instead of resolving them
+from `node_modules` at runtime. Their license terms are reproduced or pointed to
+here. Runtime-external dependencies (`playwright`, `playwright-core`, and the
+optional `better-sqlite3` and `accessibility-checker-engine`) are installed
+separately and keep their own license files in your `node_modules`.
+
+### Mozilla Public License 2.0 — axe-core, @axe-core/playwright
+
+The accessibility audit inlines **axe-core** (via its Playwright wrapper
+**@axe-core/playwright**), © Deque Systems, Inc., licensed under the
+**Mozilla Public License, Version 2.0 (MPL-2.0)**.
+
+MPL-2.0 is a file-level copyleft: because skeptic distributes these files in
+executable (bundled) form, the corresponding **source is made available** to
+recipients at:
+
+- `axe-core` — https://github.com/dequelabs/axe-core (npm: `axe-core@4.11.x`)
+- `@axe-core/playwright` — https://github.com/dequelabs/axe-core-npm
+  (npm: `@axe-core/playwright@4.11.x`)
+
+The full MPL-2.0 text is available at https://www.mozilla.org/en-US/MPL/2.0/.
+Per MPL-2.0 Exhibit A, the covered source is governed by this notice:
+
+```
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+```
+
+### Apache License 2.0 — web-vitals
+
+**web-vitals** © Google LLC is licensed under the Apache License 2.0 and is
+shipped both inlined and as the standalone `dist/web-vitals.iife.js` asset.
+Source: https://github.com/GoogleChrome/web-vitals. The full Apache 2.0 text is
+reproduced in the [agent-browser section below](#apache-license-20-full-text).
+
+### Apache License 2.0 — accessibility-checker-engine
+
+**accessibility-checker-engine** (IBM Equal Access Accessibility Checker)
+© IBM, Inc. is an **optional, runtime-external** dependency — resolved from
+`node_modules` by `src/observability/collectors/accessibility-collector.ts`
+when present (the audit falls back to axe-core only when it is absent), not
+inlined into the bundle — licensed under the **Apache License 2.0**. Source:
+https://github.com/IBMa/equal-access. The full Apache 2.0 text is reproduced in
+the [agent-browser section below](#apache-license-20-full-text).
+
+### Blue Oak Model License 1.0.0 — glob, minimatch
+
+**glob** and **minimatch** © Isaac Z. Schlueter and contributors are licensed
+under the **Blue Oak Model License 1.0.0**. Full text:
+https://blueoakcouncil.org/license/1.0.0.
+
+### ISC License — yaml, pixelmatch
+
+**yaml** © Eemeli Aro and **pixelmatch** © Mapbox are licensed under the ISC
+license (a permissive, functionally-MIT-equivalent license). Full texts ship in
+each package's `node_modules` distribution.
+
+### MIT License — commander, zod, chokidar, chalk, figures, cli-truncate, string-width, pretty-ms, pngjs, react, ink, ink-spinner
+
+The following bundled dependencies are licensed under the MIT License and carry
+their own copyright notices in their respective packages:
+
+| Package | Copyright holder |
+|---|---|
+| commander | TJ Holowaychuk and contributors |
+| zod | Colin McDonnell |
+| chokidar | Paul Miller |
+| chalk | Sindre Sorhus |
+| figures | Sindre Sorhus |
+| cli-truncate | Sindre Sorhus |
+| string-width | Sindre Sorhus |
+| pretty-ms | Sindre Sorhus |
+| pngjs | the pngjs contributors |
+| react | Meta Platforms, Inc. and affiliates |
+| ink | Vadim Demedes |
+| ink-spinner | Vadim Demedes |
+
+Each MIT/ISC/BlueOak license is permissive and grants redistribution provided
+the copyright notice and permission text are preserved; those texts are
+distributed inside each package and reproduced under the canonical license URLs
+cited above. (skeptic carries no bundled AI/MCP/ACP SDKs — those dependencies
+and their attributions were removed when the AI, MCP, and ACP subsystems were
+deleted.)
 
 ## NOTICE — agent-browser (Apache License 2.0)
 

package/README.md

@@ -43,8 +43,8 @@ skeptic observe https://example.com
 # Run TypeScript specs with full QA evidence
 skeptic run tests/homepage.spec.ts --observability --video --trace
 
-# Generate a validated TypeScript spec with AI
-skeptic generate -m "test the login page"
+# Drive a browser interactively from the shell (persistent session)
+skeptic open https://example.com && skeptic snapshot -i
 
 # Check local setup
 skeptic doctor
@@ -121,7 +121,6 @@ The fixture exposes:
 | `screenshot` | PNG screenshots, including annotated numbered-ref captures |
 | `settle` | Network-idle settle helper |
 | `observability` | Performance, network, console, and accessibility assertions |
-| `ai` | Vision-backed assertions, defect checks, and text extraction |
 | `ctx` | Per-test execution context and artifact paths |
 
 `expect` is re-exported from Playwright Test, so matchers like
@@ -249,53 +248,31 @@ It writes an output directory containing an HTML report, JSON report,
 screenshots, annotated screenshots, snapshot text/JSON, console/network data,
 performance summary, accessibility JSON, and an accessibility markdown audit.
 
-## AI Features
+## Browser Session Verbs
 
-Skeptic supports Gemini, OpenAI, and Anthropic.
+Skeptic is agent-native: a coding agent drives a persistent browser entirely from
+the shell. A daemon holds the session, so `@eN` refs from one `skeptic snapshot`
+stay valid for the next `skeptic click @eN` — across separate commands. There is
+no MCP/ACP server and no built-in AI: the host agent is the intelligence.
 
-```yaml
-ai:
-  provider: openai
-  model: gpt-4o
+```bash
+skeptic open https://app.example.com    # opens a session (default name "default")
+skeptic snapshot -i                      # mints @e1.. refs + stable selectorHints
+skeptic click @e3                        # act on a ref from the last snapshot
+skeptic fill @e5 "user@test.com"
+skeptic snapshot -i                      # re-snapshot after the DOM changed
+skeptic console --errors                 # check for uncaught errors
+skeptic screenshot --full                # returns a file path
+skeptic close
 ```
 
-Set the matching provider key with `GEMINI_API_KEY`, `OPENAI_API_KEY`, or
-`ANTHROPIC_API_KEY`. You can also use `SKEPTIC_AI_PROVIDER` and
-`SKEPTIC_AI_API_KEY` to override config in CI.
-
-Available AI paths:
-
-- `ai.assert("the dashboard greets the user")`
-- `ai.assertNoDefects()`
-- `ai.extract("the invoice total")`
-- `skeptic generate --message "test checkout"`
-- `skeptic generate --diff`
-- `skeptic run --analyze`
-
-Generated specs are typechecked and imported before being written.
-
-## MCP And ACP
-
-`skeptic mcp` exposes testing and browser QA tools over stdio:
-
-| Tool | Purpose |
-|---|---|
-| `list_tests` | Discover specs |
-| `validate_tests` | Typecheck and import-check specs |
-| `generate_test` | Generate a validated TypeScript spec |
-| `run_test` | Run specs and stream progress |
-| `browser_open` | Open a page with config-driven browser/auth/safety |
-| `browser_snapshot` | Capture ARIA/cursor refs |
-| `browser_playwright` | Run focused Playwright code |
-| `browser_screenshot` | Capture PNG, annotated PNG, or snapshot-only output |
-| `browser_console_logs` | Read console messages |
-| `browser_network_requests` | Read requests and computed issues |
-| `browser_performance_metrics` | Capture Web Vitals, LoAF, resources, and `perf-trace.md` |
-| `browser_accessibility_audit` | Run axe-core plus IBM Equal Access when available |
-| `browser_close` | Close the browser session |
-
-`skeptic acp` exposes a testing-focused agent server for editors that support
-Agent Client Protocol.
+Verbs: `open`, `snapshot` (`-i`/`-c`), `click`, `fill`, `type`, `press`, `hover`,
+`check`, `uncheck`, `select`, `get <text|box|url|title> [@ref]`, `screenshot`
+(`--full`/`--annotate`), `console` (`--errors`), `wait`, `list`, `close`
+(`--all`). Add `--json` to any verb. Use `--session <name>` for isolated parallel
+sessions; the session browser defaults to headed (`--headless` for CI/containers).
+Refs are minted per snapshot and invalidated by navigation — re-snapshot after any
+navigation or DOM change.
 
 ## Configuration
 
@@ -354,7 +331,7 @@ contexts and are not sent to Skeptic services.
 
 ```bash
 skeptic add github-action
-skeptic add github-action --ai --provider openai
+skeptic add github-action --dev-command "npm run dev" --dev-url http://localhost:3000
 ```
 
 The generated workflow installs dependencies, installs Chromium, starts your dev
@@ -393,8 +370,7 @@ skeptic daemon stop
 ```
 
 `skeptic doctor` checks config, output directories, browser installs, optional
-accessibility/cookie engines, daemon state, cookie profiles, and AI provider
-setup.
+accessibility/cookie engines, daemon state, and cookie profiles.
 
 ## License
 

package/agent-skills/skeptic/SKILL.md

@@ -1,44 +1,138 @@
 ---
 name: skeptic
-description: Use Skeptic for CLI-first browser QA and TypeScript E2E tests. Use when asked to inspect pages, write or run skeptic-cli specs, validate UI changes, capture observability evidence, or use Skeptic MCP tools. Not for unit-only logic with no browser behavior.
+description: Use Skeptic for CLI-first browser QA and TypeScript E2E tests. Use when asked to inspect pages, drive a browser interactively, write or run skeptic-cli specs, validate UI changes, or capture observability evidence. Not for unit-only logic with no browser behavior.
 ---
 
 <!-- skeptic-agent-skill: managed by skeptic-cli -->
 
 # Skeptic
 
-Use Skeptic when a coding agent needs browser evidence: page inspection, TypeScript E2E specs, one-off QA captures, AI-backed checks, or MCP browser validation. Do not claim a UI/browser change works until you have run a relevant Skeptic command or MCP tool and checked the evidence.
+Use Skeptic when you need browser evidence: interactive page-driving, page inspection, TypeScript E2E specs, one-off QA captures, or observability evidence. Do not claim a UI/browser change works until you have run a relevant Skeptic command and checked the evidence.
+
+Skeptic is **agent-native**: it has no model of its own, makes no LLM calls, and needs no API keys. You (the coding agent) are the intelligence; Skeptic is the deterministic hands and eyes. Everything is driven from the shell — there is no MCP server.
 
 ## Choose The Surface
 
-- Human interactive test run: run `skeptic tui`.
-- One-off QA or bug hunt: run `skeptic observe <url> --full-page`.
-- Persistent regression coverage: run `skeptic inspect <url> --interactive --compact --with-playwright-hints`, write a `tests/*.spec.ts`, then run `skeptic run`.
-- Changed-code verification: run existing specs with `skeptic run`, or use `skeptic generate --diff` to create one first.
-- Agent-integrated browser work: if Skeptic MCP tools are available, use `browser_open`, `browser_snapshot`, `browser_playwright`, `browser_screenshot`, `browser_console_logs`, `browser_network_requests`, `browser_performance_metrics`, `browser_accessibility_audit`, and `browser_close`.
+- **Drive a browser interactively** (click through a flow, check a fix): use the persistent session verbs — `skeptic open <url>`, `skeptic snapshot -i`, `skeptic click @e3`, etc. Refs persist between commands.
+- **One-off discovery** (get stable selectors to write a spec): `skeptic inspect <url> --interactive --compact --with-playwright-hints`.
+- **One-off QA / bug hunt** (full evidence bundle for one page): `skeptic observe <url> --full-page --video --trace`.
+- **Persistent regression coverage**: inspect, write a `tests/*.spec.ts`, then `skeptic run`.
+- **Changed-code verification**: run existing specs with `skeptic run`.
 
 If the `skeptic` binary is not on PATH, try `npx skeptic-cli` or `npx --yes skeptic-cli@latest`.
 
-Specs import from the project dependency `skeptic-cli`. A normal `skeptic init`
-writes that dependency to `package.json`. If specs fail with `Cannot find
-package 'skeptic-cli'`, run `npm install` in the project before re-running
-Skeptic.
+Specs import the project dependency `skeptic-cli`. A normal `skeptic init` writes that dependency to `package.json`. If specs fail with `Cannot find package 'skeptic-cli'`: in an initialized project run `npm install`; in a project that never ran `skeptic init`, run `skeptic init` first, then `npm install`.
+
+## Persistent Browser Session
+
+A daemon holds the browser, so `@eN` refs from one `skeptic snapshot` stay valid for the next `skeptic click @eN` — across separate commands. The loop:
+
+```bash
+skeptic open https://app.example.com    # opens a session (default name "default")
+skeptic snapshot -i                      # mints @e1.. refs + stable selectorHints
+skeptic click @e3                        # act on a ref from the last snapshot
+skeptic fill @e5 "user@test.com"
+skeptic snapshot -i                      # RE-SNAPSHOT after the DOM changed
+skeptic console --errors                 # check for uncaught errors
+skeptic screenshot --full                # returns a file path
+skeptic close                            # end the session
+```
+
+Verbs: `open`, `snapshot` (`-i` interactive, `-c` compact), `click`, `fill`, `type`, `press`, `hover`, `check`, `uncheck`, `select`, `get <text|box|url|title> [@ref]`, `screenshot` (`--full`, `--annotate`), `console` (`--errors`), `wait` (`--ms` or `--selector`), `list`, `close` (`--all`). Add `--json` to any verb for machine-readable output.
 
-## Fast Loop
+Rules:
+
+- **Re-snapshot after any navigation, route change, modal open/close, or DOM mutation.** Refs are minted per snapshot and invalidated by navigation; acting on a stale ref returns a clear `[ariaRef:stale]` error — re-run `skeptic snapshot`.
+- Prefer `@eN` refs from the latest snapshot; for selectors, use the `selectorHint` grammar (`role=button:Save`, `text=...`, `css=...`, `testid=...`).
+- Use `--session <name>` for parallel isolated sessions.
+- The session browser defaults to headed for local debugging; pass `--headless` on the first `open` for headless environments (CI/containers).
+- Binary outputs (screenshots) come back as file paths, not inline data.
+
+## Mobile (Android + iOS simulator)
+
+The same verbs drive a native app on a device. **Android** (`--platform android`)
+via `adb`; **iOS simulator** (`--platform ios-sim`) via `simctl` + `axe` (the idb
+accessibility-framework redistribution). Both are driver-less — no Appium, no
+WebDriverAgent, no in-app test bundle. `open` takes an app id (Android package /
+iOS bundle id) or a deep link instead of a URL.
+
+### Android (`--platform android`)
 
 ```bash
-skeptic doctor --quick
-skeptic inspect <url> --interactive --compact --with-playwright-hints
-skeptic run tests/<scenario>.spec.ts --observability --video --trace
+skeptic open com.example.app --platform android   # launches the app (am start -W)
+skeptic snapshot -i                                # uiautomator tree → @eN refs
+skeptic click @e5                                  # taps the node's center
+skeptic fill @e3 "user@test.com"                   # ASCII input
+skeptic is enabled @e5                             # element state (visible|enabled)
+skeptic screenshot                                 # device screencap → file path
+skeptic record --duration 5                        # screenrecord → .mp4
+skeptic perf                                        # gfxinfo jank + meminfo PSS + launch ms
+skeptic a11y                                        # uiautomator a11y heuristics
+skeptic network                                     # per-uid byte totals (degraded)
+skeptic console --errors                           # logcat (app-filtered)
+skeptic close
 ```
 
-For a page with no existing spec:
+Device evidence (parallels the web collectors; read via the verbs above):
+
+- **perf** — `dumpsys gfxinfo` (total/janky frames, frame-time percentiles, missed
+  vsync) + `meminfo` (PSS/RSS) + `am start -W` launch timings. A distinct shape from
+  web vitals (`platform: "android"`).
+- **a11y** — STRUCTURAL uiautomator heuristics only (unlabeled clickables, sub-48dp
+  touch targets, NAF nodes). No color-contrast check — the dump has no pixels.
+- **network** — `degraded: true` by default: Android exposes only per-uid byte totals,
+  never per-request URLs/status. Per-request capture needs an opt-in proxy.
+- `is checked` / `get value` aren't available on Android (the node doesn't retain them)
+  — they return a structured `[adbQuery:*_unsupported]` error; re-`snapshot` to read state.
+
+### iOS simulator (`--platform ios-sim`)
+
+Same verbs, against a **booted** simulator (`skeptic devices` lists them; boot with
+`xcrun simctl boot <udid>`). Requires a full **Xcode** (not just Command Line Tools)
+and **`axe`** (`brew install cameroncooke/axe/axe`) — skeptic finds Xcode itself, so
+no `sudo xcode-select` needed.
 
 ```bash
-skeptic observe <url> --full-page --video --trace
+skeptic open com.apple.Preferences --platform ios-sim   # bundle id or scheme:// link
+skeptic snapshot -i                                       # AXe accessibility tree → @eN refs
+skeptic click @e4                                         # taps the element's center
+skeptic fill @e14 "search text"                           # focuses + types (Cmd+A clear)
+skeptic screenshot
+skeptic console                                           # bounded unified-log (best-effort)
+skeptic close
 ```
 
-Use the generated `results.json`, `report.html`, screenshots, videos, traces, `network.json`, `console.json`, `accessibility.json`, and `perf-trace.md` as the evidence source. Reference artifact paths from `results.json` instead of guessing filenames.
+- Refs come from `axe describe-ui` (the accessibility tree). selectorHints prefer the
+  stable `id=<accessibility identifier>` › `label=` › `type=`. `snapshot()` auto-settles
+  (re-dumps until the layout stops animating) so taps land where the element *is* — iOS
+  launch / large-title animations move elements for ~1–2s.
+- iOS evidence is deliberately thin: `console` from the unified log only. perf/a11y/network
+  parity is a follow-up (the simulator exposes far less to an unprivileged host than Android).
+- Real iOS devices are out of scope (`axe`/`idb` UI automation is simulator-only).
+
+Mobile-specific guidance:
+
+- **Emulator GPU mode matters for visual evidence.** A headless emulator launched
+  with `-no-window` and the wrong `-gpu` mode returns BLANK screencaps/recordings.
+  skeptic detects this (a near-uniform frame) and attaches a `blank-screenshot`
+  diagnostic. Fix: relaunch with software rendering —
+  `emulator -avd <name> -gpu swiftshader_indirect` (drop `-no-window` if it persists).
+  uiautomator dumps and `dumpsys` evidence are unaffected (no GPU needed).
+- Refs come from a `uiautomator` accessibility dump (~1–3s each on a healthy
+  device). Re-snapshot after every screen change; prefer `res=` (resource-id)
+  and `desc=` (content-description) selectorHints over `text=`/`class=`.
+- **React Native:** `testID` surfaces as `resource-id` on RN ≥ 0.64 → use `res=`.
+  **Compose:** needs `Modifier.semantics { testTagsAsResourceId = true }`, else
+  nodes are generic `View`s (rely on `desc=`/`text=`). **Flutter:** needs the
+  semantics tree enabled, else the app is one opaque node — fall back to a
+  screenshot and tap by coordinates.
+- `adb` text input is ASCII-only; non-ASCII `fill`/`type` returns a structured
+  `[adbInput:unicode_unsupported]` error — set the value via a deep link or test
+  seam instead.
+- WebView contents are invisible to uiautomator; for in-WebView assertions, drive
+  the web surface separately.
+- iOS simulator support (`--platform ios-sim`, via `simctl` + `idb`) is planned;
+  real iOS devices are out of scope.
 
 ## Writing Specs
 
@@ -52,7 +146,7 @@ test("homepage smoke", async ({ page, snapshot, screenshot, observability }) =>
   await expect(page).toHaveTitle(/Example Domain/);
 
   const tree = await snapshot(page, { interactive: true, compact: true });
-  await tree.byRole("link", { name: "More information..." }).click();
+  await (await tree.byRef("e1")).click();
 
   await screenshot("homepage", { fullPage: true });
   await observability.expectNoConsoleErrors();
@@ -63,11 +157,42 @@ Rules:
 
 - Put browser side effects inside `test(...)`, hooks, or helper functions called from tests.
 - Prefer role, label, text, and test-id locators over CSS.
-- Use `snapshot(page)` before interacting through refs or snapshot helpers.
+- `await snapshot(page)` before interacting through refs; `tree.byRef("eN")` is async — always `await` it.
 - Re-snapshot after navigation, route changes, modal open/close, or major DOM mutation.
-- Do not paste CLI `@eN` refs directly into specs. Use `selectorHint` from `inspect`, or use `tree.byRef("eN")` only for refs returned by the same in-test `snapshot(page)` call.
+- Do not paste CLI `@eN` refs into specs. Use `selectorHint` from `inspect`, or `tree.byRef("eN")` only for refs from the same in-test `snapshot(page)` call.
 - Add `screenshot("name")` for states that would help debug a failure.
 
+### Android specs
+
+The same `test`/`expect`, runner, and `results.json` drive Android — run with
+`skeptic run <spec> --platform android` (`--target <serial>` to pick a device).
+Scaffold a starting spec with `skeptic scaffold <package> --platform android`.
+Specs get a **`device`** fixture instead of `page` (uiautomator refs, not
+Playwright locators):
+
+```ts
+import { test, expect } from "skeptic-cli";
+
+test("sessions screen loads", async ({ device }) => {
+  await device.open("app.fieldwork.android");      // package or scheme:// deep link
+  let snap = await device.snapshot();              // refs + selectorHints
+  if (snap.has("text=OK")) {                       // dismiss a dialog if present
+    await device.click("text=OK");
+    snap = await device.snapshot();                // re-snapshot after the change
+  }
+  expect(snap.has("Search sessions")).toBe(true);  // match selectorHint / name / role:name
+  await device.screenshot("sessions");
+});
+```
+
+- Targets accept an `@eN` ref from the **last** `device.snapshot()` or a
+  selectorHint (`res=`/`desc=`/`text=`). Re-`snapshot()` after every screen change.
+- `device.is("visible"|"enabled"|"checked", target)` and `device.get("text"|"value", target)`
+  read state; `device.scroll("@e5")` (into view) or `device.scroll({ dy: 600 })` (pan).
+- The run auto-attaches mobile evidence to `results.json`: `console` (logcat),
+  `mobilePerformance` (gfxinfo/meminfo/launch), `mobileAccessibility`, `mobileNetwork`.
+- Using `page` in an android spec (or `device` in a web spec) throws a clear error.
+
 ## Observability Checks
 
 Use `--observability` for real QA evidence. In specs, assert the signals that match the risk:
@@ -79,27 +204,14 @@ await observability.expectPerformance({ lcp: "<2500ms", cls: "<0.1" });
 await observability.expectAccessible({ standard: "WCAG21AA" });
 ```
 
-If an observability artifact reports a failure, fix the product or the test and re-run the same flow immediately.
-
-## MCP Workflow
-
-When Skeptic is exposed through MCP:
-
-1. `browser_open` the target URL.
-2. `browser_snapshot` or `browser_screenshot` with snapshot mode to get refs.
-3. Use one `browser_playwright` call for actions that share the same DOM state. Use the `ref` helper for snapshot refs and `return` structured evidence.
-4. After DOM-changing actions, request a fresh snapshot.
-5. Check `browser_console_logs`, `browser_network_requests`, `browser_accessibility_audit`, and `browser_performance_metrics`.
-6. `browser_close` when done so video and trace artifacts flush.
-
-Batch fills, clicks, and data collection when the DOM is stable. Do not take a new snapshot between plain text fills unless the page structure changed.
+`skeptic run` always writes `results.json` to the output dir (default `./skeptic-output`). Use it plus screenshots, videos, traces, `network.json`, `console.json`, `accessibility.json`, and `perf-trace.md` as the evidence source. Reference artifact paths from `results.json` instead of guessing filenames. If an observability artifact reports a failure, fix the product or the test and re-run the same flow immediately.
 
 ## Verification Standard
 
 Before reporting completion for browser-facing work:
 
-- Run the smallest Skeptic command or MCP workflow that actually exercises the changed behavior.
+- Run the smallest Skeptic command (session verbs or a spec) that actually exercises the changed behavior.
 - Test at least one adjacent or negative path when forms, routing, validation, auth, persistence, or shared components changed.
-- Read the full command/tool output. Passing navigation alone is not enough.
+- Read the full command output. Passing navigation alone is not enough.
 - If there are console errors, network failures, serious accessibility issues, poor Web Vitals, or visible regressions, fix and re-run.
-- State the exact command/tool run and the main artifact path in the final report.
+- State the exact command run and the main artifact path in the final report.

package/dist/adb-DUGGW3FV.mjs

@@ -0,0 +1,2 @@
+import {createRequire}from'node:module';export{a as createAdb,c as escapeInputText,b as isAsciiInput,d as listDevices}from'./chunk-G22LGRZ4.mjs';import'./chunk-2YKSIUIN.mjs';/*! @license skeptic-cli — see LICENSES.md for third-party attributions */
+createRequire(import.meta.url);

package/dist/adb-driver-TBOCCKEO.mjs

@@ -0,0 +1,3 @@
+import {createRequire}from'node:module';import {a as a$1}from'./chunk-BIGNULF6.mjs';import {d,a}from'./chunk-G22LGRZ4.mjs';import'./chunk-N3533BCE.mjs';import'./chunk-ZN6MI2TU.mjs';import'./chunk-MHNEFL35.mjs';import'./chunk-S3M2RTHJ.mjs';import'./chunk-2YKSIUIN.mjs';/*! @license skeptic-cli — see LICENSES.md for third-party attributions */
+createRequire(import.meta.url);
+var n=class i{constructor(e,r){this.serial=e;this.adb=r;}serial;adb;static async create(e={}){let r=e.serial;if(!r){let t=(await d(e.adbPath)).filter(b=>b.state==="device");if(t.length===0)throw new Error("no Android device/emulator attached (adb devices is empty); boot one first");r=t[0].serial;}let d$1=e.adb??a({serial:r,...e.adbPath?{adbPath:e.adbPath}:{}});return new i(r,d$1)}static fromAdb(e,r){return new i(e,r)}newSession(e){let r=e?.artifactDir??process.cwd();return Promise.resolve(new a$1(this.adb,this.serial,r))}close(){return Promise.resolve()}};export{n as AdbDriver};

package/dist/adb-session-AVVXL3QQ.mjs

@@ -0,0 +1,2 @@
+import {createRequire}from'node:module';export{a as AndroidAdbDriverSession,b as detectBlankCapture}from'./chunk-BIGNULF6.mjs';import'./chunk-G22LGRZ4.mjs';import'./chunk-N3533BCE.mjs';import'./chunk-ZN6MI2TU.mjs';import'./chunk-MHNEFL35.mjs';import'./chunk-S3M2RTHJ.mjs';import'./chunk-2YKSIUIN.mjs';/*! @license skeptic-cli — see LICENSES.md for third-party attributions */
+createRequire(import.meta.url);