tamash-playwright 0.13.0-beta.3 → 0.13.0

package/CHANGELOG.md

@@ -1,485 +1,474 @@
-# Changelog
-
-All notable changes to this project are documented here. Format loosely follows
-[Keep a Changelog](https://keepachangelog.com/); dates are when each version was published.
-
-## [Unreleased]
-
-### Added
-
-- **AI-powered analysis of a genuinely-failed test.** Healing has always deliberately left `expect()` untouched — silently "fixing" an assertion could mask a real defect. This adds a separate capability instead: once a test's retries are exhausted and it's still failing, classify *why* — `likely-defect`, `likely-wrong-locator`, `likely-timing-or-environment`, or `inconclusive` — with a short explanation naming what was actually found, so it's clear whether that's worth filing a bug for, fixing the test's selector, or investigating test stability. Covers any final failure, not just `expect()`: an action (click/fill/etc.) that healing already tried and reported on is analyzed too, folding healing's own diagnosis (provider, failure stage, its own reason for declining or for a replay that still failed) in as extra context for the classifier — e.g. healing declining because nothing plausible existed anywhere on the page is itself a strong signal toward `likely-defect` that the raw error message alone doesn't carry — rather than skipping the action failure or re-deriving everything from scratch. One unified verdict per genuinely-failed test, whatever kind of failure it was, not two separate, potentially conflicting explanations of the same thing. `likely-wrong-locator` is checked first, deliberately, ahead of `likely-defect`: it's the one verdict the AI is uniquely positioned to catch that skimming a plain error message would miss — the full ARIA snapshot is checked for something that plausibly matches under different text/structure before concluding the app itself is broken. On by default (`FAILURE_ANALYSIS_ENABLED`, same polarity as `HEALER_ENABLED` — unset or anything but `false`/`0` leaves it on; independent of `HEALER_ENABLED` itself, so turning healing off doesn't also silence this) — no reporter to register, no config file to edit: it's a `test.extend()` auto-fixture, the same mechanism `bindContext`/`bindPageActions`/`bindBrowser` already use, so it runs automatically the moment `test` is imported from this package. Chose default-on over mirroring `HEALER_ACTION_RECOVERY_ENABLED`'s opt-in-off polarity deliberately: this is a standalone capability, not a second-order escalation on top of an already-running mechanism the way action-recovery is — structurally closer to `HEALER_ENABLED` itself. The real tradeoff: unlike healing, which only spends tokens on a genuine action failure and is opportunistic about it (most actions succeed), this spends on *every* genuinely-failed test regardless of outcome — a red run with several broken tests means several AI calls, every run, until each is fixed. Each call's usage is its own `failure-analysis-tokens-used` annotation, deliberately a different type from healing's own `llm-tokens-used`, so the two costs can be told apart and weighed against each other rather than requiring free-text parsing to separate. (An earlier draft of this shipped as a standalone Playwright Reporter instead — reverted before release: it would have meant a *second* reporter line for anyone already running `tamash-playwright-dashboard`, on top of a real bug found only by actually running it — a fire-and-forget async call inside `onTestEnd` was silently abandoned when the process exited before the AI call resolved, since that hook's return type is strictly `void`, never awaited.) Reuses whichever `HEALER_PROVIDER` is already configured; `tamash` always declines (no reasoning capability). Exactly one AI call per genuinely-failed test when retries are configured at the project level (`playwright.config.ts`'s own `retries:`, or `--retries`) — the common case; a per-file `test.describe.configure({ retries })` override isn't visible to a fixture, so that specific case falls back to one call per attempt instead of one overall, confirmed safe (no crash, no wrong verdict) but not exactly-once. Reported the same way healing's own reports already are (`attachReportToRunningTest`, `healer/index.ts`): a `failure-analysis` annotation summarizing the verdict, the token-usage annotation described above, and a JSON attachment with the full attempt history — all visible in Playwright's own HTML report, not just the console. Deliberately no separate results log file: unlike `heals.jsonl` (a real cache, and read by `apply-heals`), nothing consumes one for this feature, and `tamash-playwright-dashboard` already reads healing's own reports straight off the test result's attachments rather than `heals.jsonl` — confirmed directly against its source (`reporter-helpers.ts`'s `extractHealReports`) — so a future dashboard integration needs no separate file either. Reads the exact same ARIA snapshot Playwright itself already captures at failure time for its own "Copy prompt for AI" feature when available, falling back to a live snapshot (the page is still open from a fixture, unlike from a Reporter) otherwise. Same non-negotiable property as healing itself: `expect()` is never touched, so this can only ever add information next to a failure that already happened, never change pass/fail.
-
-  Four real correctness bugs found and fixed via deliberate corner-case testing after the initial implementation, not caught by the happy-path tests alone: (1) the per-attempt working log was originally keyed by `testFile:testLine`, mirroring `heal-log.ts`'s own keying for a locator's call site — but that does NOT uniquely identify a *test*, since a loop generating parameterized tests (`for (const x of [...]) test(...)`) produces several tests sharing the exact same source line; four such tests failing concurrently corrupted each other's attempt history (one ended up with 5 attempts pulled from 3 different tests) before switching the key to `testInfo.testId` (confirmed stable across retries, genuinely unique even when the line collides). (2) A flaky test — fails once, recovers on retry — used to leave that failed attempt's row behind forever, since cleanup only happened after a genuine final-attempt analysis, which a recovered test never reaches; fixed by clearing a test's own rows on the passed branch too. (3) `testInfo.status !== 'passed'` fires for *any* reason a test fails, not just a genuine `expect()` assertion — a plain action (click/fill) that healing already tried and reported on (`self-heal-failed` already pushed onto `testInfo.annotations` synchronously, mid-test-body, by healing's own catch block) reached this same fixture and got explained a second, redundant time by an AI call reasoning about the same failure with strictly less context. An intermediate fix skipped analysis whenever `self-heal-failed` was already present, scoping the whole feature to `expect()` only — reconsidered before release: that meant an action failure never got the "is this worth filing a bug for" verdict either, just healing's own (different) diagnosis of why the *locator* couldn't be fixed. Landed instead as described above — analyze every final failure, folding healing's own diagnosis in as context — which needed the same stale-row cleanup discipline as bug (2), just reached via a different path: a mixed sequence (attempt 0 a genuine `expect()` failure, attempt 1 an action failure) must still end up with both attempts in the one final analysis, and the working log fully cleared afterward either way. (4) `readFailureAttempts` rebuilt each entry via an explicit field list (`{ retry, errorMessage, ariaSnapshot }`) that predated the `healingAttempt` field added for bug (3)'s fix — `appendFailureAttempt` wrote it to disk correctly the whole time, but every *read* silently dropped it again, so an action failure's healing context never actually reached the AI despite being captured; fixed by adding `healingAttempt` to that same explicit list, now covered by a unit test asserting the round trip specifically (not just that *a* value round-trips, since that would have passed before this fix too, given the other fields did).
-
-### Fixed
-
-- **A context/page built off `browser` in `test.beforeAll` (shared across tests) was never healing-aware.** Only the `context`/`page` fixtures were wrapped with the healing proxy — a consumer using `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` to log in once and reuse the session across every test in a file bypassed both, so nothing built that way ever healed. Found via a real support report. Fixed: the `browser` fixture is now wrapped too (`bindBrowser()`, `src/bindings/locator.binding.ts`) — `browser.newContext()`, `browser.newPage()`, and `browser.contexts()` all now hand back healing-aware objects, exactly like `context.newPage()` already did. Doesn't cover a browser obtained entirely outside the fixture system (e.g. `chromium.launch()` in `globalSetup`) — see "What else it heals" in README.md/usage.md for the manual `bindContext()`/`bindPageActions()` escape hatch for that case.
-
-### Docs
-
-- **README.md rewritten for readability — 666 lines down to ~220, no content lost.** The published npm listing had grown into dense, run-on paragraphs padded with self-qualifying phrases ("confirmed live," "confirmed by real testing, not just docs") — an audit-trail tone that belongs in this CHANGELOG and RELEASE-TESTING.md, not in a first-time visitor's landing page. Rewritten with short sentences and a plain, confident tone; the top-level "get started" flow (install → connect a provider → set `actionTimeout` → use it) now reads in under a minute instead of being buried under ~230 lines of provider-auth edge cases and a 110-line raw GitHub Actions YAML block. Nothing was deleted: the subscription-provider deep-dives (Claude/Copilot/Cursor/Kiro/Codex, including the Copilot org-vs-personal-token gotcha) moved into usage.md's "2. Connect an AI model" section as new subsections (it hadn't documented them at all before — README was the only copy), and README now links out to usage.md's existing sections for CI YAML, caching, and everything else usage.md already covered in full. Also fixed a real gap found while doing this: the `.env`/`usage.md` "pick one" provider comment was missing `cursor-subscription`/`kiro-subscription`/`codex-subscription` even though all three are real, documented providers.
-
-- **README.md/usage.md/feature.md now lead with the actual rule, not just examples of it.** The `browser`-in-`beforeAll` fix above was documented as a bullet point alongside popups/iframes, which left the real boundary implicit: *any* browser/context/page from Playwright's own fixtures heals automatically, however many hops away and however it's reused, while anything built outside the fixture system (`chromium.launch()` directly, or `globalSetup`) still needs manual `bindContext()`/`bindPageActions()`. Now stated as the first thing in "What else it heals," not inferred from bullets.
-
-## [0.12.0] - 2026-09-13
-
-### Added
-
-- **Playwright 1.63 support.** Dev/CI now tracks `@playwright/test` 1.63; `peerDependencies`
-  stays `>=1.40.0`. Verified: existing iframe healing (`page.frameLocator('#id')`) still heals,
-  and the full unit + representative e2e suite passes against 1.63.
-
-- **Healing through Playwright 1.63's no-argument `page.frameLocator()`.** 1.63 made
-  `frameLocator()`'s selector optional — with no argument it matches inside *any* frame on the
-  page. As a healing scope that's ambiguous the moment the page has more than one frame (the
-  healer's `locator('body')` snapshot then throws *"frameLocator() matched elements in multiple
-  frames"*, and healing silently no-op'd with `stage=no_snapshot`). Now, when the page has
-  exactly one frame, the healer re-expresses the no-arg `frameLocator()` as an explicit
-  single-frame `FrameLocator` and heals normally — including deriving a **durable, persistable**
-  cross-frame selector (`apply-heals` can write it back to source), identical to what
-  `page.frameLocator('#id')` produces. With zero or several frames it can't know which was meant,
-  so it steps aside cleanly — the original error is re-thrown, never a wrong-frame guess. For
-  healable work on a multi-frame page, pass an explicit selector: `page.frameLocator('#id')`.
-
-  *(`0.12.0-beta.1` collapsed the scope to a raw `page.frames()` `Frame` instead of a
-  `FrameLocator`. `Locator.normalize()` on a `Frame`-rooted locator returns a correct selector
-  string but an object that resolves to nothing, so the heal worked once at runtime but couldn't
-  be persisted — it fell back to a transient one-shot element reference with a `needsReview`
-  note. Fixed here.)*
-
-- **Documented [`tamash-playwright-dashboard`](https://www.npmjs.com/package/tamash-playwright-dashboard).**
-  A separate, zero-config reporter package: pass-rate trends, per-test history across runs, and —
-  specific to this package — a Self-Healing Analytics page (tests/elements healed, token usage
-  per run and cumulatively, every heal event across recorded history), read directly from the
-  `self-healing-<action>` JSON attachment this package already writes. No code change on this
-  side — README and usage.md gained a "Trends across runs" section pointing to it.
-
-### Fixed
-
-- **`describeFactoryCall` rendered `iframe "undefined"` for a no-arg `frameLocator()`.** The
-  factory-call label helper assumed a selector argument was always present; with 1.63's optional
-  selector it produced the literal string `iframe "undefined"`. Now renders `any iframe`. (Latent
-  — the label isn't currently surfaced to users or the model, but it would be the moment any
-  "healing inside iframe X" context is added to a report or prompt.)
-
-## [0.11.0] - 2026-08-31
-
-### Fixed
-
-- **`skills/tamash-playwright/references/heal.md` never told the agent the Playwright HTML report exists at the point it matters.** It only pointed at `npx playwright show-report` at the very end (the REPORT step), after the loop was already finished — not right after RUN, where the report's per-attempt annotation and JSON attachment (provider, vision/action-recovery involvement, suggested selector, token cost, failure stage) would actually help decide what to do next. Found by directly auditing the skill against every documented user workflow step, not by running it. Fixed: RUN now explicitly says what the report contains and when it's worth opening.
-
-- **`doctor`'s connectivity check gave false confidence for `claude-subscription`/`copilot-subscription`.**
-  It tested against a fixed, generous 15s timeout, completely decoupled from the project's real
-  configured `actionTimeout` — so a project using the README's own example value (`actionTimeout:
-  8000`) could get `[OK] Connected successfully` from `doctor`, then have its very first real heal
-  in a fresh test run fail with a misleading "not authenticated?" warning, because these two
-  providers spawn the vendor's own CLI as a subprocess and the first call in a process pays a
-  one-time cold-start cost (spawning + authenticating) on top of the actual model call — a cost
-  `doctor`'s own generous timeout never had to absorb. Found via a real, unbriefed agent walkthrough
-  of a from-scratch setup (see the skill entry below): it hit this exact failure, correctly
-  diagnosed the root cause from a source-code comment nothing user-facing ever surfaced, and worked
-  around it by raising `actionTimeout` to 20000ms. Fixed at the actual source: `doctor` now tests
-  connectivity within the project's real `actionTimeout` when one's configured (falling back to the
-  old generous default only when none is set yet), and a `[FAIL]` for either of these two providers
-  now explicitly suggests it may be the cold-start cost rather than a real auth problem. Verified
-  against the real `copilot-subscription` provider — confirmed the check now genuinely uses the
-  configured timeout (not just that it compiles); could not force a deterministic before/after
-  repro of the timeout itself in this environment, since the underlying race is timing/environment-
-  dependent (a warm local CLI session can mask it, exactly as the original cold-start comment
-  already described).
-
-- **The published package was silently carrying stale, orphaned compiled output.** `npm run build`
-  (plain `tsc`, no `--build`/incremental mode) never deletes `dist/` output for a source file that
-  was later removed — found in the `0.11.0-beta.1` publish itself: `dist/healer/providers/
-  claude-cli.js`/`copilot-cli.js` shipped in the tarball with no corresponding source file
-  anywhere in the repo (from an abandoned, never-committed, never-wired-up piece of past work) —
-  dead code nothing actually imports, but real, needless bloat in every install. Fixed by cleaning
-  `dist/` automatically before every build (`prebuild` script), verified by confirming a full
-  rebuild no longer produces those two files.
-
-- **A popup/new tab opened via `context.waitForEvent('page')`, `page.on('popup', ...)`, or
-  `page.waitForEvent('popup')` was never healing-aware.** `bindContext`/`bindPageActions` already
-  made `context.newPage()`/`context.pages()`/`context.on('page', ...)` heal correctly, but these
-  three — including `context.waitForEvent('page')`, the pattern most commonly taught for popup
-  handling — fell through to a raw, unwrapped Playwright page. A broken locator inside the
-  resulting page just threw a plain timeout, with no `[self-healer]` line at all: healing was never
-  attempted, not just unsuccessful. Found while building the first-ever test for popup healing
-  (previously implemented with zero coverage); fixed by extending both bindings to wrap whatever
-  page these three hand back, the same way `newPage()` already did.
-
-- **`tamash` (the rule-based provider) declined on a real, common page pattern it should have
-  resolved.** A floating label rendered as its own text node right next to a field whose accessible
-  name is *also* that same text (confirmed on a real login page: a "Username" label next to a field
-  that's itself named "Username") was miscounted as two competing candidates and declined, even
-  though there's genuinely only one field. `findRuleBasedMatch` now only treats a match as a real
-  competing candidate when it's independently resolvable on its own (has a ref and a plausible
-  role) — a bare text node repeating the same words is decorative, not a second option. Genuine
-  ambiguity (two actually-independent candidates) still declines exactly as before.
-
-- **The HTML report's self-healing attachment was a wall of escape sequences on a failed
-  heal.** Playwright's own error messages embed ANSI colour codes in their "Call log" section;
-  the healer stored those raw in `report.reason` / `report.warning` / `attempts[].error`, and
-  `JSON.stringify` (which builds the `self-healing-<action>` attachment) escapes every ESC byte in the JSON, so a *not-healed* report rendered as unreadable escape soup. A
-  *successful* heal has short or absent error strings, which is why it only showed up on failures.
-  Fixed by stripping ANSI CSI sequences in `normalizeError` — the single point every captured
-  error passes through — so the attachment, the console line, and `heals.jsonl` are all plain
-  text. Verified against a real not-healed run.
-
-- **The three CLI-based subscription providers (`cursor-subscription`, `kiro-subscription`,
-  `codex-subscription`) were verified against their real vendor CLIs for the first time — and none
-  of the three actually worked as shipped.** Four separate bugs, all found by running them, all now
-  fixed:
-  1. **`cursor-subscription` never returned a heal.** `agent -p` refuses to run in any directory
-     without workspace trust — it prints "Workspace Trust Required" and exits without answering.
-     Now passes `--trust --mode ask`; `--mode ask` is Cursor's own read-only Q&A mode ("read-only"
-     per its `--help`), which *removes* the old "has access to all tools, could edit a file"
-     caveat this provider carried — a heal call in `ask` mode cannot write or run anything.
-  2. **`codex-subscription` refused to run outside a Git repository** ("Not inside a trusted
-     directory and --skip-git-repo-check was not specified"). Now passes `--skip-git-repo-check`;
-     this only relaxes the where-may-I-run guard, not the sandbox — `codex exec` still runs
-     `approval: never` + read-only, the property this provider depends on.
-  3. **`codex exec` hung on stdin.** It drains stdin ("Reading additional input from stdin…") and
-     blocks until EOF; `runCliPrompt` left the child's stdin as an open pipe, so every call ran to
-     the timeout and was killed — confirmed: a prompt the CLI answers in ~8s "timed out" at 15s.
-     `runCliPrompt` now gives every child an already-closed stdin (`stdio: ['ignore', …]`),
-     harmless for `agent`/`kiro-cli`, the fix for `codex`.
-  4. **The JSON parsers failed on conversational output.** `parseSuggestion` /
-     `parseVisionSuggestion` / `parseActionTacticSuggestion` extracted JSON from prose with a
-     greedy first-`{`-to-last-`}` slice, which breaks the moment the response contains more than
-     one JSON object — exactly what cursor's `agent` produces (it echoes the system prompt's
-     example objects back before its real answer). Replaced with a balanced-brace-span scan that
-     takes the last valid object (a model states its answer last), old greedy slice kept as a last
-     resort. Improves robustness for every provider, not just the CLI ones.
-
-  Verified live, all authenticated: `doctor` reports `[OK] Connected` for all three; a real
-  `npx playwright test` heal (broken locator, cache cleared) went green with
-  `HEALED [provider=codex-subscription]`, and `kiro-subscription` healed the same spec.
-
-- **`cursor-subscription` reliability note.** Verifying it (see above) showed Cursor's `agent` CLI
-  is an interactive assistant rather than a one-shot completion endpoint — given the heal prompt it
-  often answers conversationally instead of with the required JSON, so the heal is declined more
-  often than with `kiro`/`codex`. It's now invoked in the safest/best-effort form
-  (`agent -p --trust --mode ask --output-format json`, read-only) and is marked **experimental**;
-  the docs point to `kiro`/`codex` as the steadier local-subscription options. Report issues.
-  Also: the full e2e healing suite (12 tests) was run end to end against `copilot-subscription` and
-  `ollama` — **12/12 each** — to confirm the parser rewrite and provider changes don't regress it.
-
-### Added
-
-- **`npx tamash-playwright init-skill` — one command to install the orchestration skill, plus a
-  `doctor` check that flags when it's missing or stale.** The skill this package ships
-  (`skills/tamash-playwright/`) was previously a copy-this-shell-one-liner-per-agent step buried in
-  `SKILL.md`, with nothing verifying it had been done — so a project could `npm install` the
-  package, never copy the skill, and its assistant would silently never load the workflow.
-  `init-skill` copies the skill (`SKILL.md` + `references/`) into **both** standard locations —
-  `.claude/skills/tamash-playwright/` (Claude Code) and `.agents/skills/tamash-playwright/` (the
-  emerging cross-tool standard, read by Cursor, GitHub Copilot, Windsurf, Kiro, Zed, dotnet Aspire,
-  … — the same convention Playwright's own `playwright-cli install --skills` uses). Same content in
-  both; no per-agent format conversion. `--target claude` / `--target agents` installs one; `--user`
-  installs under your home directory; `--force` overwrites a hand-edited copy; `--dry-run` previews.
-  Each install carries a `tamash-playwright-skill-version:` marker; `doctor`'s **Skill** section
-  reads it and reports `[OK]` current / `[WARN]` behind-the-package-version / `[INFO]` not-installed
-  or unmanaged, with the same one-line fix. Covered by unit tests (`skill.test.js`, real installs
-  into a temp dir) and verified live end to end.
-
-  *(0.11.0-beta.7 shipped an earlier `init-skill` that instead auto-detected the agent and wrote a
-  Cursor-specific `.mdc` file / appended blocks to `.github/copilot-instructions.md` and
-  `AGENTS.md`. That approach is gone — `init-skill` and `doctor` now point out any such leftovers
-  from a beta.7 install so you can delete them by hand.)*
-
-- **`doctor`'s AI Provider check now tells you *what kind* of failure it hit and what to do about
-  it, instead of one generic "no valid response".** Every provider gained an optional, diagnostics-
-  only `diagnose()` method (never on the healing hot path) that runs one trivial round trip and
-  reports a structured category — `not-installed`, `not-authenticated`, `timeout`, `bad-model`,
-  `network`, `bad-response` — each of which `doctor` maps to a specific next step: the missing
-  `npm install`/CLI installer for a missing SDK; "run `claude login` / check your API key / confirm
-  your subscription is active and within quota" for a rejected request; "raise `actionTimeout`" (plus
-  the existing subprocess cold-start note) for a timeout; "check `<MODEL>` in your .env" for a
-  rejected model id; a network/proxy/base-URL hint for a connection failure. The raw error line is
-  still printed verbatim beneath the guidance. Previously `doctor` could only distinguish "worked"
-  from "didn't" — a missing SDK, an expired login, a slow network and a wrong model name all
-  produced the same line. Providers that don't implement `diagnose()` fall back to the old
-  `suggestSelector()` probe (worked/didn't, plus a timing-based timeout guess). Verified live:
-  `openai` bad key -> `not-authenticated` (401 body shown), `openai` bad base URL -> `network`,
-  `copilot-subscription` bad model id -> `bad-model`, 1ms `actionTimeout` -> `timeout` with the
-  raise-the-timeout guidance, and all three not-installed shapes by moving the dependency out of
-  resolution and restoring it: `@github/copilot-sdk` (CJS `MODULE_NOT_FOUND`),
-  `@anthropic-ai/claude-agent-sdk` (ESM `ERR_MODULE_NOT_FOUND`), and a missing `kiro-cli` binary
-  (`ENOENT`) -- each surfacing `not-installed` with its exact install command.
-
-- **Three new local-development-only subscription providers: `cursor-subscription`,
-  `kiro-subscription`, `codex-subscription`.** Extends the same "use what you're already paying
-  for" idea `claude-subscription`/`copilot-subscription` already give, to three more real
-  subscriptions — but each is explicitly scoped to local development, never documented or
-  recommended for CI, for two genuinely different reasons found by checking real vendor docs before
-  writing any code. Cursor's and Kiro's own headless-mode docs confirm neither has a way to fully
-  disable tool/file/command access the way `claude-subscription`'s `tools: []`/`copilot-subscription`'s
-  `availableTools: []` do — Cursor's `agent -p` "has access to all tools" by its own docs, and Kiro's
-  headless mode requires `--trust-all-tools`/`--trust-tools` specifically because there's no one to
-  approve a tool call unattended; `kiro-subscription` deliberately never grants that trust, so a
-  tool-requiring response just times out and declines rather than being granted broad access.
-  `codex-subscription` is local-only for a different, simpler reason: `codex exec` (used here, not
-  the interactive REPL) defaults to a read-only sandbox with no approval prompts — already as safe
-  as the two existing subscription providers — but no long-lived, subscription-only token for
-  unattended CI use is confirmed to exist for it yet. None of the three vendors ship a Node SDK, so
-  all three are `child_process` wrappers around the vendor's own CLI binary (`agent`, `kiro-cli`,
-  `codex`) via a new shared `runCliPrompt` helper, rather than the SDK-based design the existing two
-  use — meaning every call pays a fresh process-spawn cost, not just the first the way
-  `copilot-subscription`'s warm shared client does; `doctor` now has a distinct hint explaining this
-  when one of these three fails within a tight `actionTimeout`. Investigated and explicitly ruled
-  out this round: Antigravity — its dedicated `google-antigravity` SDK is Python-only (this is a
-  Node/TypeScript package), has no documented tool-restricted mode at all, and its authentication
-  story isn't published, so it isn't even confirmed to ride on an existing subscription. Verified:
-  real graceful-decline behavior confirmed against genuinely uninstalled CLIs (no fabricated
-  simulation), and the full `doctor` integration (including the new every-call-cost hint) confirmed
-  against a real sample repo. **Not yet verified**: the actual happy path against a real installed
-  and authenticated CLI for any of the three — none were available in the development environment,
-  and all three require a real paid subscription account.
-
-- **A skill for running this package's local workflow inside an AI coding assistant.** Ships at
-  `skills/tamash-playwright/` — a `SKILL.md` entry point that branches on `npx tamash-playwright
-  doctor`'s actual output (never assumed), plus two reference docs: `onboarding.md` (bringing a
-  project up to standard — provider setup, `actionTimeout`, `.describe()` labels, Page Object
-  extraction) and `heal.md` (a gated review/apply/verify/land loop over `apply-heals` and
-  `verify-heals.cjs` — most runs proceed start to finish unattended, pausing only for a genuinely
-  ambiguous fix or anything after a failed verification, and never landing/committing/opening a PR
-  without asking first, no matter how clean the run was). Pure orchestration over commands that
-  already exist — no new healing capability. Ships with adapters for Claude Code, Kiro (identical
-  `SKILL.md` format, confirmed against Kiro's own docs), Cursor (`.mdc` rule), GitHub Copilot
-  (`copilot-instructions.md` section), and an `AGENTS.md` covering the broader cross-tool standard
-  (Antigravity, Gemini CLI, Windsurf, Zed, Aider, and others) — none of which are auto-discovered
-  from `node_modules` by any of these tools, confirmed rather than assumed, so every adapter's
-  install step is one explicit copy command, documented in `SKILL.md` itself.
-- **A new `tamash` heal provider — rule-based healing, no AI at all.** `HEALER_PROVIDER=tamash`
-  needs no API key, no subscription, and makes no network call: it resolves a broken locator by
-  text-matching the same description an AI provider would receive (`.describe()`, or a decoded
-  variable name — see below) against the already-captured accessibility snapshot, then reuses the
-  exact same structural widening (`near`/`adjacent`) the AI-backed path already uses once it finds
-  the right anchor — same output shape, same downstream code, zero duplicated logic. It shares the
-  same non-negotiable discipline as every text-matching step in this package: zero or more than one
-  match, at any point, means it declines rather than guesses — verified with a dedicated permanent
-  e2e suite covering direct matches, widened matches, and every decline path (including the known,
-  accepted limitation that a misleading type hint can't be second-guessed against). Genuinely a
-  different tool than the AI providers, not a free replacement for one: no vision fallback (nothing
-  to reason over a screenshot with) and no action-recovery tactics (those require understanding
-  *why* an action failed, which is inference this provider deliberately doesn't attempt) — a fast,
-  free, fully deterministic first line of defense, best suited to well-`.describe()`d,
-  Page-Object-style suites.
-- **A new `ollama-local` heal provider for self-hosted Ollama servers.** `HEALER_PROVIDER=ollama-local`
-  targets your own `ollama serve` instance or an internal company deployment, instead of Ollama
-  Cloud — a deliberately separate provider from `ollama`, not a flag on it, since the two have
-  genuinely different auth defaults: Ollama Cloud always requires `OLLAMA_API_KEY`, while
-  `OLLAMA_LOCAL_API_KEY` is optional, since a bare `ollama serve` has no authentication at all. Set
-  it only if your internal deployment sits behind a reverse proxy or API gateway that requires a
-  bearer token — verified against a real HTTP server both ways, confirming the `Authorization`
-  header is omitted entirely when no key is set, and sent correctly when one is. Prompted by a real
-  support request from a team wanting to use their own internally-hosted `gpt-oss:120b`.
-- **Undescribed, POM-style locator variables now get a real description automatically.** When
-  `.describe()` was never called, the healer already fell back to the locator's own variable/
-  property name (`txtEmployeeId`) as its best guess at intent — now that raw identifier is decoded
-  into the same kind of human-readable phrase `.describe()` would give: `txtEmployeeId` becomes
-  "Employee Id (textbox)", `submitButton` becomes "Submit (button)", recognizing both prefix-style
-  (`btnSubmit`) and suffix-style (`submitBtn`) naming, camelCase/snake_case/kebab-case, and correct
-  acronym boundaries (`employeeIDNumber` → "Employee ID Number"). Falls back to the raw identifier,
-  exactly as before, whenever nothing meaningful survives decoding (a placeholder name like `el1`,
-  or a bare affix with nothing else) — never a guess dressed up as a real description. Verified
-  live against a real, unpublished build in both sample repos (a real `copilot-subscription` call,
-  and — after finding and fixing a genuinely stale API key along the way — a real `ollama` call),
-  confirming the decoded description actually reaches the configured AI provider unchanged.
-
-## [0.10.0] - 2026-08-27
-
-### Fixed
-
-- **`waitFor()` is never sent to the AI.** It's a state check, not an action — a timeout on it can
-  mean a genuinely broken selector, or it can mean the element correctly never reached the expected
-  state (verifying something does NOT appear, or a real app issue), and there's no way to tell those
-  apart from the error alone. `expect(locator).toBeVisible()` was already permanently excluded from
-  healing for exactly this reason, but never reached this code at all (a separate path from the
-  Proxy-intercepted actions) — `waitFor` just never got the same treatment. Real, reported case: a
-  user's `waitFor` on a locator verifying an absence (where timing out was the *correct* outcome)
-  still burned 8175 tokens across a failed text attempt and a failed vision attempt before giving
-  up, for a heal that could never have succeeded. Now fails fast with a clear `state-wait-not-healed`
-  stage and zero AI calls; a real action (fill/click/...) on the same kind of broken locator is
-  unaffected.
-- **`claude-subscription` was burning a real, unnecessary amount of extra tokens.** The SDK's
-  `effort` option silently defaults to `'high'` ("deep reasoning") when left unset, and this
-  provider never set it — a small prompt-complexity increase (the `nearbyRef`/`nearbyText` addition
-  below) pushed adaptive thinking to reason unpredictably harder for a task that only ever needs to
-  return one line of JSON. Confirmed live via real CI runs: output tokens for the same heal went
-  from a 188-445 baseline up to 422-881, inconsistently, run to run. `thinking: { type: 'disabled' }`
-  + `effort: 'low'` removes the variability entirely — verified repeatedly at a steady 28-30 output
-  tokens, below even the pre-regression baseline, with no change to correctness.
-- **The primary ariaSnapshot capture no longer requests `boxes:true`.** Every node was paying for a
-  `[box=x,y,w,h]` annotation that nothing on the text/`ref` path (including the `nearbyRef`/
-  `adjacent`-strategy widening logic below) ever reads — it's purely topological. The one real
-  consumer (vision's own nearest-candidate lookup) already captures its own separate, fresh
-  snapshot, so this is genuinely free: verified live, input tokens dropped ~23% on a large real
-  page (3794 → 2937) with no loss of accuracy, and no change on small pages (box overhead scales
-  with node count).
-
-### Added
-
-- **Search-scoped snapshots**: before falling back to the full page, the healer now searches the
-  already-captured snapshot for the description's identifying phrase and, only when it matches
-  exactly one node, sends the AI a scoped excerpt (that node's own subtree plus every sibling
-  branch's subtree at each ancestor level up to the root) instead of the whole page — zero extra
-  browser round-trips, since it's pure processing on data already in memory. Falls back to the full
-  snapshot automatically whenever the search is empty or ambiguous, never a guess. Verified live
-  across every real failure mode found this session: 41% token reduction on a deeply-nested field,
-  66% when the target was inside what looked like an unrelated navigation menu (proving it finds
-  wherever the relevant text actually is, not "excludes the nav"), ~29% on a pair of identical
-  sibling fields that still had to be correctly disambiguated, and a clean, correct fallback when
-  the description doesn't match the page's real text at all.
-- **A new `adjacent` selector strategy**, fixing a real ambiguity in the existing `near` strategy:
-  when two fields with no identity of their own share a row/section (two dropdowns side by side,
-  say), `near`'s "climb to a shared ancestor, then search it for any element of this role"
-  approach matches both and gives up rather than risk the wrong one. The AI's `ref` response can
-  now optionally report `nearbyRef`/`nearbyText`/`nearbyRole` for a nameless target it identified;
-  `deriveDurableLocator` uses that hint to find the true common ancestor between the target and
-  its label — via each ref's own full ancestor chain, not by assuming either sits at a matching
-  depth — and, when they're proven to be immediate sibling branches, builds a precise CSS
-  `:text() + *` sibling match (or an xpath climb-then-step, when the label text turns out to be
-  nested below its own branch root). Verified live against a real configured provider, resolving
-  the correct field and never its same-row neighbor in both directions.
-- **Full attempt-history logging**: `SelfHealingReport` now carries an `attempts[]` array — one
-  entry per cache/ref/text/vision/action-recovery attempt actually made, each with its own
-  `succeeded`/`stage`/`error`. Previously only the *last* attempt's stage survived; an earlier
-  attempt's real failure (and the specific error it threw) was silently discarded the moment a
-  later attempt also failed — the exact shape of a real user-reported bug, where a genuine
-  candidate selector was shown next to an unrelated `vision_provider_error` with no way to tell
-  why the candidate itself hadn't worked. The attempt history now also prints directly to
-  console/CI output (not just the JSON attachment) whenever more than one attempt was made, on
-  both pass and fail — since that plain-text output is what most bug reports actually paste, not
-  an attachment nobody opens.
-- **`ariaSnapshot` is attached to the test report on failure** — the exact accessibility tree the
-  AI reasoned over, so a confusing report can be diagnosed against real evidence instead of a
-  separately-captured DevTools screenshot.
-
-## [0.9.0] - 2026-08-26
-
-### Fixed
-
-- **Heal-log visibility**: a heal with no reusable selector (a one-shot `ref` resolution, or a
-  vision-tagged point) was silently dropped from `heals.jsonl` entirely, even though it genuinely
-  fixed that run. Now logged for audit — with a clear `reviewNote` — whenever it has a suggestion
-  *or* a review note, without letting an audit-only entry shadow an older, real cached fix for the
-  same location.
-- **Vision support for `claude-subscription`/`copilot-subscription`**: both providers had
-  `supportsVision` hardcoded to `false` regardless of model. Both SDKs genuinely support image
-  input (Claude Agent SDK via an image content block; Copilot SDK via a `blob` attachment) —
-  implemented for real and verified live with actual screenshots, not just doctor's yes/no label.
-- **Argument forwarding in healed replays**: `replayAction()` only ever forwarded the first call
-  argument. A trailing options object (`click({ modifiers: [...] })`, `fill(value, { timeout })`,
-  `dispatchEvent`'s 3rd argument) was silently dropped on a healed replay — changing the action's
-  real behavior while still reporting a clean `HEALED`.
-- **`ref`-strategy replays now act through the derived durable locator, not the raw ref**:
-  `aria-ref=` locators never resolve for `dispatchEvent` at all (a Playwright-level limitation,
-  confirmed directly via `DEBUG=pw:api`), even though the identical element resolves instantly via
-  a `normalize()`-derived locator for that same action. Fixed by deriving the durable locator
-  *before* replaying and acting through it, falling back to the raw ref only when nothing durable
-  could be found. A related accuracy bug is fixed alongside it: the report/heal-log could
-  previously claim a derived selector "worked" even when its own replay had actually failed and a
-  fallback silently took over — now only the locator that genuinely performed the action is
-  reported or cached.
-- **`copilot-subscription` could hang a non-Playwright test runner indefinitely** — its shared
-  client keeps a connection open across calls for performance, which Playwright's own test runner
-  tolerates by force-exiting regardless, but a runner like Cucumber does not, so the process never
-  returned even after every test had already passed. Found live running a real Cucumber suite in
-  CI. `closeCopilotSubscriptionClient()` is now exported from the package's own entry point so any
-  non-Playwright consumer can call it from their own teardown hook (e.g. Cucumber's `AfterAll`).
-
-### Added
-
-- **`locator.getDurable(action?)`** — resolves any locator (most usefully one built from
-  `aria-ref=...`) to a durable, reusable equivalent (`getByRole`/`getByLabel`/a css selector/…),
-  using the same derivation logic self-healing already uses internally. Throws if nothing durable
-  could be derived, rather than silently handing back something untrusted.
-- **`apply-heals` now previews before writing**: every run — dry or real — shows a styled table of
-  exactly what it found (location, before, after, review status) instead of a plain scrolling log.
-  A real run also asks for confirmation before writing anything, but *only* at a genuine
-  interactive terminal — CI and any non-interactive/piped invocation proceed automatically exactly
-  as before, so no existing unattended CI workflow is affected. `--yes`/`-y` skips the prompt at a
-  real terminal too.
-- **`doctor`'s output is styled** with colors and tables (including a new end-of-run Summary
-  section) instead of a plain scrolling log.
-- **Exact locator code in console lines and reports**: a healed suggestion is now shown as the
-  real, copy-pasteable Playwright call (`getByRole("textbox", { name: "Username" })`) instead of
-  an abbreviated shorthand (`role:textbox:Username`) — the same code `apply-heals` would write to
-  source, so what you see is never a lossier stand-in for what was actually used.
-- A canonical Page Object Model usage example (`tests/pages/` +
-  `tests/example-orangehrm-add-employee.spec.ts`), verified live against a real OrangeHRM demo,
-  including a genuine self-heal via the `near`/widening strategy on a real unlabeled field.
-
-### Changed
-
-- README/usage.md's vision-fallback documentation now correctly lists `claude-subscription`/
-  `copilot-subscription` as vision-capable (with a suitable model), not just the API-key providers.
-
-## [0.8.0] - 2026-08-25
-
-### Added
-
-- `claude-subscription` and `copilot-subscription` heal providers — self-healing backed by a
-  personal Claude or GitHub Copilot subscription instead of a pay-per-token API key, working both
-  locally and unattended in CI (`CLAUDE_CODE_OAUTH_TOKEN` for Claude; the ambient `GITHUB_TOKEN` or
-  a personal-account PAT for Copilot on GitHub Actions).
-
-### Fixed
-
-- Missing CLI install step in setup docs for `claude-subscription`/`copilot-subscription` — the
-  standalone `claude`/`copilot` CLIs are genuinely required for the login step even though the SDKs
-  don't need them installed to function at runtime.
-
-### Documentation
-
-- The org-vs-personal-account Copilot licensing gotcha in CI (a repo owned by an organization
-  without its own Copilot enablement can't use a personal subscription via the ambient token).
-- Action Recovery (`HEALER_ACTION_RECOVERY_ENABLED`) hidden from docs and `doctor` output —
-  disabled by default already; this only reduced its visibility, no behavior change.
-
-## [0.7.0] - 2026-08-21
-
-### Added
-
-- `apply-heals` — turns a runtime heal into a permanent source-code fix, plus an opportunistic
-  cache (`heals.jsonl`) so a previously-confirmed selector is tried before a fresh AI call, and
-  history archival so a run's report/log isn't silently overwritten by the next one.
-- Position/relationship-based locator strategies (`near`, `scoped`, `containing`) for elements with
-  no accessible identity of their own.
-- Self-healing rebuilt around `ariaSnapshot({ mode: 'ai' })` + `aria-ref=` resolution and
-  `Locator.normalize()`, replacing pixel-distance guessing for both the text path and the vision
-  fallback's durability upgrade.
-- A real unit test suite (32 tests at the time, zero new dependencies).
-
-### Fixed
-
-- `doctor`'s `actionTimeout` check being fooled by a commented-out config value.
-- `apply-heals --logs-dir` silently losing raw heal-log archival.
-- `apply-heals` only replacing the first call when re-healing an already-`near`-fixed line.
-- `apply-heals` `ENOENT` on a fresh CI checkout with no `.tamash-playwright/` directory yet — the
-  sharded "apply-heals" CI job checks out fresh and has never run tests itself, so the directory
-  genuinely doesn't exist there the way it always does in every local recipe.
-- File path corruption (and a `require()` crash in the generated verification script) for ESM
-  (`"type": "module"`) consumer projects — `Error.stack` renders as a `file://` URL there, which
-  broke path resolution and a plain `.js` verification script alike.
-- The AI being misled by the broken selector still present in its own prompt context; a failed
-  label guess now auto-upgrades to a structural `near` match instead of giving up.
-
-### Verified
-
-- All four API-key providers (Ollama, OpenAI, Anthropic, Gemini) confirmed working with real API
-  calls, not just documented.
-
-## [0.6.0] - 2026-08-17
-
-### Added
-
-- iframe and popup healing, vision fallback (screenshot-based recovery when text alone isn't
-  enough), AI-driven action recovery (scroll/force/wait/dispatch), and source-location reporting.
-- `doctor`'s `actionTimeout` configuration check.
-
-### Initial release
-
-- Self-healing Playwright bindings: broken locators are recovered at runtime via an AI provider,
-  with `.describe()` for human-readable context.
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); dates are when each version was published.
+
+## [0.13.0] - 2026-09-17
+
+### Added
+
+- **AI-powered analysis of why a test failed.** Classifies a genuinely-failed test (every retry exhausted) as `likely-defect`, `likely-wrong-locator`, `likely-timing-or-environment`, or `inconclusive`, with a short explanation. Covers any final failure, not just `expect()` — an action failure healing already reported on is analyzed too, using healing's own diagnosis (provider, failure stage, reason) as context. On by default (`FAILURE_ANALYSIS_ENABLED`), independent of `HEALER_ENABLED`. No reporter to register — runs as a `test.extend()` auto-fixture, the same mechanism `bindContext`/`bindPageActions`/`bindBrowser` use. Reuses whichever `HEALER_PROVIDER` is configured; `tamash` always returns `inconclusive`. One AI call per genuinely-failed test when retries are set at the project level (`playwright.config.ts`'s `retries:`, or `--retries`); a per-file `test.describe.configure({ retries })` override is not visible to the fixture, so that case analyzes every failing attempt instead of one. Reported the same way healing's own reports are: a `failure-analysis` annotation, a `failure-analysis-tokens-used` annotation (separate from healing's `llm-tokens-used`), and a `failure-analysis` JSON attachment with the full attempt history. `expect()` itself is never touched.
+
+  Four bugs were fixed during development, each covered by a permanent regression test: (1) the working log was keyed by `testFile:testLine`, which is not unique for parameterized tests sharing a source line — fixed by keying on `testInfo.testId`. (2) A flaky test that passes on retry left a stale row in the working log — fixed by clearing it on the passing branch too. (3) An action failure that healing already reported on received no failure-analysis verdict — fixed by analyzing it too, passing healing's own diagnosis in as context. (4) `readFailureAttempts` dropped the `healingAttempt` field on every read despite writing it to disk correctly — fixed by adding the field to its return list.
+
+### Fixed
+
+- **A context/page built off `browser` in `test.beforeAll` was not healing-aware.** Only the `context`/`page` fixtures were wrapped with the healing proxy; `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` bypassed both. Fixed: `browser.newContext()`, `browser.newPage()`, and `browser.contexts()` now return healing-aware objects, matching `context.newPage()`. Does not cover a browser obtained outside the fixture system (e.g. `chromium.launch()` in `globalSetup`) — see "What else it heals" in README.md/usage.md for the manual `bindContext()`/`bindPageActions()` option.
+
+### Docs
+
+- **README.md rewritten — 666 lines to ~220, no content removed.** Deep-dive content (subscription-provider setup, the full CI YAML example) moved into usage.md's existing sections; README links out to them. Fixed a gap: the `.env`/usage.md "pick one" provider comment was missing `cursor-subscription`/`kiro-subscription`/`codex-subscription`.
+
+- **README.md/usage.md/feature.md state the fixture-healing rule directly.** "What else it heals" now leads with the rule: any browser/context/page from Playwright's own fixtures heals automatically, however many hops away; anything built outside the fixture system needs manual `bindContext()`/`bindPageActions()`.
+
+## [0.12.0] - 2026-09-13
+
+### Added
+
+- **Playwright 1.63 support.** Dev/CI now tracks `@playwright/test` 1.63; `peerDependencies`
+  stays `>=1.40.0`. Verified: existing iframe healing (`page.frameLocator('#id')`) still heals,
+  and the full unit + representative e2e suite passes against 1.63.
+
+- **Healing through Playwright 1.63's no-argument `page.frameLocator()`.** 1.63 made
+  `frameLocator()`'s selector optional — with no argument it matches inside *any* frame on the
+  page. As a healing scope that's ambiguous the moment the page has more than one frame (the
+  healer's `locator('body')` snapshot then throws *"frameLocator() matched elements in multiple
+  frames"*, and healing silently no-op'd with `stage=no_snapshot`). Now, when the page has
+  exactly one frame, the healer re-expresses the no-arg `frameLocator()` as an explicit
+  single-frame `FrameLocator` and heals normally — including deriving a **durable, persistable**
+  cross-frame selector (`apply-heals` can write it back to source), identical to what
+  `page.frameLocator('#id')` produces. With zero or several frames it can't know which was meant,
+  so it steps aside cleanly — the original error is re-thrown, never a wrong-frame guess. For
+  healable work on a multi-frame page, pass an explicit selector: `page.frameLocator('#id')`.
+
+  *(`0.12.0-beta.1` collapsed the scope to a raw `page.frames()` `Frame` instead of a
+  `FrameLocator`. `Locator.normalize()` on a `Frame`-rooted locator returns a correct selector
+  string but an object that resolves to nothing, so the heal worked once at runtime but couldn't
+  be persisted — it fell back to a transient one-shot element reference with a `needsReview`
+  note. Fixed here.)*
+
+- **Documented [`tamash-playwright-dashboard`](https://www.npmjs.com/package/tamash-playwright-dashboard).**
+  A separate, zero-config reporter package: pass-rate trends, per-test history across runs, and —
+  specific to this package — a Self-Healing Analytics page (tests/elements healed, token usage
+  per run and cumulatively, every heal event across recorded history), read directly from the
+  `self-healing-<action>` JSON attachment this package already writes. No code change on this
+  side — README and usage.md gained a "Trends across runs" section pointing to it.
+
+### Fixed
+
+- **`describeFactoryCall` rendered `iframe "undefined"` for a no-arg `frameLocator()`.** The
+  factory-call label helper assumed a selector argument was always present; with 1.63's optional
+  selector it produced the literal string `iframe "undefined"`. Now renders `any iframe`. (Latent
+  — the label isn't currently surfaced to users or the model, but it would be the moment any
+  "healing inside iframe X" context is added to a report or prompt.)
+
+## [0.11.0] - 2026-08-31
+
+### Fixed
+
+- **`skills/tamash-playwright/references/heal.md` never told the agent the Playwright HTML report exists at the point it matters.** It only pointed at `npx playwright show-report` at the very end (the REPORT step), after the loop was already finished — not right after RUN, where the report's per-attempt annotation and JSON attachment (provider, vision/action-recovery involvement, suggested selector, token cost, failure stage) would actually help decide what to do next. Found by directly auditing the skill against every documented user workflow step, not by running it. Fixed: RUN now explicitly says what the report contains and when it's worth opening.
+
+- **`doctor`'s connectivity check used a fixed 15s timeout, not the project's own `actionTimeout`.**
+  A project using `actionTimeout: 8000` could get `[OK] Connected successfully` from `doctor`, then
+  have its first real heal fail with a misleading "not authenticated?" warning: `claude-subscription`/
+  `copilot-subscription` spawn the vendor's CLI as a subprocess, and the first call in a process pays
+  a one-time cold-start cost on top of the model call, which the old 15s check absorbed but a smaller
+  `actionTimeout` does not. Found during a from-scratch setup walkthrough (see the skill entry
+  below). Fixed: `doctor` now tests connectivity within the project's real `actionTimeout` when one
+  is configured, falling back to the 15s default only when none is set. A `[FAIL]` for either
+  provider now names the cold-start cost as a possible cause. Verified against `copilot-subscription`
+  that the check uses the configured timeout.
+
+- **The published package was silently carrying stale, orphaned compiled output.** `npm run build`
+  (plain `tsc`, no `--build`/incremental mode) never deletes `dist/` output for a source file that
+  was later removed — found in the `0.11.0-beta.1` publish itself: `dist/healer/providers/
+  claude-cli.js`/`copilot-cli.js` shipped in the tarball with no corresponding source file
+  anywhere in the repo (from an abandoned, never-committed, never-wired-up piece of past work) —
+  dead code nothing actually imports, but real, needless bloat in every install. Fixed by cleaning
+  `dist/` automatically before every build (`prebuild` script), verified by confirming a full
+  rebuild no longer produces those two files.
+
+- **A popup/new tab opened via `context.waitForEvent('page')`, `page.on('popup', ...)`, or
+  `page.waitForEvent('popup')` was never healing-aware.** `bindContext`/`bindPageActions` already
+  made `context.newPage()`/`context.pages()`/`context.on('page', ...)` heal correctly, but these
+  three — including `context.waitForEvent('page')`, the pattern most commonly taught for popup
+  handling — fell through to a raw, unwrapped Playwright page. A broken locator inside the
+  resulting page just threw a plain timeout, with no `[self-healer]` line at all: healing was never
+  attempted, not just unsuccessful. Found while building the first-ever test for popup healing
+  (previously implemented with zero coverage); fixed by extending both bindings to wrap whatever
+  page these three hand back, the same way `newPage()` already did.
+
+- **`tamash` (the rule-based provider) declined on a real, common page pattern it should have
+  resolved.** A floating label rendered as its own text node right next to a field whose accessible
+  name is *also* that same text (confirmed on a real login page: a "Username" label next to a field
+  that's itself named "Username") was miscounted as two competing candidates and declined, even
+  though there's genuinely only one field. `findRuleBasedMatch` now only treats a match as a real
+  competing candidate when it's independently resolvable on its own (has a ref and a plausible
+  role) — a bare text node repeating the same words is decorative, not a second option. Genuine
+  ambiguity (two actually-independent candidates) still declines exactly as before.
+
+- **The HTML report's self-healing attachment was a wall of escape sequences on a failed
+  heal.** Playwright's own error messages embed ANSI colour codes in their "Call log" section;
+  the healer stored those raw in `report.reason` / `report.warning` / `attempts[].error`, and
+  `JSON.stringify` (which builds the `self-healing-<action>` attachment) escapes every ESC byte in the JSON, so a *not-healed* report rendered as unreadable escape soup. A
+  *successful* heal has short or absent error strings, which is why it only showed up on failures.
+  Fixed by stripping ANSI CSI sequences in `normalizeError` — the single point every captured
+  error passes through — so the attachment, the console line, and `heals.jsonl` are all plain
+  text. Verified against a real not-healed run.
+
+- **The three CLI-based subscription providers (`cursor-subscription`, `kiro-subscription`,
+  `codex-subscription`) were verified against their real vendor CLIs for the first time — and none
+  of the three actually worked as shipped.** Four separate bugs, all found by running them, all now
+  fixed:
+  1. **`cursor-subscription` never returned a heal.** `agent -p` refuses to run in any directory
+     without workspace trust — it prints "Workspace Trust Required" and exits without answering.
+     Now passes `--trust --mode ask`; `--mode ask` is Cursor's own read-only Q&A mode ("read-only"
+     per its `--help`), which *removes* the old "has access to all tools, could edit a file"
+     caveat this provider carried — a heal call in `ask` mode cannot write or run anything.
+  2. **`codex-subscription` refused to run outside a Git repository** ("Not inside a trusted
+     directory and --skip-git-repo-check was not specified"). Now passes `--skip-git-repo-check`;
+     this only relaxes the where-may-I-run guard, not the sandbox — `codex exec` still runs
+     `approval: never` + read-only, the property this provider depends on.
+  3. **`codex exec` hung on stdin.** It drains stdin ("Reading additional input from stdin…") and
+     blocks until EOF; `runCliPrompt` left the child's stdin as an open pipe, so every call ran to
+     the timeout and was killed — confirmed: a prompt the CLI answers in ~8s "timed out" at 15s.
+     `runCliPrompt` now gives every child an already-closed stdin (`stdio: ['ignore', …]`),
+     harmless for `agent`/`kiro-cli`, the fix for `codex`.
+  4. **The JSON parsers failed on conversational output.** `parseSuggestion` /
+     `parseVisionSuggestion` / `parseActionTacticSuggestion` extracted JSON from prose with a
+     greedy first-`{`-to-last-`}` slice, which breaks the moment the response contains more than
+     one JSON object — exactly what cursor's `agent` produces (it echoes the system prompt's
+     example objects back before its real answer). Replaced with a balanced-brace-span scan that
+     takes the last valid object (a model states its answer last), old greedy slice kept as a last
+     resort. Improves robustness for every provider, not just the CLI ones.
+
+  Verified, all authenticated: `doctor` reports `[OK] Connected` for all three; a real
+  `npx playwright test` heal (broken locator, cache cleared) went green with
+  `HEALED [provider=codex-subscription]`, and `kiro-subscription` healed the same spec.
+
+- **`cursor-subscription` reliability note.** Verifying it (see above) showed Cursor's `agent` CLI
+  is an interactive assistant rather than a one-shot completion endpoint — given the heal prompt it
+  often answers conversationally instead of with the required JSON, so the heal is declined more
+  often than with `kiro`/`codex`. It's now invoked in the safest/best-effort form
+  (`agent -p --trust --mode ask --output-format json`, read-only) and is marked **experimental**;
+  the docs point to `kiro`/`codex` as the steadier local-subscription options. Report issues.
+  Also: the full e2e healing suite (12 tests) was run end to end against `copilot-subscription` and
+  `ollama` — **12/12 each** — to confirm the parser rewrite and provider changes don't regress it.
+
+### Added
+
+- **`npx tamash-playwright init-skill` — one command to install the orchestration skill, plus a
+  `doctor` check that flags when it's missing or stale.** The skill this package ships
+  (`skills/tamash-playwright/`) was previously a copy-this-shell-one-liner-per-agent step buried in
+  `SKILL.md`, with nothing verifying it had been done — so a project could `npm install` the
+  package, never copy the skill, and its assistant would silently never load the workflow.
+  `init-skill` copies the skill (`SKILL.md` + `references/`) into **both** standard locations —
+  `.claude/skills/tamash-playwright/` (Claude Code) and `.agents/skills/tamash-playwright/` (the
+  emerging cross-tool standard, read by Cursor, GitHub Copilot, Windsurf, Kiro, Zed, dotnet Aspire,
+  … — the same convention Playwright's own `playwright-cli install --skills` uses). Same content in
+  both; no per-agent format conversion. `--target claude` / `--target agents` installs one; `--user`
+  installs under your home directory; `--force` overwrites a hand-edited copy; `--dry-run` previews.
+  Each install carries a `tamash-playwright-skill-version:` marker; `doctor`'s **Skill** section
+  reads it and reports `[OK]` current / `[WARN]` behind-the-package-version / `[INFO]` not-installed
+  or unmanaged, with the same one-line fix. Covered by unit tests (`skill.test.js`, real installs
+  into a temp dir) and verified end to end.
+
+  *(0.11.0-beta.7 shipped an earlier `init-skill` that instead auto-detected the agent and wrote a
+  Cursor-specific `.mdc` file / appended blocks to `.github/copilot-instructions.md` and
+  `AGENTS.md`. That approach is gone — `init-skill` and `doctor` now point out any such leftovers
+  from a beta.7 install so you can delete them by hand.)*
+
+- **`doctor`'s AI Provider check now tells you *what kind* of failure it hit and what to do about
+  it, instead of one generic "no valid response".** Every provider gained an optional, diagnostics-
+  only `diagnose()` method (never on the healing hot path) that runs one trivial round trip and
+  reports a structured category — `not-installed`, `not-authenticated`, `timeout`, `bad-model`,
+  `network`, `bad-response` — each of which `doctor` maps to a specific next step: the missing
+  `npm install`/CLI installer for a missing SDK; "run `claude login` / check your API key / confirm
+  your subscription is active and within quota" for a rejected request; "raise `actionTimeout`" (plus
+  the existing subprocess cold-start note) for a timeout; "check `<MODEL>` in your .env" for a
+  rejected model id; a network/proxy/base-URL hint for a connection failure. The raw error line is
+  still printed verbatim beneath the guidance. Previously `doctor` could only distinguish "worked"
+  from "didn't" — a missing SDK, an expired login, a slow network and a wrong model name all
+  produced the same line. Providers that don't implement `diagnose()` fall back to the old
+  `suggestSelector()` probe (worked/didn't, plus a timing-based timeout guess). Verified:
+  `openai` bad key -> `not-authenticated` (401 body shown), `openai` bad base URL -> `network`,
+  `copilot-subscription` bad model id -> `bad-model`, 1ms `actionTimeout` -> `timeout` with the
+  raise-the-timeout guidance, and all three not-installed shapes by moving the dependency out of
+  resolution and restoring it: `@github/copilot-sdk` (CJS `MODULE_NOT_FOUND`),
+  `@anthropic-ai/claude-agent-sdk` (ESM `ERR_MODULE_NOT_FOUND`), and a missing `kiro-cli` binary
+  (`ENOENT`) -- each surfacing `not-installed` with its exact install command.
+
+- **Three new local-development-only subscription providers: `cursor-subscription`,
+  `kiro-subscription`, `codex-subscription`.** Extends the same "use what you're already paying
+  for" idea `claude-subscription`/`copilot-subscription` already give, to three more real
+  subscriptions — but each is explicitly scoped to local development, never documented or
+  recommended for CI, for two genuinely different reasons found by checking real vendor docs before
+  writing any code. Cursor's and Kiro's own headless-mode docs confirm neither has a way to fully
+  disable tool/file/command access the way `claude-subscription`'s `tools: []`/`copilot-subscription`'s
+  `availableTools: []` do — Cursor's `agent -p` "has access to all tools" by its own docs, and Kiro's
+  headless mode requires `--trust-all-tools`/`--trust-tools` specifically because there's no one to
+  approve a tool call unattended; `kiro-subscription` deliberately never grants that trust, so a
+  tool-requiring response just times out and declines rather than being granted broad access.
+  `codex-subscription` is local-only for a different, simpler reason: `codex exec` (used here, not
+  the interactive REPL) defaults to a read-only sandbox with no approval prompts — already as safe
+  as the two existing subscription providers — but no long-lived, subscription-only token for
+  unattended CI use is confirmed to exist for it yet. None of the three vendors ship a Node SDK, so
+  all three are `child_process` wrappers around the vendor's own CLI binary (`agent`, `kiro-cli`,
+  `codex`) via a new shared `runCliPrompt` helper, rather than the SDK-based design the existing two
+  use — meaning every call pays a fresh process-spawn cost, not just the first the way
+  `copilot-subscription`'s warm shared client does; `doctor` now has a distinct hint explaining this
+  when one of these three fails within a tight `actionTimeout`. Investigated and explicitly ruled
+  out this round: Antigravity — its dedicated `google-antigravity` SDK is Python-only (this is a
+  Node/TypeScript package), has no documented tool-restricted mode at all, and its authentication
+  story isn't published, so it isn't even confirmed to ride on an existing subscription. Verified:
+  real graceful-decline behavior confirmed against genuinely uninstalled CLIs (no fabricated
+  simulation), and the full `doctor` integration (including the new every-call-cost hint) confirmed
+  against a real sample repo. **Not yet verified**: the actual happy path against a real installed
+  and authenticated CLI for any of the three — none were available in the development environment,
+  and all three require a real paid subscription account.
+
+- **A skill for running this package's local workflow inside an AI coding assistant.** Ships at
+  `skills/tamash-playwright/` — a `SKILL.md` entry point that branches on `npx tamash-playwright
+  doctor`'s actual output (never assumed), plus two reference docs: `onboarding.md` (bringing a
+  project up to standard — provider setup, `actionTimeout`, `.describe()` labels, Page Object
+  extraction) and `heal.md` (a gated review/apply/verify/land loop over `apply-heals` and
+  `verify-heals.cjs` — most runs proceed start to finish unattended, pausing only for a genuinely
+  ambiguous fix or anything after a failed verification, and never landing/committing/opening a PR
+  without asking first, no matter how clean the run was). Pure orchestration over commands that
+  already exist — no new healing capability. Ships with adapters for Claude Code, Kiro (identical
+  `SKILL.md` format, confirmed against Kiro's own docs), Cursor (`.mdc` rule), GitHub Copilot
+  (`copilot-instructions.md` section), and an `AGENTS.md` covering the broader cross-tool standard
+  (Antigravity, Gemini CLI, Windsurf, Zed, Aider, and others) — none of which are auto-discovered
+  from `node_modules` by any of these tools, confirmed rather than assumed, so every adapter's
+  install step is one explicit copy command, documented in `SKILL.md` itself.
+- **A new `tamash` heal provider — rule-based healing, no AI at all.** `HEALER_PROVIDER=tamash`
+  needs no API key, no subscription, and makes no network call: it resolves a broken locator by
+  text-matching the same description an AI provider would receive (`.describe()`, or a decoded
+  variable name — see below) against the already-captured accessibility snapshot, then reuses the
+  exact same structural widening (`near`/`adjacent`) the AI-backed path already uses once it finds
+  the right anchor — same output shape, same downstream code, zero duplicated logic. It shares the
+  same non-negotiable discipline as every text-matching step in this package: zero or more than one
+  match, at any point, means it declines rather than guesses — verified with a dedicated permanent
+  e2e suite covering direct matches, widened matches, and every decline path (including the known,
+  accepted limitation that a misleading type hint can't be second-guessed against). Genuinely a
+  different tool than the AI providers, not a free replacement for one: no vision fallback (nothing
+  to reason over a screenshot with) and no action-recovery tactics (those require understanding
+  *why* an action failed, which is inference this provider deliberately doesn't attempt) — a fast,
+  free, fully deterministic first line of defense, best suited to well-`.describe()`d,
+  Page-Object-style suites.
+- **A new `ollama-local` heal provider for self-hosted Ollama servers.** `HEALER_PROVIDER=ollama-local`
+  targets your own `ollama serve` instance or an internal company deployment, instead of Ollama
+  Cloud — a deliberately separate provider from `ollama`, not a flag on it, since the two have
+  genuinely different auth defaults: Ollama Cloud always requires `OLLAMA_API_KEY`, while
+  `OLLAMA_LOCAL_API_KEY` is optional, since a bare `ollama serve` has no authentication at all. Set
+  it only if your internal deployment sits behind a reverse proxy or API gateway that requires a
+  bearer token — verified against a real HTTP server both ways, confirming the `Authorization`
+  header is omitted entirely when no key is set, and sent correctly when one is. Prompted by a real
+  support request from a team wanting to use their own internally-hosted `gpt-oss:120b`.
+- **Undescribed, POM-style locator variables now get a real description automatically.** When
+  `.describe()` was never called, the healer already fell back to the locator's own variable/
+  property name (`txtEmployeeId`) as its best guess at intent — now that raw identifier is decoded
+  into the same kind of human-readable phrase `.describe()` would give: `txtEmployeeId` becomes
+  "Employee Id (textbox)", `submitButton` becomes "Submit (button)", recognizing both prefix-style
+  (`btnSubmit`) and suffix-style (`submitBtn`) naming, camelCase/snake_case/kebab-case, and correct
+  acronym boundaries (`employeeIDNumber` → "Employee ID Number"). Falls back to the raw identifier,
+  exactly as before, whenever nothing meaningful survives decoding (a placeholder name like `el1`,
+  or a bare affix with nothing else) — never a guess dressed up as a real description. Verified
+  live against a real, unpublished build in both sample repos (a real `copilot-subscription` call,
+  and — after finding and fixing a genuinely stale API key along the way — a real `ollama` call),
+  confirming the decoded description actually reaches the configured AI provider unchanged.
+
+## [0.10.0] - 2026-08-27
+
+### Fixed
+
+- **`waitFor()` is never sent to the AI.** It's a state check, not an action — a timeout on it can
+  mean a genuinely broken selector, or it can mean the element correctly never reached the expected
+  state (verifying something does NOT appear, or a real app issue), and there's no way to tell those
+  apart from the error alone. `expect(locator).toBeVisible()` was already permanently excluded from
+  healing for exactly this reason, but never reached this code at all (a separate path from the
+  Proxy-intercepted actions) — `waitFor` just never got the same treatment. Real, reported case: a
+  user's `waitFor` on a locator verifying an absence (where timing out was the *correct* outcome)
+  still burned 8175 tokens across a failed text attempt and a failed vision attempt before giving
+  up, for a heal that could never have succeeded. Now fails fast with a clear `state-wait-not-healed`
+  stage and zero AI calls; a real action (fill/click/...) on the same kind of broken locator is
+  unaffected.
+- **`claude-subscription` used more tokens than necessary.** The SDK's `effort` option defaults to
+  `'high'` when left unset, and this provider never set it — a small prompt-complexity increase (the
+  `nearbyRef`/`nearbyText` addition below) pushed adaptive thinking higher for a task that only needs
+  to return one line of JSON. Output tokens for the same heal ranged 188-445 before, 422-881 after,
+  across real CI runs. `thinking: { type: 'disabled' }` + `effort: 'low'` fixes this: a steady 28-30
+  output tokens, below the original baseline, with no change to correctness.
+- **The primary ariaSnapshot capture no longer requests `boxes:true`.** Every node was paying for a
+  `[box=x,y,w,h]` annotation that nothing on the text/`ref` path (including the `nearbyRef`/
+  `adjacent`-strategy widening logic below) ever reads — it's purely topological. The one real
+  consumer (vision's own nearest-candidate lookup) already captures its own separate, fresh
+  snapshot, so this is genuinely free: verified, input tokens dropped ~23% on a large real
+  page (3794 → 2937) with no loss of accuracy, and no change on small pages (box overhead scales
+  with node count).
+
+### Added
+
+- **Search-scoped snapshots**: before falling back to the full page, the healer now searches the
+  already-captured snapshot for the description's identifying phrase and, only when it matches
+  exactly one node, sends the AI a scoped excerpt (that node's own subtree plus every sibling
+  branch's subtree at each ancestor level up to the root) instead of the whole page — zero extra
+  browser round-trips, since it's pure processing on data already in memory. Falls back to the full
+  snapshot automatically whenever the search is empty or ambiguous, never a guess. Verified across
+  several real cases: 41% token reduction on a deeply-nested field,
+  66% when the target was inside what looked like an unrelated navigation menu (proving it finds
+  wherever the relevant text actually is, not "excludes the nav"), ~29% on a pair of identical
+  sibling fields that still had to be correctly disambiguated, and a clean, correct fallback when
+  the description doesn't match the page's real text at all.
+- **A new `adjacent` selector strategy**, fixing a real ambiguity in the existing `near` strategy:
+  when two fields with no identity of their own share a row/section (two dropdowns side by side,
+  say), `near`'s "climb to a shared ancestor, then search it for any element of this role"
+  approach matches both and gives up rather than risk the wrong one. The AI's `ref` response can
+  now optionally report `nearbyRef`/`nearbyText`/`nearbyRole` for a nameless target it identified;
+  `deriveDurableLocator` uses that hint to find the true common ancestor between the target and
+  its label — via each ref's own full ancestor chain, not by assuming either sits at a matching
+  depth — and, when they're proven to be immediate sibling branches, builds a precise CSS
+  `:text() + *` sibling match (or an xpath climb-then-step, when the label text turns out to be
+  nested below its own branch root). Verified against a real configured provider, resolving
+  the correct field and never its same-row neighbor in both directions.
+- **Full attempt-history logging**: `SelfHealingReport` now carries an `attempts[]` array — one
+  entry per cache/ref/text/vision/action-recovery attempt actually made, each with its own
+  `succeeded`/`stage`/`error`. Previously only the *last* attempt's stage survived; an earlier
+  attempt's real failure (and the specific error it threw) was silently discarded the moment a
+  later attempt also failed — the exact shape of a real user-reported bug, where a genuine
+  candidate selector was shown next to an unrelated `vision_provider_error` with no way to tell
+  why the candidate itself hadn't worked. The attempt history now also prints directly to
+  console/CI output (not just the JSON attachment) whenever more than one attempt was made, on
+  both pass and fail — since that plain-text output is what most bug reports actually paste, not
+  an attachment nobody opens.
+- **`ariaSnapshot` is attached to the test report on failure** — the exact accessibility tree the
+  AI reasoned over, so a confusing report can be diagnosed against real evidence instead of a
+  separately-captured DevTools screenshot.
+
+## [0.9.0] - 2026-08-26
+
+### Fixed
+
+- **Heal-log visibility**: a heal with no reusable selector (a one-shot `ref` resolution, or a
+  vision-tagged point) was silently dropped from `heals.jsonl` entirely, even though it genuinely
+  fixed that run. Now logged for audit — with a clear `reviewNote` — whenever it has a suggestion
+  *or* a review note, without letting an audit-only entry shadow an older, real cached fix for the
+  same location.
+- **Vision support for `claude-subscription`/`copilot-subscription`**: both providers had
+  `supportsVision` hardcoded to `false` regardless of model. Both SDKs genuinely support image
+  input (Claude Agent SDK via an image content block; Copilot SDK via a `blob` attachment) —
+  implemented for real and verified with actual screenshots, not just doctor's yes/no label.
+- **Argument forwarding in healed replays**: `replayAction()` only ever forwarded the first call
+  argument. A trailing options object (`click({ modifiers: [...] })`, `fill(value, { timeout })`,
+  `dispatchEvent`'s 3rd argument) was silently dropped on a healed replay — changing the action's
+  real behavior while still reporting a clean `HEALED`.
+- **`ref`-strategy replays now act through the derived durable locator, not the raw ref**:
+  `aria-ref=` locators never resolve for `dispatchEvent` at all (a Playwright-level limitation,
+  confirmed directly via `DEBUG=pw:api`), even though the identical element resolves instantly via
+  a `normalize()`-derived locator for that same action. Fixed by deriving the durable locator
+  *before* replaying and acting through it, falling back to the raw ref only when nothing durable
+  could be found. A related accuracy bug is fixed alongside it: the report/heal-log could
+  previously claim a derived selector "worked" even when its own replay had actually failed and a
+  fallback silently took over — now only the locator that genuinely performed the action is
+  reported or cached.
+- **`copilot-subscription` could hang a non-Playwright test runner indefinitely.** Its shared
+  client keeps a connection open across calls for performance; Playwright's own test runner
+  force-exits regardless, but a runner like Cucumber does not, so the process never returns even
+  after every test has passed. `closeCopilotSubscriptionClient()` is now exported from the
+  package's own entry point so a non-Playwright consumer can call it from their own teardown hook
+  (e.g. Cucumber's `AfterAll`).
+
+### Added
+
+- **`locator.getDurable(action?)`** — resolves any locator (most usefully one built from
+  `aria-ref=...`) to a durable, reusable equivalent (`getByRole`/`getByLabel`/a css selector/…),
+  using the same derivation logic self-healing already uses internally. Throws if nothing durable
+  could be derived, rather than silently handing back something untrusted.
+- **`apply-heals` now previews before writing**: every run — dry or real — shows a styled table of
+  exactly what it found (location, before, after, review status) instead of a plain scrolling log.
+  A real run also asks for confirmation before writing anything, but *only* at a genuine
+  interactive terminal — CI and any non-interactive/piped invocation proceed automatically exactly
+  as before, so no existing unattended CI workflow is affected. `--yes`/`-y` skips the prompt at a
+  real terminal too.
+- **`doctor`'s output is styled** with colors and tables (including a new end-of-run Summary
+  section) instead of a plain scrolling log.
+- **Exact locator code in console lines and reports**: a healed suggestion is now shown as the
+  real, copy-pasteable Playwright call (`getByRole("textbox", { name: "Username" })`) instead of
+  an abbreviated shorthand (`role:textbox:Username`) — the same code `apply-heals` would write to
+  source, so what you see is never a lossier stand-in for what was actually used.
+- A canonical Page Object Model usage example (`tests/pages/` +
+  `tests/example-orangehrm-add-employee.spec.ts`), verified against a real OrangeHRM demo,
+  including a genuine self-heal via the `near`/widening strategy on a real unlabeled field.
+
+### Changed
+
+- README/usage.md's vision-fallback documentation now correctly lists `claude-subscription`/
+  `copilot-subscription` as vision-capable (with a suitable model), not just the API-key providers.
+
+## [0.8.0] - 2026-08-25
+
+### Added
+
+- `claude-subscription` and `copilot-subscription` heal providers — self-healing backed by a
+  personal Claude or GitHub Copilot subscription instead of a pay-per-token API key, working both
+  locally and unattended in CI (`CLAUDE_CODE_OAUTH_TOKEN` for Claude; the ambient `GITHUB_TOKEN` or
+  a personal-account PAT for Copilot on GitHub Actions).
+
+### Fixed
+
+- Missing CLI install step in setup docs for `claude-subscription`/`copilot-subscription` — the
+  standalone `claude`/`copilot` CLIs are genuinely required for the login step even though the SDKs
+  don't need them installed to function at runtime.
+
+### Documentation
+
+- The org-vs-personal-account Copilot licensing gotcha in CI (a repo owned by an organization
+  without its own Copilot enablement can't use a personal subscription via the ambient token).
+- Action Recovery (`HEALER_ACTION_RECOVERY_ENABLED`) hidden from docs and `doctor` output —
+  disabled by default already; this only reduced its visibility, no behavior change.
+
+## [0.7.0] - 2026-08-21
+
+### Added
+
+- `apply-heals` — turns a runtime heal into a permanent source-code fix, plus an opportunistic
+  cache (`heals.jsonl`) so a previously-confirmed selector is tried before a fresh AI call, and
+  history archival so a run's report/log isn't silently overwritten by the next one.
+- Position/relationship-based locator strategies (`near`, `scoped`, `containing`) for elements with
+  no accessible identity of their own.
+- Self-healing rebuilt around `ariaSnapshot({ mode: 'ai' })` + `aria-ref=` resolution and
+  `Locator.normalize()`, replacing pixel-distance guessing for both the text path and the vision
+  fallback's durability upgrade.
+- A real unit test suite (32 tests at the time, zero new dependencies).
+
+### Fixed
+
+- `doctor`'s `actionTimeout` check being fooled by a commented-out config value.
+- `apply-heals --logs-dir` silently losing raw heal-log archival.
+- `apply-heals` only replacing the first call when re-healing an already-`near`-fixed line.
+- `apply-heals` `ENOENT` on a fresh CI checkout with no `.tamash-playwright/` directory yet — the
+  sharded "apply-heals" CI job checks out fresh and has never run tests itself, so the directory
+  genuinely doesn't exist there the way it always does in every local recipe.
+- File path corruption (and a `require()` crash in the generated verification script) for ESM
+  (`"type": "module"`) consumer projects — `Error.stack` renders as a `file://` URL there, which
+  broke path resolution and a plain `.js` verification script alike.
+- The AI being misled by the broken selector still present in its own prompt context; a failed
+  label guess now auto-upgrades to a structural `near` match instead of giving up.
+
+### Verified
+
+- All four API-key providers (Ollama, OpenAI, Anthropic, Gemini) confirmed working with real API
+  calls, not just documented.
+
+## [0.6.0] - 2026-08-17
+
+### Added
+
+- iframe and popup healing, vision fallback (screenshot-based recovery when text alone isn't
+  enough), AI-driven action recovery (scroll/force/wait/dispatch), and source-location reporting.
+- `doctor`'s `actionTimeout` configuration check.
+
+### Initial release
+
+- Self-healing Playwright bindings: broken locators are recovered at runtime via an AI provider,
+  with `.describe()` for human-readable context.